Sent when a Grid payout is processing, completed, failed, refunded or expired
Grid Payout Status Webhook
A Grid payout sends money from your USDC account to a recipient's bank account abroad. It has two parts:
- The funding transfer. USDC leaves your account on-chain. You already receive the usual
ON_CHAIN_WITHDRAWAL_*webhooks for it. - The payout itself. Grid delivers the money to the recipient. This webhook tells you how that part is going.
GRID_PAYOUT_STATUS_UPDATED is sent each time a payout reaches a new status. It is delivered to the /tx endpoint appended to your Webhook URL, the same TRANSACTION channel as transaction status updates. Filter on the type field.
Statuses
status | Meaning |
|---|---|
PROCESSING | The payout was executed and Grid is delivering it. |
COMPLETED | Grid delivered the money to the recipient. settledAt is set. |
FAILED | The payout failed. gridFailureReason says why, when Grid gives a reason. |
REFUNDED | Grid returned the money, for example after the recipient bank rejected it. It can follow COMPLETED. |
EXPIRED | The quote expired before the payout was funded. |
PENDING and PENDING_2FA_CONFIRMATION are internal steps before any money moves. They are never sent.
On sandbox, a payout Grid returns ends asFAILED. Sandbox has noREFUNDEDstatus.
Semantics
- One webhook per status. Each status of a payout is sent once.
- Never backwards. You will not receive
PROCESSINGafter a final status, orCOMPLETEDafterREFUNDED. - At least once. In rare recovery cases a status can arrive twice. Deduplicate on
id+status. - Delivery can be delayed. If a webhook could not be stored when the status changed, it is resent within a few minutes.
- The current status is always available. Call
POST /grid/payouts/getwith the payout'sid. Use it if you think you missed an update.
Linking to the funding withdrawal
The payout's fundingTransactionId is the id of the on-chain withdrawal that funds it, as it appears on that withdrawal's ON_CHAIN_WITHDRAWAL_* webhooks. Those webhooks also carry a gridPayout object naming the payout. See Crypto Deposit/Withdrawal Webhooks.
Payload
The body is the payout, in the same shape as POST /grid/payouts/list and POST /grid/payouts/get, plus uid, type and ts. Empty fields are omitted. All amounts are strings in the smallest unit of their currency.
| Field | Description |
|---|---|
uid | Unique id of this webhook delivery |
type | Always GRID_PAYOUT_STATUS_UPDATED |
id | Id of the payout, as returned when you created it |
status | The status this webhook reports (table above) |
accountId | The USDC account that funded the payout |
syncedOwnerId | Owner of that account |
beneficiaryId | The recipient. Join against POST /grid/beneficiaries/list. |
sendingAmount | USDC sent, in cents |
sendingCurrency | USDC |
receivingAmount | Amount for the recipient, in the smallest unit of receivingCurrency |
receivingCurrency | The recipient's currency |
exchangeRate | Rate of the quote |
fees | Fees included in the quote, in USD cents |
feeEstimate | Striga fee breakdown applied on top of the quote |
description | The description you gave the payout |
fundingTransactionId | id of the on-chain withdrawal funding the payout. It changes if funding is retried. |
txHash | On-chain hash of the funding transfer, once available |
paymentRail | Rail you pinned when creating the payout, if any |
gridPaymentRail | Rail Grid used |
gridFailureReason | Grid's reason, on FAILED and on some REFUNDED payouts. Seen so far: COUNTERPARTY_POST_TX_FAILED, QUOTE_EXECUTION_FAILED, QUOTE_EXPIRED. |
gridRefundReason | Grid's reason for returning a settled payout, for example TRANSACTION_FAILED |
createdAt | When the payout was created |
settledAt | When Grid delivered the payout |
ts | Delivery timestamp (milliseconds) |
Completed
{
"uid": "5d1c2b3a-4f5e-4a6b-8c7d-9e0f1a2b3c4d",
"type": "GRID_PAYOUT_STATUS_UPDATED",
"id": "0f6b3f8e-9d2a-4f27-9f0f-2a2f0b0a1c33",
"status": "COMPLETED",
"accountId": "8a7b6c5d4e3f20112233445566778899",
"syncedOwnerId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"beneficiaryId": "9c9c8d5f-1204-4a30-ae40-aa951f0ae5b3",
"sendingAmount": "250000",
"sendingCurrency": "USDC",
"receivingAmount": "250000",
"receivingCurrency": "USD",
"exchangeRate": 1,
"fees": 0,
"description": "Invoice 1042",
"paymentRail": "WIRE",
"gridPaymentRail": "WIRE",
"fundingTransactionId": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"createdAt": "2026-09-02T14:05:10.112Z",
"settledAt": "2026-09-02T18:41:37.540Z",
"ts": 1788374497612
}Failed
{
"uid": "7e6d5c4b-3a2f-4e1d-9c0b-8a7f6e5d4c3b",
"type": "GRID_PAYOUT_STATUS_UPDATED",
"id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
"status": "FAILED",
"accountId": "8a7b6c5d4e3f20112233445566778899",
"syncedOwnerId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"beneficiaryId": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"sendingAmount": "120400",
"sendingCurrency": "USDC",
"receivingAmount": "2000000",
"receivingCurrency": "MXN",
"exchangeRate": 16.65,
"fees": 47,
"description": "Payout to Empresa S.A. de C.V.",
"gridFailureReason": "COUNTERPARTY_POST_TX_FAILED",
"createdAt": "2026-09-03T09:12:44.008Z",
"ts": 1788427366250
}
