--- title: "Confirm receipt delivery" method: POST path: "/transactions/{transactionId}/confirm" tags: ["Transactions"] --- # Confirm receipt delivery `POST /transactions/{transactionId}/confirm` ## Request - Base URL: `https://api.lightspark.com/grid/2025-10-13` - URL: `https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/confirm` - Auth: HTTP basic Confirm that the platform delivered the transaction receipt to its customer. This confirmation is only necessary when the platform is contractually required to send a receipt. If `receiptDeliveryConfirmedAt` is omitted, the confirmation time is set to the current server time. Calling this endpoint again for the same transaction updates the stored confirmation time. ## Path parameters - `transactionId` string, required ## Request body - ConfirmReceiptDeliveryRequest - `receiptDeliveryConfirmedAt` string, date-time: The time at which the platform delivered the transaction receipt to their customer. If omitted, the current server time is used. ## Response `200` Receipt delivery confirmation recorded successfully - 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). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction's `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | The funds are where settlement put them. A return that takes them back moves the transaction to `FAILED`, and the returned side's `railDetails` shows `RETURNED`. A transaction stays `COMPLETED` through a return only when a later step that can't be undone already used the funds | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to `COMPLETED`. A returned payout stays `FAILED`, since it has already been refunded. Each step shows on the returned side's `railDetails` | | `REFUNDED` | Deprecated. A refund is reported on the transaction's `refund` object, and the status stays `FAILED` | | `EXPIRED` | Quote has expired. Terminal | - `pendingReason` 'COUNTERPARTY_DECLARATION_REQUIRED' | 'WALLET_VERIFICATION_REQUIRED' | 'COUNTERPARTY_INFORMATION_REQUIRED' | 'COMPLIANCE_REVIEW': Why a transaction is pending. | Reason | Description | |--------|-------------| | `COUNTERPARTY_DECLARATION_REQUIRED` | The customer must declare who controls the sending wallet. | | `WALLET_VERIFICATION_REQUIRED` | The customer must verify ownership of the sending wallet. | | `COUNTERPARTY_INFORMATION_REQUIRED` | Information about the sender is required. | | `COMPLIANCE_REVIEW` | The customer's action is complete and the deposit remains under compliance review. | - `type` 'INCOMING', required: Type of transaction - `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 - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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 - `ruleBasedAccountId` string: The `RULE_BASED` internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, `source` describes the party that made the deposit when it is known, and is this account otherwise. - `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. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate. - `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 - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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. `railDetails` describes the transfer that delivered the funds; its fields are populated on a best-effort basis depending on what the funding source provides. Rails without a `railDetails` variant, such as SWIFT, carry the originator's details in the deprecated flat fields only. - `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: Deprecated. Use `railDetails.bankAccount.accountHolderName`. The name of the originator (sender) of the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `accountIdentifier` string: Deprecated. Use `railDetails.bankAccount.accountNumber`. The originator's account number or IBAN. May be masked or partial depending on the rail. Still populated on rails without a `railDetails` variant, such as SWIFT. - `bankName` string: Deprecated. Use `railDetails.bankAccount.bankName` on wires. The name of the originating bank. Still populated on rails without a `railDetails` variant, such as SWIFT. - `bankIdentifier` string: Deprecated. Use `railDetails.bankAccount.routingNumber`. The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. Still populated on rails without a `railDetails` variant, such as SWIFT. - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'ACH_SAME_DAY' | '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. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`. - `remittanceInformation` string: Deprecated. Use `railDetails.addenda` for ACH, `railDetails.originatorToBeneficiaryInformation` for wires and `railDetails.remittanceInformation` for RTP and FedNow. Free-form information about the payment provided by the originator. Still populated on rails without a `railDetails` variant, such as SWIFT. - `endToEndId` string: Deprecated. Use `railDetails.endToEndId`. The originator's own end-to-end reference for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `traceNumber` string: Deprecated. Use `railDetails.traceNumber` for ACH and `railDetails.imad` for wires. Rail-level tracking identifier for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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 - `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 `railDetails` 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 settlement transfer, when available. This field reports two different transfers, and only one of them has a replacement today: For a crypto transfer to or from a customer's own external wallet, use the `railDetails` on the relevant source or destination instead — it names the network alongside the hash. That is the transfer this field is deprecated for. For the inter-VASP settlement leg of a UMA payment (e.g. USDC on Solana to the receiving partner), this field remains the only place the hash is reported: a UMA address is not a wallet you hold, so its source and destination carry no `railDetails`. The field will not be removed before that leg has a replacement. - `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' | 'COMPLIANCE_REJECTED' | 'COLLECTION_FAILED' | 'SWEEP_AMOUNT_OUT_OF_RANGE' | 'SWEEP_QUOTE_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. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. A payment that settled into a rule-based account but could not be swept to the destination of the account's rule fails with one of the `SWEEP_*` reasons. A rule-based account never holds a balance, so the funds are moved to the account holder's own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule's minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment. - 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). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction's `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `EXPIRED` | Quote wasn't executed before expiry window. Terminal | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | The funds are at the destination. A bank return moves the payout to `FAILED` | | `FAILED` | The payout did not reach the destination, or was returned after it did — accompanied by a `failureReason`, and refunded to the source. A returned payout stays `FAILED` even if the return is later dishonored, since the refund has already been posted; the dishonor shows on `destination.railDetails` | - `pendingReason` 'COUNTERPARTY_DECLARATION_REQUIRED' | 'WALLET_VERIFICATION_REQUIRED' | 'COUNTERPARTY_INFORMATION_REQUIRED' | 'COMPLIANCE_REVIEW': Why a transaction is pending. | Reason | Description | |--------|-------------| | `COUNTERPARTY_DECLARATION_REQUIRED` | The customer must declare who controls the sending wallet. | | `WALLET_VERIFICATION_REQUIRED` | The customer must verify ownership of the sending wallet. | | `COUNTERPARTY_INFORMATION_REQUIRED` | Information about the sender is required. | | `COMPLIANCE_REVIEW` | The customer's action is complete and the deposit remains under compliance review. | - `type` 'OUTGOING', required: Type of transaction - `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 - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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 - `ruleBasedAccountId` string: The `RULE_BASED` internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, `source` describes the party that made the deposit when it is known, and is this account otherwise. - `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. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate. - `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 - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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. `railDetails` describes the transfer that delivered the funds; its fields are populated on a best-effort basis depending on what the funding source provides. Rails without a `railDetails` variant, such as SWIFT, carry the originator's details in the deprecated flat fields only. - `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: Deprecated. Use `railDetails.bankAccount.accountHolderName`. The name of the originator (sender) of the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `accountIdentifier` string: Deprecated. Use `railDetails.bankAccount.accountNumber`. The originator's account number or IBAN. May be masked or partial depending on the rail. Still populated on rails without a `railDetails` variant, such as SWIFT. - `bankName` string: Deprecated. Use `railDetails.bankAccount.bankName` on wires. The name of the originating bank. Still populated on rails without a `railDetails` variant, such as SWIFT. - `bankIdentifier` string: Deprecated. Use `railDetails.bankAccount.routingNumber`. The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. Still populated on rails without a `railDetails` variant, such as SWIFT. - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'ACH_SAME_DAY' | '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. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`. - `remittanceInformation` string: Deprecated. Use `railDetails.addenda` for ACH, `railDetails.originatorToBeneficiaryInformation` for wires and `railDetails.remittanceInformation` for RTP and FedNow. Free-form information about the payment provided by the originator. Still populated on rails without a `railDetails` variant, such as SWIFT. - `endToEndId` string: Deprecated. Use `railDetails.endToEndId`. The originator's own end-to-end reference for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `traceNumber` string: Deprecated. Use `railDetails.traceNumber` for ACH and `railDetails.imad` for wires. Rail-level tracking identifier for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. - `railDetails` union: The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. - OnChainRailDetails: A crypto transfer to or from an external wallet. - `paymentRail` 'ONCHAIN', required - `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' | 'ARBITRUM' | '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. - AchRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'ACH' | 'ACH_SAME_DAY', required - `status` 'PENDING' | 'SETTLED' | 'RETURNED' | 'RETURN_DISHONORED' | 'RETURN_CONTESTED' | 'REVERSED' | 'FAILED', required: Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. - `traceNumber` string: 15-digit ACH trace number of the entry. - `statementDescriptor` string: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. - `addenda` string: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. - `returnedAt` string, date-time: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. - `returnCode` string: The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. - `returnCategory` 'ADMINISTRATIVE' | 'UNAUTHORIZED': The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. - `dishonoredAt` string, date-time: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. - `contestedAt` string, date-time: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. - `reversedAt` string, date-time: When the originator reversed the entry. Present when `status` is `REVERSED`. - WireRailDetails: Fields shared by every US bank rail. - `bankAccount` object: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'WIRE', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | - `imad` string: Fedwire Input Message Accountability Data assigned when the wire was sent. - `originatorToBeneficiaryInformation` string: Free-form originator-to-beneficiary information (OBI) sent with the wire. - FedNowRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'FEDNOW', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - RtpRailDetails: Fields shared by every US bank rail. - `bankAccount` UsdBankAccountDetails: The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. - … - `settledAt` string, date-time: When the transfer settled. - `paymentRail` 'RTP', required - `status` 'PENDING' | 'SETTLED' | 'FAILED', required: Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | - `endToEndId` string: The originator's end-to-end reference for the payment. - `remittanceInformation` string: Unstructured remittance information sent with the payment. - SwiftRailDetails: An international wire over the SWIFT network. Present on payout destinations. - `paymentRail` 'SWIFT', required - `uetr` string, uuid: Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. - `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' | 'ARBITRUM' | '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 - `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 `railDetails` 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 settlement transfer, when available. This field reports two different transfers, and only one of them has a replacement today: For a crypto transfer to or from a customer's own external wallet, use the `railDetails` on the relevant source or destination instead — it names the network alongside the hash. That is the transfer this field is deprecated for. For the inter-VASP settlement leg of a UMA payment (e.g. USDC on Solana to the receiving partner), this field remains the only place the hash is reported: a UMA address is not a wallet you hold, so its source and destination carry no `railDetails`. The field will not be removed before that leg has a replacement. - `paymentInstructions` PaymentInstructions[]: 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: Where to send the funds. Quotes can carry any of these types. Internal accounts return only `USD_ACCOUNT`, `EUR_ACCOUNT`, `SWIFT_ACCOUNT`, and the network wallet types; MXN, BRL, COP, ARS, Lightning, and Bitcoin L1 instructions appear only on real-time funded quotes. - PaymentUsdAccountInfo - `accountType` 'USD_ACCOUNT', required: Type of payment account or wallet - `accountNumber` string, required: The account number of the bank - `routingNumber` string, required: The ABA routing number - `bankName` string: The name of the financial institution holding the account. Optional on every rail, and recommended for wires, where it identifies the beneficiary's institution on the payment message. Not checked against `GET /discoveries`. - `intermediaryBankName` string: The name of the intermediary financial institution, for accounts reachable only through a correspondent bank. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. - `intermediaryRoutingNumber` string: The ABA routing number of the intermediary financial institution. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. - `fiToFiInformation` string: Bank-to-bank instructions carried alongside the payment. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. - `paymentRails` string[], required - `bankAccountType` 'CHECKING' | 'SAVINGS': Whether the account is a checking or a savings account. Grid uses this to set the ACH transaction code, so a value that does not match the account causes the receiving bank to return a notification of change. - `reference` string, required: Unique reference code that must be included with the payment to properly credit it - `bankAddress` string: The postal address of the financial institution holding the account, on a single line. Optional on every rail, and recommended for wires, where some originating banks require the beneficiary institution's address before they will send. - PaymentEurAccountInfo - `accountType` 'EUR_ACCOUNT', required: Type of payment account or wallet - `iban` string, required: The IBAN of the bank account - `swiftCode` string: The SWIFT/BIC code of the bank. When omitted, Grid derives it from the IBAN when possible. Provide it when automatic derivation is unavailable. - `paymentRails` string[], required - `reference` string, required: Unique reference code that must be included with the payment to properly credit it - PaymentSwiftAccountInfo: At least one of accountNumber or iban is always present: IBAN-only corridors (e.g. BR, GB) use iban, other corridors use accountNumber, and both appear when the bank exposes both identifiers for the same account. - `accountType` 'SWIFT_ACCOUNT', required: Type of payment account or wallet - `country` string, required: The ISO 3166-1 alpha-2 country code of the bank account - `swiftCode` string, required: The SWIFT/BIC code of the bank - `bankName` string, required: The name of the bank - `accountNumber` string: The bank account number. Required for most corridors. Use iban instead for IBAN-only corridors (e.g. BR, GB). - `iban` string: The IBAN of the bank account. Required for IBAN-only corridors (e.g. BR, GB). Use accountNumber for all other corridors. - `paymentRails` string[], required - `accountHolderName` string, required: The name of the account holder as it must appear on the wire. Remitting banks match this against the beneficiary name field, so payers should copy it exactly. - `bankAddress` string: The address of the bank holding the account, when known. - `reference` string: Reference code to include with the payment when present. SWIFT payments are attributed by the destination account number/IBAN, so this account type typically requires no reference. - PaymentMxnAccountInfo - `accountType` 'MXN_ACCOUNT', required: Type of payment account or wallet - `clabeNumber` string, required: The CLABE number of the bank - `paymentRails` string[], required - `reference` string, required: Unique reference code that must be included with the payment to properly credit it - PaymentBrlAccountInfo - `accountType` 'BRL_ACCOUNT', required: Type of payment account or wallet - `qrCode` string, required: A PIX QR code payload that can be used to fund the transaction. This can be rendered as a QR code image or pasted into a PIX-compatible banking app. - PaymentCopAccountInfo - `accountType` 'COP_ACCOUNT', required: Type of payment account or wallet - `paymentUrl` string, uri, required: A payment URL where the customer can complete their COP deposit. - PaymentArsAccountInfo - `accountType` 'ARS_ACCOUNT', required: Type of payment account or wallet - `accountNumber` string, required: The static CVU (Clave Virtual Uniforme) bank account number to pay to. - PaymentSparkWalletInfo - `accountType` 'SPARK_WALLET', required: Type of payment account or wallet - `address` string, required: Spark wallet address - `assetType` string, required: Type of asset or configured Spark token currency code - `invoice` string: Invoice for the payment - PaymentLightningInvoiceInfo - `accountType` 'LIGHTNING', required: Type of payment account or wallet - `invoice` string, required: Invoice for the payment - PaymentBitcoinDepositAddressInfo - `accountType` 'BITCOIN_L1', required: Type of payment account or wallet - `address` string, required: On-chain Bitcoin (L1) deposit address to send funds to - `network` 'BITCOIN': The blockchain network for the deposit address. - PaymentSolanaWalletInfo - `accountType` 'SOLANA_WALLET', required: Type of payment account or wallet - `address` string, required: Solana wallet address - `assetType` 'USDC' | 'USDT': Type of asset - PaymentEthereumWalletInfo - `accountType` 'ETHEREUM_WALLET', required: Type of payment account or wallet - `address` string, required: Ethereum L1 wallet address - `assetType` 'USDC' | 'USDT': Type of asset - PaymentBaseWalletInfo - `accountType` 'BASE_WALLET', required: Type of payment account or wallet - `address` string, required: Base eth wallet address - `assetType` 'USDC': Type of asset - PaymentPolygonWalletInfo - `accountType` 'POLYGON_WALLET', required: Type of payment account or wallet - `address` string, required: Polygon eth wallet address - `assetType` 'USDC': Type of asset - PaymentArbitrumWalletInfo - `accountType` 'ARBITRUM_WALLET', required: Type of payment account or wallet - `address` string, required: Arbitrum wallet address - `assetType` 'USDC' | 'USDT': Type of asset - PaymentTronWalletInfo - `accountType` 'TRON_WALLET', required: Type of payment account or wallet - `address` string, required: Tron wallet address - `assetType` 'USDT': Type of asset - PaymentPlasmaWalletInfo - `accountType` 'PLASMA_WALLET', required: Type of payment account or wallet - `address` string, required: Plasma wallet address - `assetType` 'USDT': Type of asset - PaymentEmbeddedWalletInfo - `accountType` 'EMBEDDED_WALLET', required: Discriminator value identifying this as Embedded Wallet payment instructions. - `payloadToSign` string, required: JSON-encoded transaction signing payload that must be stamped, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting Grid wallet signature is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet. - `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_RATE_UNAVAILABLE' | 'QUOTE_EXECUTION_FAILED' | 'FUNDING_AMOUNT_MISMATCH' | 'SCA_NOT_COMPLETED' | 'PAYOUT_RETURNED' | 'LIMIT_EXCEEDED' | 'ACCOUNT_CANNOT_RECEIVE' | 'ACCOUNT_INVALID' | 'COMPLIANCE_REJECTED' | 'LIGHTNING_PAYMENT_FAILED' | 'COUNTERPARTY_POST_TX_FAILED' | 'SWEEP_AMOUNT_OUT_OF_RANGE' | 'SWEEP_QUOTE_FAILED': 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. When a payout partner rejects or fails a payment, one of the granular payout reasons (`PAYOUT_RETURNED`, `LIMIT_EXCEEDED`, `ACCOUNT_CANNOT_RECEIVE`, `ACCOUNT_INVALID`, `COMPLIANCE_REJECTED`) is returned when available. `COUNTERPARTY_POST_TX_FAILED` is a coarse fallback used only when no granular reason is available. `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. | Reason | Description | |--------|-------------| | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | | `QUOTE_RATE_UNAVAILABLE` | The quoted exchange rate was no longer available when the quote was executed, so nothing was exchanged. Create a new quote to get a current rate | | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | | `SCA_NOT_COMPLETED` | The customer did not complete the Strong Customer Authentication challenge before it expired | | `PAYOUT_RETURNED` | The receiving bank accepted the payout and then returned or reversed it | | `LIMIT_EXCEEDED` | The payout exceeds a recipient-, account-, or corridor-level limit at the partner | | `ACCOUNT_CANNOT_RECEIVE` | The account exists but can't accept this payment — dormant, frozen, restricted, or the currency or payment rail isn't supported for that account. A sweep whose rule names a rail the destination cannot accept reports this | | `ACCOUNT_INVALID` | The recipient account couldn't be found or the details are wrong — bad IBAN/account number, beneficiary not found, or account closed | | `COMPLIANCE_REJECTED` | The payout partner rejected the recipient on compliance grounds — sanctions, watchlist, or KYC/AML screening | | `LIGHTNING_PAYMENT_FAILED` | Deprecated — superseded by `QUOTE_EXECUTION_FAILED`. The Lightning settlement leg failed | | `COUNTERPARTY_POST_TX_FAILED` | Deprecated — coarse fallback retained for historical transactions when no granular payout reason is available | | `SWEEP_AMOUNT_OUT_OF_RANGE` | The amount was outside the range the corridor to the rule's destination can carry — below its minimum or above its maximum. The rule's `minimumAmount` and `maximumAmount` give the current band | | `SWEEP_QUOTE_FAILED` | Grid could not price the sweep to the rule's destination. A sweep that was priced and then failed on the way to settlement reports `QUOTE_EXECUTION_FAILED`, the same as any other payout | The `SWEEP_*` reasons apply to a payment that settled into a rule-based account and could not be swept onward. A rule-based account never holds a balance, so the funds are moved to the account holder's own account in the same currency. - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'ACH_SAME_DAY' | '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. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`. - `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: One row per cardholder-visible card transaction. A purchase row rolls its clearings up into `settledAmount`; a merchant return is its own dated `CREDIT` row linked back to the purchase via `originalTransactionId` rather than a rollup on the parent, so statements can list purchases and refunds as separate dated lines. Delivered whole as the `data` payload of every `CARD_TRANSACTION.*` webhook, and returned as the `CARD` variant of `Transaction` from `GET /transactions`. - `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' | 'DECLINED' | 'VOIDED' | 'EXCEPTION', required: Lifecycle status of a card transaction. The status tracks the authorization outcome and settlement — a return against a purchase is its own dated `CREDIT` row linked to the purchase via `originalTransactionId`, not a status of its own. | 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. A `RETURN` received afterwards keeps the purchase `SETTLED`; the return appears as its own `CREDIT` transaction. | | `DECLINED` | The authorization was declined before any money moved. Declines carry no settlement and must be excluded from cardholder statements. | | `VOIDED` | The authorization was fully reversed or expired before any clearing posted, so the hold closed without moving money. `authorizedAmount` reports what is still held, normally 0, and `settledAmount` is absent. | | `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. | - `cardDeclinedReason` 'CARD_NOT_ACTIVE' | 'SPEND_LIMIT_EXCEEDED' | 'INSUFFICIENT_FUNDS' | 'NO_ELIGIBLE_FUNDING_SOURCE' | 'BLOCKED' | 'UNSUPPORTED_NETWORK' | 'INCORRECT_CARD_DETAILS' | 'TEMPORARILY_UNAVAILABLE' | 'PLATFORM_DECLINED' | 'PLATFORM_UNAVAILABLE' | 'OTHER': Why Grid declined a card authorization. Present only when a card transaction's `status` is `DECLINED`. | Reason | Returned when | |--------|---------------| | `CARD_NOT_ACTIVE` | The card is not `ACTIVE`. A `FROZEN`, `PROCESSING`, `PENDING_KYC`, or `CLOSED` card declines every authorization. | | `SPEND_LIMIT_EXCEEDED` | The authorization exceeds a configured card velocity limit or an applicable agent spending-policy cap. | | `INSUFFICIENT_FUNDS` | The funding source balance does not cover the authorization. Grid reserves the amount when it decides the authorization, so an underfunded card is declined. | | `NO_ELIGIBLE_FUNDING_SOURCE` | The card has no usable funding source, for example an Embedded Wallet source with no active delegated key. | | `BLOCKED` | Program rules block the merchant category or the transaction. | | `UNSUPPORTED_NETWORK` | Grid does not support the network or the transaction type. | | `INCORRECT_CARD_DETAILS` | The PIN, security code, expiry date, or billing address entered at the merchant did not match the card. | | `TEMPORARILY_UNAVAILABLE` | A temporary problem at Grid, the card processor, or the card network stopped the authorization. The cardholder can try again. | | `PLATFORM_DECLINED` | Your platform returned `decision: DECLINE`. `platformDeclineReason` carries the reason it gave. | | `PLATFORM_UNAVAILABLE` | Your platform did not return a valid decision to a `CARD_AUTHORIZATION.REQUEST` in time, and `cardConfigs.realTimeAuthorization.timeoutBehavior` is `DECLINE`. | | `OTHER` | Any other reason, including a security or fraud decline the card processor made. | - `platformDeclineReason` 'SUSPECTED_FRAUD' | 'UNAUTHORIZED_MERCHANT' | 'VELOCITY_EXCEEDED' | 'INSUFFICIENT_FUNDS' | 'CARD_PAUSED': Why your platform declined a card authorization. Grid passes it to the card network, so choose the most specific reason. | Reason | Use when | |--------|----------| | `SUSPECTED_FRAUD` | The authorization breaks your fraud rules. Use it only when no other reason fits. | | `UNAUTHORIZED_MERCHANT` | The merchant, merchant category, country, or transaction type is not allowed for this card. | | `VELOCITY_EXCEEDED` | The authorization exceeds a velocity limit you set. The merchant may retry later. | | `INSUFFICIENT_FUNDS` | The cardholder lacks funds by your own accounting. The merchant may retry later. | | `CARD_PAUSED` | You track a paused state for the card that Grid's card `status` does not reflect. | - `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. - `originalTransactionId` string: On a refund row (`direction: CREDIT`), the id of the purchase this return credits back against. Absent on purchases and on standalone credits with no matching purchase. - `description` string: The merchant descriptor, repeated from `merchant.descriptor` so a transaction list reads without expanding each card row. Unlike `description` on other transaction types, this is set by Grid from the card network's descriptor, not supplied by the platform. - `merchant` CardMerchant, required - `descriptor` string, required: Merchant descriptor string captured from the card network at authorization time. On the sandbox simulate endpoints, where this is supplied rather than reported, it must be 1–25 characters — the width of the card network's acceptor-name field. - `mcc` string: Merchant Category Code (ISO 18245) — four-digit numeric string. - `city` string: Merchant city as reported by the card network, when present. - `state` string: Merchant state or region as reported by the card network, when present. - `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). - `authorizedAt` string, date-time, required: When the authorization was approved or declined. - `createdAt` string, date-time, required: Creation timestamp (same as `authorizedAt` for card transactions). - `updatedAt` string, date-time, required: Last update timestamp. ## Other responses - `400`: Bad request - Invalid parameters - `401`: Unauthorized - `404`: Transaction not found - `500`: Internal service error ## Changes > 115 revisions in range; 2 not diffed. - **2026-10-28** `d996ddfb9d2b`: 2 info - added the optional property `details/missingFields` to the response with the `400` status - added the optional property `details/refusalReason` to the response with the `400` status - **2026-10-27** `190120f7c3c4`: 2 warning, 1 info - added the new `PLATFORM_DECLINED` enum value to the `oneOf[subschema #3: Card Transaction]/cardDeclinedReason` response property for the response status `200` - added the new `PLATFORM_UNAVAILABLE` enum value to the `oneOf[subschema #3: Card Transaction]/cardDeclinedReason` response property for the response status `200` - added the optional property `oneOf[subschema #3: Card Transaction]/platformDeclineReason` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/transactions/:transactionId/confirm/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.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)