Look up a claim

The claimable payout a claim token is for, as the platform’s claim page needs it. The page should show the recipient only senderName and amount until she has entered a one-time code sent to recipient.phoneNumber or recipient.email, so that a forwarded link alone cannot claim the payout. A token that matches no payout, or one that was replaced, is answered with 404.

POST /claimable-payouts/claim/lookup

Look up a claim

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/lookup \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimToken": "<string>"
}
'

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

Response

200

application/json

Successful operation

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