Skip to main content
Claimable payouts are off by default. To request access, reach out to your Lightspark contact.
A claimable payout lets an agent send money from its customer’s Embedded Wallet to someone who has no Grid account. The agent names the recipient’s phone number or email. You send the recipient a link, she chooses how to receive the money from what Grid pays out to in her country, and Grid pays her from the customer’s wallet.

​
The hold

Grid holds the amount from the moment the payout is created. The funds stay in the customer’s wallet, but quotes and card payments from that wallet cannot spend the held amount, and the payout counts toward the agent’s spending limits like a send of the same amount. Grid releases the hold when the payout expires, is cancelled or rejected, or fails.

​
Prerequisites

  • Claimable payouts enabled for your platform, alongside the agents API.
  • An agent whose policy grants CREATE_QUOTES, EXECUTE_QUOTES and MANAGE_EXTERNAL_ACCOUNTS, with a delegated key on the customer’s Embedded Wallet.
  • A customer whose KYC status is APPROVED.

​
Lifecycle

1

The agent sends the payout

The agent calls POST /agents/me/claimable-payouts. Grid evaluates it against the agent’s policy as a payout to a bank account, so it may need the customer’s approval as a CLAIMABLE_PAYOUT agent action.
2

You send the recipient a link

Once the payout is AWAITING_CLAIM, your backend calls POST /claimable-payouts/{claimablePayoutId}/claim-token and sends the recipient a link to your claim page carrying the token. Grid keeps only the token’s hash. Issuing another token, for a reminder, replaces the earlier one.
3

The recipient proves she holds the link

Your claim page calls POST /claimable-payouts/claim/lookup with the token. Show her only the sender’s name and the amount until she enters a one-time code you send to the payout’s phone number or email, so a forwarded link alone cannot claim it.
4

She chooses how to be paid

POST /claimable-payouts/claim/options lists the currencies and rails Grid pays out to in her country, priced for the payout.
5

Grid locks a quote to her account

POST /claimable-payouts/claim/quote takes her account details and chosen rail, validates and screens them, saves her as an external account under the sender’s customer, and locks a quote.
6

She confirms

POST /claimable-payouts/claim/confirm pays her on that quote. The payout is CLAIMED, then PAID or FAILED.
Grid fires CLAIMABLE_PAYOUT.CLAIMED, CLAIMABLE_PAYOUT.PAID, CLAIMABLE_PAYOUT.EXPIRED and CLAIMABLE_PAYOUT.FAILED so you can tell the sender. A payout not claimed within 7 days of approval expires. The agent can cancel a payout until it is claimed with POST /agents/me/claimable-payouts/{claimablePayoutId}/cancel. Because the recipient is saved as an external account, the agent can pay her again later as a saved recipient, without a link.