---
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

- object
  - `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' | '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
      - `currency` string — Currency code for the destination
      - `destinationType` 'ACCOUNT', required
      - `accountId` string, required — Destination account identifier
    - UmaAddressTransactionDestination — UMA address destination details
      - `currency` string — Currency code for the destination
      - `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` object — Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.
  - `source` union
    - 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
  - `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
  - `reconciliationInstructions` ReconciliationInstructions
    - `reference` string, required — Unique reference code that must be included with the payment to match it with the correct incoming transaction
  - `rateDetails` IncomingRateDetails — Details about the rate and fees for an incoming transaction.
    - `gridApiMultiplier` number, double, required — The underlying multiplier from the mSATS to the receiving currency, including variable fees.
    - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving 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 receiving currency amount.
    - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate.
  - `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

## Changes

- **2026-02-13** `ecd31fe01b4e` — 25 breaking, 5 warning, 4 info
  - added `#/components/schemas/Error400_INVALID_INPUT, #/components/schemas/Error400_MISSING_MANDATORY_USER_INFO, #/components/schemas/Error400_INVITATION_ALREADY_CLAIMED, #/components/schemas/Error400_INVITATIONS_NOT_CONFIGURED, #/components/schemas/Error400_INVALID_UMA_ADDRESS, #/components/schemas/Error400_INVITATION_CANCELLED, #/components/schemas/Error400_QUOTE_REQUEST_FAILED, #/components/schemas/Error400_INVALID_PAYREQ_RESPONSE, #/components/schemas/Error400_INVALID_RECEIVER, #/components/schemas/Error400_PARSE_PAYREQ_RESPONSE_ERROR, #/components/schemas/Error400_CERT_CHAIN_INVALID, #/components/schemas/Error400_CERT_CHAIN_EXPIRED, #/components/schemas/Error400_INVALID_PUBKEY_FORMAT, #/components/schemas/Error400_MISSING_REQUIRED_UMA_PARAMETERS, #/components/schemas/Error400_SENDER_NOT_ACCEPTED, #/components/schemas/Error400_AMOUNT_OUT_OF_RANGE, #/components/schemas/Error400_INVALID_CURRENCY, #/components/schemas/Error400_INVALID_TIMESTAMP, #/components/schemas/Error400_INVALID_NONCE, #/components/schemas/Error400_INVALID_REQUEST_FORMAT, #/components/schemas/Error400_INVALID_BANK_ACCOUNT, #/components/schemas/Error400_SELF_PAYMENT, #/components/schemas/Error400_LOOKUP_REQUEST_FAILED, #/components/schemas/Error400_PARSE_LNURLP_RESPONSE_ERROR, #/components/schemas/Error400_INVALID_AMOUNT, #/components/schemas/Error400_WEBHOOK_ENDPOINT_NOT_SET, #/components/schemas/Error400_WEBHOOK_DELIVERY_ERROR` to the response body `oneOf` list for the response status `400`
  - added `#/components/schemas/Error401_UNAUTHORIZED, #/components/schemas/Error401_INVALID_SIGNATURE` to the response body `oneOf` list for the response status `401`
  - added `#/components/schemas/Error404_TRANSACTION_NOT_FOUND, #/components/schemas/Error404_INVITATION_NOT_FOUND, #/components/schemas/Error404_USER_NOT_FOUND, #/components/schemas/Error404_QUOTE_NOT_FOUND, #/components/schemas/Error404_LOOKUP_REQUEST_NOT_FOUND, #/components/schemas/Error404_TOKEN_NOT_FOUND, #/components/schemas/Error404_BULK_UPLOAD_JOB_NOT_FOUND, #/components/schemas/Error404_REFERENCE_NOT_FOUND` to the response body `oneOf` list for the response status `404`
  - added `#/components/schemas/Error409_TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL, #/components/schemas/Error409_UMA_ADDRESS_EXISTS` to the response body `oneOf` list for the response status `409`
  - …30 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/transactions/:transactionId/approve/post.md)

---

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