---
title: "Agent action pending approval webhook"
method: POST
path: "agent-action"
tags: ["Webhooks"]
---

# Agent action pending approval webhook

`POST agent-action` (webhook)

Fired when an agent submits an action that requires platform approval before Grid will execute it. Use this to send a push notification to the customer so they can review and approve or reject the action in your app.
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.

The payload contains the full `AgentAction` — including the embedded quote or transfer details — so you can render the approval UI without a second API call. Approve or reject via `POST /agents/{agentId}/actions/{actionId}/approve` or `POST /agents/{agentId}/actions/{actionId}/reject`.

## Payload

- AgentActionWebhook
  - `id` string, required — Unique identifier for this webhook delivery (can be used for idempotency)
  - `type` 'AGENT_ACTION.PENDING_APPROVAL', 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` AgentAction, required — An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.
    - `id` string, required — System-generated unique identifier for this action.
    - `agentId` string, required — The agent that submitted this action.
    - `customerId` string, required — The customer on whose behalf the action was submitted.
    - `platformCustomerId` string, required — Platform-specific ID of the customer.
    - `status` 'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED' | 'FAILED', required — Status of an agent action. | Status | Description | |--------|-------------| | `PENDING_APPROVAL` | Submitted by the agent, awaiting platform approval before execution | | `APPROVED` | Approved by the platform; execution is in progress or completed | | `REJECTED` | Rejected by the platform; the underlying transaction was not executed | | `FAILED` | Approved but execution failed (e.g. quote expired, insufficient funds) |
    - `type` 'EXECUTE_QUOTE' | 'TRANSFER_OUT' | 'TRANSFER_IN', required — The type of action the agent is requesting. | Type | Description | |------|-------------| | `EXECUTE_QUOTE` | Execute a cross-currency quote | | `TRANSFER_OUT` | Transfer from an internal account to an external account | | `TRANSFER_IN` | Transfer from an external account to an internal account |
    - `quote` Quote
      - `id` string, required — Unique identifier for this quote
      - `status` 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Current status of the quote. `PENDING_AUTHORIZATION` occurs only for customers in a region where Strong Customer Authentication is required (e.g. EU): the quote carries an `scaChallenge` that must be authorized before execution, and for realtime-funding sources `paymentInstructions` are withheld until it is satisfied.
      - `createdAt` string, date-time, required — When this quote was created
      - `expiresAt` string, date-time, required — Absolute UTC timestamp when the rate locked in this quote becomes invalid and the quote can no longer be executed. The window depends on the rail and corridor: instant rails (Lightning, Spark, USDC on Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5 minutes; corridors with longer settlement guarantees may have longer windows. Always rely on this timestamp rather than assuming a fixed window.
      - `source` union, required
        - AccountQuoteSource — Source account details
          - `sourceType` 'ACCOUNT', required — Type of quote funding source
          - `accountId` string, required — Source account identifier
          - `customerId` string — Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated. Otherwise, will default to the customerId of the account owner.
        - RealtimeFundingQuoteSource — Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.).
          - `sourceType` 'REALTIME_FUNDING', required — Type of quote funding source
          - `customerId` string — Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself.
          - `currency` string, required — Currency code for the funding source. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
          - `cryptoNetwork` string — The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `TRON`, `PLASMA`, `SPARK`, `LIGHTNING`, `BITCOIN`.
      - `destination` union, required
        - AccountDestination — Destination account details
          - `destinationType` 'ACCOUNT', required — Type of payment destination
          - `accountId` string, required — Destination account identifier
          - `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 to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail.
        - UmaAddressDestination — UMA address destination details
          - `destinationType` 'UMA_ADDRESS', required — Type of payment destination
          - `umaAddress` string, required — UMA address of the recipient
          - `currency` string — Currency code for the destination. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
      - `sendingCurrency` 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
      - `receivingCurrency` 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
      - `totalSendingAmount` integer, required — The total amount that will be sent in the smallest unit of the sending currency (eg. cents).
      - `totalReceivingAmount` integer, required — The total amount that will be received in the smallest unit of the receiving currency (eg. cents).
      - `exchangeRate` number, required — Number of sending currency units per receiving currency unit.
      - `feesIncluded` integer, required — The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.
      - `platformFeesIncluded` integer — The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. May be omitted from payloads produced before platform fees existed.
      - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. This is not required when using an internal account source. — unresolved $ref
      - `transactionId` string, required — The ID of the transaction created from this quote.
      - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
      - `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.
      - `scaChallenge` ScaChallenge — A Strong Customer Authentication challenge that must be satisfied before a money-movement operation can complete. This object is **only present when the customer is in a region where SCA is required** (the EU); for customers outside SCA-regulated regions it is omitted entirely and no action is needed. When present on a quote, authorize it by submitting an `ScaAuthorization` proof to `POST /quotes/{quoteId}/authorize`. **A single operation may require more than one authorization, in sequence.** Treat `scaChallenge` as *the challenge to satisfy now*, not "the only one". After each authorize, re-inspect the returned quote/transaction: if it is still `PENDING_AUTHORIZATION`, it carries the **next** `scaChallenge` (a new `id`) — authorize that too, and repeat until it leaves `PENDING_AUTHORIZATION`. Do not assume one authorization releases the transfer. The number of authorizations is flow-dependent and **may decrease in future**: for example, a cross-currency send today authorizes the currency conversion and the payout as two separate challenges; a future update may collapse them into one. A client written to loop on status handles any count unchanged.
        - `id` string, required — Unique identifier for this challenge. The server resolves the active challenge from the quote or transaction being authorized, so this field need not be supplied back; it is informational (e.g. for logging or correlation).
        - `expiresAt` string, date-time, required — Absolute UTC timestamp after which this challenge can no longer be authorized.
        - `factor` 'SMS_OTP' | 'TOTP' | 'PASSKEY', required — A Strong Customer Authentication factor. | Factor | Description | |--------|-------------| | `SMS_OTP` | One-time code sent by SMS to the customer's verified phone. Requires no prior enrollment. | | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). | | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. |
        - `availableFactors` ScaFactor[], required — The factors the customer may use to satisfy this challenge.
        - `purpose` string, nullable — Optional, informational label for what this particular challenge in the sequence authorizes — useful for step UX (e.g. "Authorize the currency conversion" vs "Authorize the payout"). Known values include `CURRENCY_CONVERSION`, `PAYOUT`, and `TRANSFER`, but the set is **non-exhaustive and may grow** — treat unrecognized values as a generic authorization step and do not branch program logic on it. Omitted when steps are not distinguished (e.g. a single-authorization flow).
        - `passkeyAssertionOptions` object, nullable — Opaque WebAuthn assertion request options (including the relying-party id, challenge, and allowed credentials), present only when `factor` is `PASSKEY`. Pass to the device's WebAuthn API to produce the assertion submitted back in `ScaAuthorization.passkeyAssertion`.
        - `passkeyAllowedOrigins` string[], nullable — The origins the WebAuthn ceremony may run against. Populated for enrollment and login passkey challenges; the origin the assertion is produced against must be one of these and echoed back as `ScaAuthorization.origin`. Per-transaction passkey challenges omit this (they carry `passkeyAssertionOptions` only) — see `ScaAuthorization.origin` for how to source the origin in that case.
    - `transferDetails` AgentTransferDetails — Details of a transfer-type agent action (TRANSFER_OUT or TRANSFER_IN).
      - `amount` integer, required — Transfer amount in the smallest unit of the specified currency.
      - `currency` string, required — ISO 4217 currency code for the transfer amount.
      - `sourceAccountId` string, required — ID of the source account (internal or external).
      - `destinationAccountId` string, required — ID of the destination account (internal or external).
    - `transaction` union
      - IncomingTransaction
        - `id` string, required — Unique identifier for the transaction
        - `status` 'CREATED' | 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU); authorize the transaction's `scaChallenge` to proceed. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired |
        - `type` 'INCOMING', 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
            - `onChainTransaction` OnChainTransaction
              - …
          - 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 this transaction belongs to
        - `platformCustomerId` string, required — Platform-specific ID of the customer this transaction belongs to
        - `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
        - `sentAmount` 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.
        - `quoteId` string — The ID of the quote that was used to trigger this payment
        - `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
        - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
        - `source` union
          - AccountTransactionSource — Source account details
            - `sourceType` 'ACCOUNT', required — Type of transaction source
            - `currency` string — Currency code for the source
            - `accountId` string, required — Source account identifier
            - `onChainTransaction` OnChainTransaction
              - …
          - 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.
            - `onChainTransaction` OnChainTransaction
              - …
        - `receivedAmount` 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
        - `fees` integer — The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents).
        - `reconciliationInstructions` ReconciliationInstructions — Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead.
          - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
          - `transactionHash` string — Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination.
        - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — Reason for failure of an incoming 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.
      - OutgoingTransaction
        - `id` string, required — Unique identifier for the transaction
        - `status` 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU); authorize the transaction's `scaChallenge` to proceed. | | `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
            - `onChainTransaction` OnChainTransaction
              - …
          - 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 this transaction belongs to
        - `platformCustomerId` string, required — Platform-specific ID of the customer this transaction belongs to
        - `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
        - `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
        - `exchangeRate` number — Number of sending currency units per receiving currency unit.
        - `quoteId` string — The ID of the quote that was used to trigger this payment
        - `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
        - `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
            - `onChainTransaction` OnChainTransaction
              - …
          - 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.
            - `onChainTransaction` OnChainTransaction
              - …
        - `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
        - `fees` integer — The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
        - `platformFees` integer — The portion of `fees` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `fees`.
        - `reconciliationInstructions` ReconciliationInstructions — Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead.
          - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
          - `transactionHash` string — Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination.
        - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. — unresolved $ref
        - `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' | 'SCA_NOT_COMPLETED' | 'EXECUTION_FAILED_POST_DEBIT' | 'SETTLEMENT_FAILED' | 'TIMEOUT' | 'MANUAL_REFUND' — 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. `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live.
        - `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.
      - CardTransaction — Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the `pullSummary`, `refundSummary`, and `settlementSummary` aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition.
        - `type` 'CARD', required — Discriminator identifying this transaction as a card transaction in the `Transaction` list.
        - `id` string, required — System-generated unique card transaction identifier
        - `cardId` string — The id of the `Card` this transaction was made on.
        - `customerId` string, required — System ID of the customer (cardholder) this transaction belongs to.
        - `platformCustomerId` string, required — Platform-specific ID of the customer (cardholder) this transaction belongs to.
        - `issuerTransactionToken` string — Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks.
        - `status` 'AUTHORIZED' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'REFUNDED' | 'EXCEPTION', required — Lifecycle status of a card transaction. | Status | Description | |--------|-------------| | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. | | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). | | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. | | `REFUNDED` | A `RETURN` was received from the merchant; the net settled amount has been refunded in part or whole. | | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. |
        - `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.
        - `merchant` CardMerchant, required
          - `descriptor` string, required — Merchant descriptor string captured from the card network at authorization time.
          - `mcc` string — Merchant Category Code (ISO 18245) — four-digit numeric string.
          - `country` string — Two-letter ISO 3166-1 alpha-2 country code of the merchant.
        - `authorizedAmount` 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
        - `settledAmount` 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
        - `refundedAmount` 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
        - `accountId` string, required — Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time).
        - `pullSummary` CardPullSummary
          - `count` integer, required — Total number of pulls (debits) executed against the funding source for this transaction. `> 1` indicates one or more post-hoc pulls — e.g. restaurant tip / over-auth clearings.
          - `totalAmount` integer, required — Sum of all pull amounts in the smallest unit of the funding source's currency.
          - `pendingCount` integer — Number of pulls still in the `PENDING` state. Drops to zero when every pull has reached a terminal state. Non-zero values that persist beyond the expected settlement window are an early signal for the `EXCEPTION` path.
        - `refundSummary` CardRefundSummary
          - `count` integer, required — Number of refund (return) events received for this transaction.
          - `totalAmount` integer, required — Sum of all refund amounts in the smallest unit of the funding source's currency.
        - `settlementSummary` CardSettlementSummary
          - `count` integer, required — Number of settlement (clearing) events received for this transaction.
          - `totalAmount` integer, required — Sum of all settled amounts in the smallest unit of the funding source's currency.
        - `authorizedAt` string, date-time, required — When the auth was approved.
        - `lastEventAt` string, date-time — Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction.
        - `createdAt` string, date-time, required — Creation timestamp (same as `authorizedAt` for card transactions).
        - `updatedAt` string, date-time, required — Last update timestamp.
    - `rejectionReason` string — Human-readable reason provided by the platform when rejecting the action. Only present when status is `REJECTED`.
    - `createdAt` string, date-time, required — When the action was submitted by the agent.
    - `updatedAt` string, date-time, required — When the action was last updated.

## Acknowledgement `200`

Webhook received and acknowledged.

## Other responses

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

---

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