---
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)
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required
        - `accountId` string, required — Destination account identifier
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required
        - `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
    - `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
        - `accountId` string, required — Source account identifier
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
        - `sourceType` 'REALTIME_FUNDING', required
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `currency` string, required — Currency code for the funding source
    - `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.
      - `instructionsNotes` string — Additional human-readable instructions for making the payment
      - `isPlatformAccount` boolean — Indicates whether the account is a platform account or a customer account.
      - `accountOrWalletInfo` union, required
        - PaymentUsdAccountInfo
          - `accountType` 'USD_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `routingNumber` string, required — The ABA routing number
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBrlAccountInfo
          - `accountType` 'BRL_ACCOUNT'
          - `qrCode` string, required — A PIX QR code payload that can be used to fund the transaction. This can be rendered as a QR code image or pasted into a PIX-compatible banking app.
        - PaymentMxnAccountInfo
          - `accountType` 'MXN_ACCOUNT', required
          - `clabeNumber` string, required — The CLABE number of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentDkkAccountInfo
          - `accountType` 'DKK_ACCOUNT', required
          - `iban` string, required — Danish IBAN (18 characters, starting with DK)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentEurAccountInfo
          - `accountType` 'EUR_ACCOUNT', required
          - `iban` string, required — The IBAN of the bank account
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentInrAccountInfo
          - `accountType` 'INR_ACCOUNT', required
          - `vpa` string, required — The UPI Virtual Payment Address
          - `paymentRails` string[], required
        - PaymentNgnAccountInfo
          - `accountType` 'NGN_ACCOUNT', required
          - `accountNumber` string, required — Nigerian bank account number
          - `bankName` string, required — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentCadAccountInfo
          - `accountType` 'CAD_ACCOUNT', required
          - `bankCode` string, required — Canadian financial institution number (3 digits)
          - `branchCode` string, required — Transit number identifying the branch (5 digits)
          - `accountNumber` string, required — Bank account number (7-12 digits)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGbpAccountInfo
          - `accountType` 'GBP_ACCOUNT', required
          - `sortCode` string, required — The UK sort code
          - `accountNumber` string, required — UK bank account number (8 digits)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentHkdAccountInfo
          - `accountType` 'HKD_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Hong Kong bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentIdrAccountInfo
          - `accountType` 'IDR_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Indonesian bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `phoneNumber` string, required — Indonesian phone number for e-wallet payments
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentMyrAccountInfo
          - `accountType` 'MYR_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Malaysian bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentPhpAccountInfo
          - `accountType` 'PHP_ACCOUNT', required
          - `bankName` string, required — Name of the beneficiary's bank
          - `accountNumber` string, required — Bank account number
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSgdAccountInfo
          - `accountType` 'SGD_ACCOUNT', required
          - `bankName` string, required — Name of the beneficiary's bank
          - `accountNumber` string, required — Bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentThbAccountInfo
          - `accountType` 'THB_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Thai bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentVndAccountInfo
          - `accountType` 'VND_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Vietnamese bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentAedAccountInfo
          - `accountType` 'AED_ACCOUNT', required
          - `iban` string, required — UAE IBAN (23 characters, starting with AE)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentKesAccountInfo
          - `accountType` 'KES_ACCOUNT', required
          - `phoneNumber` string, required — Kenyan mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentMwkAccountInfo
          - `accountType` 'MWK_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentRwfAccountInfo
          - `accountType` 'RWF_ACCOUNT', required
          - `phoneNumber` string, required — Rwandan mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentTzsAccountInfo
          - `accountType` 'TZS_ACCOUNT', required
          - `phoneNumber` string, required — Tanzanian mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentUgxAccountInfo
          - `accountType` 'UGX_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentXofAccountInfo
          - `accountType` 'XOF_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `region` 'BJ' | 'CI' | 'SN' | 'TG', required — Country code within the West African CFA franc zone
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentZarAccountInfo
          - `accountType` 'ZAR_ACCOUNT', required
          - `accountNumber` string, required — South African bank account number
          - `bankName` string, required — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentZmwAccountInfo
          - `accountType` 'ZMW_ACCOUNT', required
          - `phoneNumber` string, required — Zambian mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBwpAccountInfo
          - `accountType` 'BWP_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentXafAccountInfo
          - `accountType` 'XAF_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `region` 'CM' | 'CG', required — Country code within the Central African CFA franc zone
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBdtAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'BDT_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `branchCode` string — The branch code
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `phoneNumber` string — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentArsAccountInfo
          - `accountType` 'ARS_ACCOUNT', required
          - `accountNumber` string, required — The static CVU (Clave Virtual Uniforme) bank account number to pay to.
        - PaymentCopAccountInfo
          - `accountType` 'COP_ACCOUNT'
          - `paymentUrl` string, uri, required — A payment URL where the customer can complete their COP deposit.
        - PaymentEgpAccountInfo
          - `accountType` 'EGP_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — The account number of the bank
          - `iban` string — Egyptian IBAN (29 characters, starting with EG)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGhsAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'GHS_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `phoneNumber` string — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGtqAccountInfo
          - `accountType` 'GTQ_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentHtgAccountInfo
          - `accountType` 'HTG_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentJmdAccountInfo
          - `accountType` 'JMD_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `branchCode` string, required — The branch code
          - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentPkrAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: bankName, phoneNumber
          - `accountType` 'PKR_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `iban` string — Pakistani IBAN (24 characters, starting with PK)
          - `phoneNumber` string — The phone number in international format
          - `bankName` string — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSlvAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankAccountType, accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'SLV_ACCOUNT', required
          - `bankName` string — The name of the bank (BANK_TRANSFER only)
          - `accountNumber` string — The account number of the bank (BANK_TRANSFER only)
          - `bankAccountType` 'CHECKING' | 'SAVINGS' — The bank account type (BANK_TRANSFER only)
          - `phoneNumber` string — The phone number in international format (MOBILE_MONEY only — e.g. Tigo Money)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSparkWalletInfo
          - `accountType` 'SPARK_WALLET', required
          - `address` string, required — Spark wallet address
          - `assetType` 'BTC' | 'USDB', required — Type of asset
          - `invoice` string — Invoice for the payment
        - PaymentLightningInvoiceInfo
          - `accountType` 'LIGHTNING'
          - `invoice` string, required — Invoice for the payment
        - PaymentSolanaWalletInfo
          - `accountType` 'SOLANA_WALLET', required
          - `address` string, required — Solana wallet address
          - `assetType` 'USDC' | 'USDT' — Type of asset
        - PaymentTronWalletInfo
          - `accountType` 'TRON_WALLET', required
          - `address` string, required — Tron wallet address
          - `assetType` 'USDT' — Type of asset
        - PaymentPolygonWalletInfo
          - `accountType` 'POLYGON_WALLET', required
          - `address` string, required — Polygon eth wallet address
          - `assetType` 'USDC' — Type of asset
        - PaymentBaseWalletInfo
          - `accountType` 'BASE_WALLET', required
          - `address` string, required — Base eth wallet address
          - `assetType` 'USDC' — Type of asset
        - PaymentEthereumWalletInfo
          - `accountType` 'ETHEREUM_WALLET', required
          - `address` string, required — Ethereum L1 wallet address
          - `assetType` 'USDC' — Type of asset
        - PaymentEmbeddedWalletInfo
          - `accountType` 'EMBEDDED_WALLET', required — Discriminator value identifying this as Embedded Wallet payment instructions.
          - `payloadToSign` string, required — JSON-encoded transaction signing payload that must be stamped, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting Turnkey API-key stamp is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet.
    - `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.

## 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/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)