Get a claimable payout

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts/{claimablePayoutId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts/{claimablePayoutId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

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

{
  "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": {}
}

GET

agents

claimable-payouts

{claimablePayoutId}

Get a claimable payout

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts/{claimablePayoutId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts/{claimablePayoutId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

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

{
  "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

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.

Path Parameters

claimablePayoutId

string

required

Unique identifier of the claimable payout

Response

Successful operation

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.

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

Using the API

API documentation

Get a claimable payout

Authorizations

Path Parameters

Response