Cancel a claimable payout

Cancel a claimable payout the authenticated agent sent that is PENDING_APPROVAL or AWAITING_CLAIM, releasing its hold. Its claim link stops working. Cancelling a payout already CANCELLED returns it unchanged; one the recipient has claimed, or that has ended otherwise, is refused with 409.

POST /agents/me/claimable-payouts/{claimablePayoutId}/cancel

Cancel a claimable payout

cURL

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

200

{
  "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": "[phone]",
    "email": "[e-mail]",
    "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"
}

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

200

application/json

Claimable payout cancelled

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.

id · 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