Send a claimable payout

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": "+639171234567",
    "email": "maria@example.com",
    "country": "PH"
  },
  "note": "Happy birthday, Mom"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceAccountId: 'InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123',
    amount: 5000,
    recipient: {
      name: 'Maria',
      phoneNumber: '+639171234567',
      email: 'maria@example.com',
      country: 'PH'
    },
    note: 'Happy birthday, Mom'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts', 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  \"sourceAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\",\n  \"amount\": 5000,\n  \"recipient\": {\n    \"name\": \"Maria\",\n    \"phoneNumber\": \"+639171234567\",\n    \"email\": \"maria@example.com\",\n    \"country\": \"PH\"\n  },\n  \"note\": \"Happy birthday, Mom\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .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": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

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

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

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

Agent Operations

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, 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

claimable-payouts

Send a claimable payout

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": "+639171234567",
    "email": "maria@example.com",
    "country": "PH"
  },
  "note": "Happy birthday, Mom"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceAccountId: 'InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123',
    amount: 5000,
    recipient: {
      name: 'Maria',
      phoneNumber: '+639171234567',
      email: 'maria@example.com',
      country: 'PH'
    },
    note: 'Happy birthday, Mom'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts', 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  \"sourceAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\",\n  \"amount\": 5000,\n  \"recipient\": {\n    \"name\": \"Maria\",\n    \"phoneNumber\": \"+639171234567\",\n    \"email\": \"maria@example.com\",\n    \"country\": \"PH\"\n  },\n  \"note\": \"Happy birthday, Mom\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/claimable-payouts")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .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": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

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

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

{
  "code": "SERVICE_UNAVAILABLE",
  "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.

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

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.

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

Send a claimable payout

Authorizations

Headers

Body

Response