--- title: "Reject a pending incoming payment" method: POST path: "/transactions/{transactionId}/reject" tags: ["Transactions"] --- # Reject a pending incoming payment `POST /transactions/{transactionId}/reject` Reject a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously reject payments after additional processing. ## Path parameters - `transactionId` string, required ## Request body - RejectPaymentRequest - `reason` string — Optional reason for rejecting the payment. This is just for debugging purposes or can be used for a platform's own purposes. ## Response `200` Payment rejected successfully - IncomingTransaction - `id` string, required — Unique identifier for the transaction - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'SENT' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PROCESSING` | Funding has been received and payment initiated | | `SENT` | Cross border settlement has been 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) - `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 - ExternalAccountDetailsTransactionDestination — Transaction destination where external account details were provided inline at quote creation rather than using a pre-registered external account. - `currency` string — Currency code for the destination - `destinationType` 'EXTERNAL_ACCOUNT_DETAILS', required - `externalAccountDetails` ExternalAccountCreateRequest, required - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform. - `currency` string, required — The ISO 4217 currency code - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier. - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. - `accountInfo` union, required - BrlExternalAccountInfo - `accountType` 'BRL_ACCOUNT', required - `paymentRails` string[], required - `pixKey` string, required — The PIX key of the bank - `pixKeyType` string, required — The type of PIX key of the bank - `taxId` string, required — The tax ID of the bank account - `beneficiary` union, required - … - CadExternalAccountInfo - `accountType` 'CAD_ACCOUNT', required - `paymentRails` string[], 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) - `beneficiary` union, required - … - DkkExternalAccountInfo - `accountType` 'DKK_ACCOUNT', required - `paymentRails` string[], required - `iban` string, required — The IBAN of the bank - `swiftBic` string — The SWIFT BIC of the bank - `beneficiary` union, required - … - EurExternalAccountInfo - `accountType` 'EUR_ACCOUNT', required - `paymentRails` string[], required - `iban` string, required — The IBAN of the bank - `swiftBic` string — The SWIFT BIC of the bank - `beneficiary` union, required - … - GbpExternalAccountInfo - `accountType` 'GBP_ACCOUNT', required - `paymentRails` string[], required - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens) - `accountNumber` string, required — UK bank account number (8 digits) - `beneficiary` union, required - … - HkdExternalAccountInfo - `accountType` 'HKD_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the bank - `accountNumber` string, required — Hong Kong bank account number - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - IdrExternalAccountInfo - `accountType` 'IDR_ACCOUNT', required - `paymentRails` string[], required - `accountNumber` string, required — Indonesian bank account number - `bankName` string, required — Name of the bank - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `phoneNumber` string, required — Indonesian phone number for e-wallet payments - `beneficiary` union, required - … - InrExternalAccountInfo - `accountType` 'INR_ACCOUNT', required - `paymentRails` string[], required - `vpa` string, required — The VPA of the bank - `beneficiary` union, required - … - KesExternalAccountInfo - `accountType` 'KES_ACCOUNT', required - `paymentRails` string[], required - `phoneNumber` string, required — Kenyan mobile money phone number - `provider` 'M-PESA', required — Mobile money provider - `beneficiary` union, required - … - MxnExternalAccountInfo - `accountType` 'MXN_ACCOUNT', required - `paymentRails` string[], required - `clabeNumber` string, required — The CLABE number of the bank - `beneficiary` union, required - … - MyrExternalAccountInfo - `accountType` 'MYR_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the bank - `accountNumber` string, required — Malaysian bank account number - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - NgnExternalAccountInfo - `accountType` 'NGN_ACCOUNT', required - `paymentRails` string[], required - `accountNumber` string, required — Nigerian bank account number - `bankName` string, required — Name of the bank - `beneficiary` union, required - … - PhpExternalAccountInfo - `accountType` 'PHP_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the beneficiary's bank - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - RwfExternalAccountInfo - `accountType` 'RWF_ACCOUNT', required - `paymentRails` string[], required - `phoneNumber` string, required — Rwandan mobile money phone number - `provider` 'MTN' | 'AIRTEL', required — Mobile money provider - `beneficiary` union, required - … - SgdExternalAccountInfo - `accountType` 'SGD_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the beneficiary's bank - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - ThbExternalAccountInfo - `accountType` 'THB_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the bank - `accountNumber` string, required — Thai bank account number - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - TzsExternalAccountInfo - `accountType` 'TZS_ACCOUNT', required - `paymentRails` string[], required - `phoneNumber` string, required — Tanzanian mobile money phone number - `provider` 'AIRTEL' | 'VODACOM', required — Mobile money provider - `beneficiary` union, required - … - UsdExternalAccountInfo - `accountType` 'USD_ACCOUNT', required - `paymentRails` string[], required - `accountNumber` string, required — The account number of the bank - `routingNumber` string, required — The routing number of the bank - `beneficiary` union, required - … - VndExternalAccountInfo - `accountType` 'VND_ACCOUNT', required - `paymentRails` string[], required - `bankName` string, required — Name of the bank - `accountNumber` string, required — Vietnamese bank account number - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - ZarExternalAccountInfo - `accountType` 'ZAR_ACCOUNT', required - `paymentRails` string[], required - `accountNumber` string, required — South African bank account number - `bankName` string, required — Name of the bank - `beneficiary` union, required - … - ZmwExternalAccountInfo - `accountType` 'ZMW_ACCOUNT', required - `paymentRails` string[], required - `phoneNumber` string, required — Zambian mobile money phone number - `provider` 'TNM' | 'AIRTEL' | 'ZAMTEL' | 'MTN', required — Mobile money provider - `beneficiary` union, required - … - SparkWalletExternalAccountInfo - `accountType` 'SPARK_WALLET', required - `address` string, required — Spark wallet address - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. - `accountType` 'LIGHTNING', required - `invoice` string — 1-time use lightning bolt11 invoice payout destination - `bolt12` string — A bolt12 offer which can be reused as a payment destination - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination. - SolanaWalletExternalAccountInfo - `accountType` 'SOLANA_WALLET', required - `address` string, required — Solana wallet address - TronWalletExternalAccountInfo - `accountType` 'TRON_WALLET', required - `address` string, required — Tron wallet address - PolygonWalletExternalAccountInfo - `accountType` 'POLYGON_WALLET', required - `address` string, required — Polygon eth wallet address - BaseWalletExternalAccountInfo - `accountType` 'BASE_WALLET', required - `address` string, required — Base eth wallet address - `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 - 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 - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). - `currency` string, required — Currency code for the funding source - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — The customer on whose behalf the transaction was initiated. - `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 rejected - `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-03-03** `efe0d983985f` — 23 breaking, 34 info - the response's body type/format changed from ``/`` to `object`/`` for status `400` - the response's body type/format changed from ``/`` to `object`/`` for status `401` - the response's body type/format changed from ``/`` to `object`/`` for status `404` - the response's body type/format changed from ``/`` to `object`/`` for status `409` - …53 more - …earlier changes not shown [Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/transactions/:transactionId/reject/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/efe0d983985f/schema)