Look up a claim

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>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({claimToken: '<string>'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"claimToken\": \"<string>\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/lookup")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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": "+639171234567",
    "email": "maria@example.com",
    "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"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

POST

claimable-payouts

claim

lookup

Look up a claim

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>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({claimToken: '<string>'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"claimToken\": \"<string>\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/lookup")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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": "+639171234567",
    "email": "maria@example.com",
    "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"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

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

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.

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

Using the API

API documentation

Look up a claim

Authorizations

Body

Response