Deferred payout

Overview

Deferred payout splits the journey across two flows:

Slug	Who	Role
`deferred-payout-origination`	Sender	Compose corridor, amount, and funding method, then share a claim link
`payout-claim`	Recipient	Open the claim link, choose payout, bind, and create the operation

Use this when the beneficiary should receive funds after the sender has committed, without both parties finishing in the same session. Minting an origination freezes the send commitment (amount, corridor, funding method). It does not create a money-transfer operation. The operation is created when the recipient binds on payout-claim.

Do not treat origination as “funds now.” Card and ACH debit the sender at bind. Cash at store (CASH_DEPOSIT) can only mint a barcode after bind, when an operation exists and is waiting for funding.

Happy path

Sender widget after mint: share / copy the claim URL (cash also shows how-to-deposit copy; pay-at-store is not available yet). Recipient widget: if the origination is still takeable and the sender is CIP-verified, show the intention (“Receive”). Otherwise show that the claim is no longer available (same screen for several reasons — see Claim blocked).

Sender identity (CIP)

The sender User (partnerId + origination referenceId) owns CIP. The recipient does not complete the sender’s KYC.

Moment	Allowed sender `cipStatus`
Mint claim link (after CIP UI)	`pending`, `manual_review`, or `verified` (`failed` is rejected)
Open / bind payout-claim	`verified` required

On claim/session, the payout-claim widget reads live config.senderCipStatus (and bindingState). If the sender is not verified, the recipient is sent to the unavailable screen before they can choose a payout. Kentucky approval only counts once the CIP webhook updates that User in this backend. A ticket approved in Kentucky against another environment leaves senderCipStatus: pending and the claim stays blocked.

Funding variants

The funding method is chosen on origination and stored on sendCommitment. Payout is chosen on claim.

Funding	At origination	At bind	Pay at store
Card / ACH (pull)	Instrument (or rail) committed	Sender is charged; operation created	—
`CASH_DEPOSIT` (push)	Method committed; no barcode	Operation created and parks awaiting funding	Sender hub shows Pay at store / Deposit only when `operationId` exists and `fundingStatus` is `awaiting_funding` or `barcode_issued`

Cash at store on deferred payout is not a standalone cash-deposit origination. After bind, the sender widget mints an operation_payment cash-deposit link for that operation (stores + barcode), same pattern as other cash-funded operations.

Integrate

Exact bodies: OpenAPI (CreateDeferredPayoutOriginationLinkDto, CreatePayoutClaimLinkDto, widget deferred-payout routes). Mint a sender hub. After the sender finishes compose + CIP UI, the platform mints payout-claim and returns the share URL.

curl -X POST https://raas-widgets-backend-sandbox.up.railway.app/partner/links \
  -H "X-API-Key: raas_sandbox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "sender_user_123",
    "flow": "deferred-payout-origination",
    "expiresInMinutes": 120,
    "language": "es"
  }'

Optional config can prefill user data and corridor pins (same general shape as send).

2. You distribute the claim link

POST /partner/links with flow: "payout-claim" when your integration owns claim distribution. See OpenAPI for required fields (existing originationId, or senderReferenceId + sendCommitment so the backend mints the origination).

3. M2M create

POST /v1/deferred-payout still originates + mints a claim link. Prefer widget + Partner links for new work; see Pre-quote lite for the stance on /v1/*.

Binding states and webhooks

payment_bound → awaiting_claim → payout_bound → executable → (operation terminal)
                     ↓
              expired | cancelled

`bindingState`	Meaning
`payment_bound`	Origination saved; claim link not attached yet
`awaiting_claim`	Claim link minted; recipient has not bound
`payout_bound` / `executable`	Bind in progress / operation exists
`expired`	Claim TTL elapsed before bind
`cancelled`	Partner cancel or sender blocked before claim

Event	When
`deferred_payout.created`	Origination first persisted (`payment_bound` / `awaiting_claim`)
`deferred_payout.updated`	Later `bindingState` or `operationId` change
`operation.created`	Successful bind
`operation.completed` / `failed` / `cancelled`	Operation lifecycle

Payloads: Webhook events. Cancel

Before claim (payment_bound / awaiting_claim): POST /partner/deferred-payouts/:originationId/cancel (revokes the claim link).
After bind: sender cancels the operation from the origination link (POST /widget/links/:linkId/operations/:operationId/cancel), same window as send. There is no widget cancel for an unclaimed origination.

Partner portal: list / detail / cancel under deferred payouts.

Claim blocked

The recipient UI uses one unavailable title (“this claim is no longer available”). Triggers include:

Cause	Typical signal
Sender CIP not `verified`	Claim `config.senderCipStatus` is `pending` or `manual_review`
Already bound	`bindingState` `payout_bound` or `executable`
Expired / cancelled	`expired`, `cancelled`, or claim `410` / `409`
Someone else occupied the link	Occupancy after auth (`other_occupant`)

Inspect POST /widget/links/:linkId/claim → data.config.bindingState and data.config.senderCipStatus. Do not assume Kentucky UI “approved” until that field is verified. Bind can still return SENDER_IDENTITY_PENDING / SENDER_IDENTITY_FAILED if CIP changes between splash and commit.

Resource	Purpose
`POST /partner/links`	Mint origination (and optionally claim) links
`GET` / `POST /partner/deferred-payouts`	Ops list, detail, cancel
Widget `…/deferred-payout*`	Pre-quote, quote, bind on the claim link

Next steps

Flows catalog

How flows fit in the platform.

Cash deposit

Standalone and operation_payment cash links (used after deferred cash bind).

Webhook events

deferred_payout.* and operation.*.

Operations

Query operations after claim.

Getting Started

Request API

Concepts

Integration

Flows

Webhooks

Operations

Overview

Happy path

Sender identity (CIP)

Funding variants

Integrate

1. Widget (typical)

2. You distribute the claim link

3. M2M create

Binding states and webhooks

Claim blocked

Next steps

Flows catalog

Cash deposit

Webhook events

Operations

​Overview

​Happy path

​Sender identity (CIP)

​Funding variants

​Integrate

​1. Widget (typical)

​2. You distribute the claim link

​3. M2M create

​Binding states and webhooks

​Claim blocked

​Related Partner resources

​Next steps

Flows catalog

Cash deposit

Webhook events

Operations

Overview

Happy path

Sender identity (CIP)

Funding variants

Integrate

1. Widget (typical)

2. You distribute the claim link

3. M2M create

Binding states and webhooks

Claim blocked

Related Partner resources

Next steps