Confirm a claim

Pay a claimable payout on the locked quote from POST /claimable-payouts/claim/quote. The payout becomes CLAIMED, and Grid signs the payout from the sender’s wallet with the agent’s delegated key; it becomes PAID when the payout completes, or FAILED. A quote that has expired is refused with QUOTE_EXPIRED: request another. Confirming a payout already CLAIMED or PAID on the same quote returns it unchanged.

POST /claimable-payouts/claim/confirm

Confirm a claim

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/confirm \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimToken": "<string>",
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}
'

200

{
  "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
  "status": "PENDING_APPROVAL",
  "senderName": "Kevin",
  "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",
  "note": "Happy birthday, Mom",
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "paymentRail": "ACH",
  "failureReason": "INSUFFICIENT_FUNDS"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

application/json

claimToken · string · required

The claim token from the recipient's link.

Required string length: 1 - 128

quoteId · string · required

The quote from POST /claimable-payouts/claim/quote.

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"

Response

200

application/json

Claim confirmed

A claimable payout as its claim token shows it to the platform. Show the recipient no more than senderName and amount until she has proved she holds recipient.phoneNumber or recipient.email.

id · string · required

The claimable payout's identifier.

Example:

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

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

senderName · string · required

The sender's first name, from their verified identity.

Example:

"Kevin"

amount · object · required

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

When the claim window ends.

Example:

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

note · string

The sender's note to the recipient.

Example:

"Happy birthday, Mom"

receivedAmount · object

What the recipient receives. Present once she has a locked quote.

Show child attributes

paymentRail · enum<string>

The rail the recipient chose. Present once she has a locked quote.

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