Send a claimable payout

Send money from the agent’s customer’s Embedded Wallet to a person by phone number or email. The recipient needs no Grid account: she claims the payout from a link the platform sends her, choosing how to receive it from what Grid pays out to in her country, and Grid pays her from the customer’s wallet.

Grid holds amount against the wallet’s balance and the agent’s spending limits from creation. Funds do not leave the wallet until the recipient claims; while the payout is held, quotes and card payments from the wallet cannot spend the held amount. The hold is released when the payout expires, is cancelled or rejected, or fails.

The request is evaluated against the agent’s policy as a send of the same amount to a bank account: it needs the EXECUTE_QUOTES permission, counts toward the spending limits, and needs the customer’s approval above the policy’s approval threshold or its spending pool’s approvalThreshold, in APPROVAL_REQUIRED mode, or above the platform’s limit for bank payouts without approval. A payout that needs approval is created PENDING_APPROVAL with a CLAIMABLE_PAYOUT agent action, and the AGENT_ACTION.PENDING_APPROVAL webhook fires; approving the action makes it AWAITING_CLAIM. Otherwise it is created AWAITING_CLAIM. Then issue the recipient’s link with POST /claimable-payouts/{claimablePayoutId}/claim-token.

Available only where the platform enables claimable payouts and agent bank payouts, for a customer whose KYC status is APPROVED.

POST /agents/me/claimable-payouts

Send a claimable payout

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "amount": 5000,
  "recipient": {
    "name": "Maria",
    "phoneNumber": "[phone]",
    "email": "[e-mail]",
    "country": "PH"
  },
  "note": "Happy birthday, Mom"
}
'

201

{
  "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "status": "PENDING_APPROVAL",
  "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "amount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "recipient": {
    "name": "Maria",
    "phoneNumber": "[phone]",
    "email": "[e-mail]",
    "country": "PH"
  },
  "expiresAt": "2025-10-10T15:00:00Z",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z",
  "note": "Happy birthday, Mom",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "externalAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "paymentRail": "ACH",
  "failureReason": "INSUFFICIENT_FUNDS"
}

Authorizations

Authorization · string · header · required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key · string · required

A unique identifier for the request, scoped to the agent. A retry with the same key returns the payout the first request created.

Maximum string length: 255

Example:

"<uuid>"

Body

application/json

A claimable payout an agent sends from its customer's Embedded Wallet.

sourceAccountId · string · required

The customer's EMBEDDED_WALLET internal account to pay from.

Example:

"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

amount · integer<int64> · required

The amount to send, in the smallest unit of the source account's currency.

Required range: x <= 9000000000000000

Example:

5000

recipient · object · required

The person a claimable payout is for. Exactly one of phoneNumber and email is set: the one-time code that proves the recipient holds the link goes there.

Show child attributes

note · string

A note for the recipient, shown once she has proved she holds the link.

Maximum string length: 140

Example:

"Happy birthday, Mom"

Response

201

application/json

Claimable payout created

Money an agent sends to a person by phone number or email, for her to claim from a link. Grid holds amount against the sender's Embedded Wallet balance and the agent's spending limits; the funds stay in the wallet until the recipient claims and Grid pays her from it.

id · string · required

System-generated unique identifier.

Example:

"ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077"

agentId · string · required

The agent that sent the payout.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

customerId · string · required

The sender, the agent's customer.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

platformCustomerId · string · required

Platform-specific ID of the sender.

Example:

"user-a1b2c3"

status · enum<string> · required

Status of a claimable payout. Grid holds the amount against the sender's Embedded Wallet balance and the agent's spending limits from creation until the payout is PAID, or releases it when the payout ends in any other status.

Status	Description
PENDING_APPROVAL	Waiting for the customer to approve the agent's request. No claim token can be issued yet
AWAITING_CLAIM	Approved; the recipient can claim it with a claim token until expiresAt
CLAIMED	The recipient confirmed a locked quote and Grid is paying her
PAID	The payout reached the recipient's account
EXPIRED	Not claimed by expiresAt, or not approved in time. The hold is released
CANCELLED	Cancelled by the agent, or rejected by the customer. The hold is released
FAILED	The payout could not be made; see failureReason. The hold is released

Available options: PENDING_APPROVAL, AWAITING_CLAIM, CLAIMED, PAID, EXPIRED, CANCELLED, FAILED

sourceAccountId · string · required

The sender's EMBEDDED_WALLET internal account the payout is paid from.

Example:

"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

amount · object · required

The amount held and sent, in the source account's currency.

Show child attributes

recipient · object · required

The person a claimable payout is for. Exactly one of phoneNumber and email is set: the one-time code that proves the recipient holds the link goes there.

Show child attributes

expiresAt · string<date-time> · required

While PENDING_APPROVAL, the end of the approval window; from AWAITING_CLAIM, when the claim window ends, 7 days after approval. A payout not PAID by then, and not being paid, expires and its hold is released.

Example:

"2025-10-10T15:00:00Z"

createdAt · string<date-time> · required

When the agent sent the payout.

Example:

"2025-10-03T15:00:00Z"

updatedAt · string<date-time> · required

When the payout last changed.

Example:

"2025-10-03T15:02:00Z"

note · string

The sender's note to the recipient.

Maximum string length: 140

Example:

"Happy birthday, Mom"

agentActionId · string

The CLAIMABLE_PAYOUT agent action the customer approves or rejects.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

externalAccountId · string

The external account Grid saved under the sender's customer for the recipient's payout details. Present once the recipient has claimed. An agent can pay it again as a saved recipient.

Example:

"ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

transactionId · string

The outgoing transaction that paid the recipient. Present once Grid sends the payout.

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000030"

receivedAmount · object

What the recipient receives, in her currency. Present once she has a locked quote.

Show child attributes

paymentRail · enum<string>

The rail the recipient chose. Present once she has claimed.

Available options: ACH, ACH_COLOMBIA, ACH_SAME_DAY, BANK_TRANSFER, BRE_B, CIPS, FAST, FASTER_PAYMENTS, FEDNOW, INSTAPAY, MOBILE_MONEY, NEFT, PAYNOW, PESONET, PIX, RTGS, RTP, SEPA, SEPA_INSTANT, SPEI, SWIFT, UNIONPAY, UPI, WIRE

Example:

"ACH"

failureReason · enum<string>

Present only when status is FAILED.

Available options: INSUFFICIENT_FUNDS, RECIPIENT_REFUSED, AGENT_INACTIVE, PAYOUT_FAILED