Grid Payout Status Webhook

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:

  1. The funding transfer. USDC leaves your account on-chain. You already receive the usual ON_CHAIN_WITHDRAWAL_* webhooks for it.
  2. 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

statusMeaning
PROCESSINGThe payout was executed and Grid is delivering it.
COMPLETEDGrid delivered the money to the recipient. settledAt is set.
FAILEDThe payout failed. gridFailureReason says why, when Grid gives a reason.
REFUNDEDGrid returned the money, for example after the recipient bank rejected it. It can follow COMPLETED.
EXPIREDThe 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 as FAILED. Sandbox has no REFUNDED status.

Semantics

  • One webhook per status. Each status of a payout is sent once.
  • Never backwards. You will not receive PROCESSING after a final status, or COMPLETED after REFUNDED.
  • 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/get with the payout's id. 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.

FieldDescription
uidUnique id of this webhook delivery
typeAlways GRID_PAYOUT_STATUS_UPDATED
idId of the payout, as returned when you created it
statusThe status this webhook reports (table above)
accountIdThe USDC account that funded the payout
syncedOwnerIdOwner of that account
beneficiaryIdThe recipient. Join against POST /grid/beneficiaries/list.
sendingAmountUSDC sent, in cents
sendingCurrencyUSDC
receivingAmountAmount for the recipient, in the smallest unit of receivingCurrency
receivingCurrencyThe recipient's currency
exchangeRateRate of the quote
feesFees included in the quote, in USD cents
feeEstimateStriga fee breakdown applied on top of the quote
descriptionThe description you gave the payout
fundingTransactionIdid of the on-chain withdrawal funding the payout. It changes if funding is retried.
txHashOn-chain hash of the funding transfer, once available
paymentRailRail you pinned when creating the payout, if any
gridPaymentRailRail Grid used
gridFailureReasonGrid's reason, on FAILED and on some REFUNDED payouts. Seen so far: COUNTERPARTY_POST_TX_FAILED, QUOTE_EXECUTION_FAILED, QUOTE_EXPIRED.
gridRefundReasonGrid's reason for returning a settled payout, for example TRANSACTION_FAILED
createdAtWhen the payout was created
settledAtWhen Grid delivered the payout
tsDelivery 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
}