---
title: "Approve a pending incoming payment"
method: POST
path: "/transactions/{transactionId}/approve"
tags: ["Transactions"]
---

# Approve a pending incoming payment

`POST /transactions/{transactionId}/approve`

Approve a pending incoming payment that was previously acknowledged with a 202 response.
This endpoint allows platforms to asynchronously approve payments after async processing.

## Path parameters

- `transactionId` string, required

## Request body

- ApprovePaymentRequest
  - `receiverCustomerInfo` object — Information about the recipient, provided by the platform if requested in the original webhook via `requestedReceiverCustomerInfoFields`.

## Response `200`

Payment approved successfully

- 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
        - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
        - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
    - 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
        - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
        - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
    - 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
        - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
        - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
  - `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.

## Other responses

- `400` — Bad request - Invalid parameters or payment cannot be approved
- `401` — Unauthorized
- `404` — Transaction not found
- `409` — Conflict - Payment is not in a pending state or has already been processed or timed out.
- `500` — Internal service error

---

[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/versions/151f2d9bad9c/schema)