---
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 or fails.

## Payload

- OutgoingPaymentWebhook
  - `timestamp` string, date-time, required — ISO8601 timestamp when the webhook was sent (can be used to prevent replay attacks)
  - `webhookId` string, required — Unique identifier for this webhook delivery (can be used for idempotency)
  - `type` 'INCOMING_PAYMENT' | 'OUTGOING_PAYMENT' | 'TEST' | 'BULK_UPLOAD' | 'INVITATION_CLAIMED' | 'KYC_STATUS' | 'ACCOUNT_STATUS', required — Type of webhook event, used by the receiver to identify which webhook is being received
  - `transaction` OutgoingTransaction, required
    - `id` string, required — Unique identifier for the transaction
    - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction
    - `type` 'INCOMING' | '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
    - `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. Only applicable for transactions to/from UMA addresses.
    - `source` union, required
      - AccountTransactionSource — Source account details
        - `currency` string — Currency code for the source
        - `sourceType` 'ACCOUNT', required
        - `accountId` string, required — Source account identifier
      - UmaAddressTransactionSource — UMA address source details
        - `currency` string — Currency code for the source
        - `sourceType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the sender
    - `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).
    - `quoteId` string — The ID of the quote that was used to trigger this payment
    - `originalTransactionId` string — ID of the original transaction that this transaction is retrying, if applicable
    - `paymentInstructions` PaymentInstructions[], required — 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
        - PaymentClabeAccountInfo
          - `accountType` 'CLABE', required
          - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard)
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentUsAccountInfo
          - `accountType` 'US_ACCOUNT', required
          - `accountNumber` string, required — US bank account number
          - `routingNumber` string, required — ACH routing number (9 digits)
          - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings)
          - `bankName` string — Name of the bank
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentPixAccountInfo
          - `accountType` 'PIX', required
          - `pixKey` string, required — PIX key for Brazilian instant payments
          - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used
          - `taxId` string, required — Tax ID of the account holder
        - PaymentIbanAccountInfo
          - `accountType` 'IBAN', required
          - `iban` string, required — International Bank Account Number
          - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters)
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentUpiAccountInfo
          - `accountType` 'UPI', required
          - `vpa` string, required — Virtual Payment Address for UPI payments
        - 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
    - `refund` Refund
      - `reference` string, required — The unique reference code of the refund
      - `initiatedAt` string, date-time, required — When the refund was initiated
      - `settledAt` string, date-time — When the refund was or will be settled
    - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote.
      - `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' | 'TIMEOUT' — 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 webhookId)

---

[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/9ae8cc2fa307/schema)