---
title: "Outgoing payment status webhook"
method: POST
path: "outgoing-payment"
tags: ["Webhooks"]
---

# Outgoing payment status webhook

`POST outgoing-payment` (webhook)

Webhook that is called when an outgoing payment's status changes.
This endpoint should be implemented by clients of the Grid API.

### Authentication
The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
To verify the signature:
1. Get the Grid public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

This webhook is informational only and is sent when an outgoing payment completes successfully, fails, or is refunded.

## Payload

- OutgoingPaymentWebhook
  - `id` string, required — Unique identifier for this webhook delivery (can be used for idempotency)
  - `type` 'OUTGOING_PAYMENT.PENDING' | 'OUTGOING_PAYMENT.PROCESSING' | 'OUTGOING_PAYMENT.COMPLETED' | 'OUTGOING_PAYMENT.FAILED' | 'OUTGOING_PAYMENT.EXPIRED' | 'OUTGOING_PAYMENT.REFUND_PENDING' | 'OUTGOING_PAYMENT.REFUND_COMPLETED' | 'OUTGOING_PAYMENT.REFUND_FAILED', required — Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status.
  - `timestamp` string, date-time, required — ISO 8601 timestamp of when the webhook was sent
  - `data` OutgoingTransaction, required
    - `id` string, required — Unique identifier for the transaction
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `EXPIRED` | Quote wasn't executed before expiry window | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | Payout successfully reached the destination | | `FAILED` | Something went wrong — accompanied by a `failureReason` |
    - `type` 'OUTGOING', required — Type of transaction (incoming payment or outgoing payment)
    - `direction` 'CREDIT' | 'DEBIT', required — Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `accountId` string, required — Destination account identifier
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `umaAddress` string, required — UMA address of the recipient
    - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming)
    - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
    - `settledAt` string, date-time — When the payment was or will be settled
    - `createdAt` string, date-time — When the transaction was created
    - `updatedAt` string, date-time — When the transaction was last updated
    - `receiptDeliveryConfirmedAt` string, date-time — The time at which the platform confirmed delivery of the receipt to their customer.
    - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.
    - `description` string — Optional memo or description for the payment
    - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
    - `source` union, required
      - AccountTransactionSource — Source account details
        - `sourceType` 'ACCOUNT', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `accountId` string, required — Source account identifier
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides.
        - `sourceType` 'REALTIME_FUNDING', required — Type of transaction source
        - `currency` string, required — Currency code for the funding source
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `accountHolderName` string — The name of the originator (sender) of the payment.
        - `accountIdentifier` string — The originator's account number or IBAN. May be masked or partial depending on the rail.
        - `bankName` string — The name of the originating bank.
        - `bankIdentifier` string — The identifier of the originating bank, such as a routing number, BIC, or SWIFT code.
        - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | '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' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
        - `remittanceInformation` string — Free-form information about the payment provided by the originator. The source field depends on the payment rail: the Addenda record for ACH, the OBI / beneficiary information for wires, and the remittanceInformation field for RTP and FedNow.
        - `endToEndId` string — The originator's own end-to-end reference for the payment.
        - `traceNumber` string — Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation.
    - `sentAmount` CurrencyAmount, required
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `receivedAmount` CurrencyAmount
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `exchangeRate` number — Number of sending currency units per receiving currency unit.
    - `fees` integer — The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
    - `reconciliationInstructions` ReconciliationInstructions
      - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
      - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available.
    - `quoteId` string — The ID of the quote that was used to trigger this payment
    - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. — unresolved $ref
    - `refund` Refund
      - `reference` string, required — The unique reference ID of the refund
      - `initiatedAt` string, date-time, required — When the refund was initiated
      - `settledAt` string, date-time — When the refund was settled
      - `status` 'PENDING' | 'COMPLETED' | 'FAILED', required — Current status of the refund
      - `reason` 'TRANSACTION_FAILED' | 'USER_CANCELLATION' | 'TIMEOUT' — Reason for the refund
    - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.
      - `counterpartyMultiplier` number, double, required — The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution.
      - `counterpartyFixedFee` integer, required — The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents).
      - `gridApiMultiplier` number, double, required — The underlying multiplier from the sending currency to mSATS, including variable fees.
      - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents).
      - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount.
      - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate.
    - `failureReason` 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' | 'LIGHTNING_PAYMENT_FAILED' | 'FUNDING_AMOUNT_MISMATCH' | 'COUNTERPARTY_POST_TX_FAILED' — Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted.
    - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | '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' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
    - `railSelectionMode` 'AUTO' | 'MANUAL' — How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it.
    - `expectedSettlementAt` string, date-time, nullable — Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved.
    - `settlementTimelineSeconds` integer, nullable — Expected number of seconds from quote creation to settlement. Null when not yet known.

## Acknowledgement `200`

Webhook received successfully

## Other responses

- `400` — Bad request
- `401` — Unauthorized - Signature validation failed
- `409` — Conflict - Webhook has already been processed (duplicate id)

---

[API](https://skmtc.dev/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/8165d5121244/schema)