---
title: "Create a transfer-out request"
method: POST
path: "/transfer-out"
tags: ["Same-Currency Transfers"]
---

# Create a transfer-out request

`POST /transfer-out`

Transfer funds from an internal account to an external account for a specific customer.

## Headers

- `Idempotency-Key` string

## Request body

- TransferOutRequest
  - `source` InternalAccountReference, required
    - `accountId` string, required — Reference to an internal account ID
  - `destination` ExternalAccountDestinationReference, required
    - `accountId` string, required — Reference to an external account ID
    - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
  - `amount` integer — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
  - `remittanceInformation` string — Free-form information about the payment that travels with it to the recipient. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information.
  - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'TAX_PAYMENT' | 'LOAN_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'FAMILY_SUPPORT' | 'SALARY_PAYMENT' | 'OTHER' — The purpose of the payment. This may be required when sending to certain geographies (e.g. India).

## Response `201`

Transfer-out request created 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); authorize the transaction's `scaChallenge` to proceed. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired |
    - `type` 'INCOMING', required — Type of transaction (incoming payment or outgoing payment)
    - `direction` 'CREDIT' | 'DEBIT', required — Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `accountId` string, required — Destination account identifier
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `umaAddress` string, required — UMA address of the recipient
    - `customerId` string, required — System ID of the customer this transaction belongs to
    - `platformCustomerId` string, required — Platform-specific ID of the customer this transaction belongs to
    - `settledAt` string, date-time — When the payment was or will be settled
    - `createdAt` string, date-time — When the transaction was created
    - `updatedAt` string, date-time — When the transaction was last updated
    - `receiptDeliveryConfirmedAt` string, date-time — The time at which the platform confirmed delivery of the receipt to their customer.
    - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.
    - `description` string — Optional memo or description for the payment
    - `sentAmount` CurrencyAmount
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `exchangeRate` number — Number of sending currency units per receiving currency unit.
    - `quoteId` string — The ID of the quote that was used to trigger this payment
    - `refund` Refund
      - `reference` string, required — The unique reference ID of the refund
      - `initiatedAt` string, date-time, required — When the refund was initiated
      - `settledAt` string, date-time — When the refund was settled
      - `status` 'PENDING' | 'COMPLETED' | 'FAILED', required — Current status of the refund
      - `reason` 'TRANSACTION_FAILED' | 'USER_CANCELLATION' | 'TIMEOUT' — Reason for the refund
    - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
    - `source` union
      - AccountTransactionSource — Source account details
        - `sourceType` 'ACCOUNT', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `accountId` string, required — Source account identifier
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides.
        - `sourceType` 'REALTIME_FUNDING', required — Type of transaction source
        - `currency` string, required — Currency code for the funding source
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `accountHolderName` string — The name of the originator (sender) of the payment.
        - `accountIdentifier` string — The originator's account number or IBAN. May be masked or partial depending on the rail.
        - `bankName` string — The name of the originating bank.
        - `bankIdentifier` string — The identifier of the originating bank, such as a routing number, BIC, or SWIFT code.
        - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
        - `remittanceInformation` string — Free-form information about the payment provided by the originator. The source field depends on the payment rail: the Addenda record for ACH, the OBI / beneficiary information for wires, and the remittanceInformation field for RTP and FedNow.
        - `endToEndId` string — The originator's own end-to-end reference for the payment.
        - `traceNumber` string — Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation.
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
    - `receivedAmount` CurrencyAmount, required
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `fees` integer — The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents).
    - `reconciliationInstructions` ReconciliationInstructions — Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead.
      - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
      - `transactionHash` string — Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination.
    - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted.
  - OutgoingTransaction
    - `id` string, required — Unique identifier for the transaction
    - `status` 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU); authorize the transaction's `scaChallenge` to proceed. | | `EXPIRED` | Quote wasn't executed before expiry window | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | Payout successfully reached the destination | | `FAILED` | Something went wrong — accompanied by a `failureReason` |
    - `type` 'OUTGOING', required — Type of transaction (incoming payment or outgoing payment)
    - `direction` 'CREDIT' | 'DEBIT', required — Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `accountId` string, required — Destination account identifier
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required — Type of transaction destination
        - `currency` string — Currency code for the destination
        - `umaAddress` string, required — UMA address of the recipient
    - `customerId` string, required — System ID of the customer this transaction belongs to
    - `platformCustomerId` string, required — Platform-specific ID of the customer this transaction belongs to
    - `settledAt` string, date-time — When the payment was or will be settled
    - `createdAt` string, date-time — When the transaction was created
    - `updatedAt` string, date-time — When the transaction was last updated
    - `receiptDeliveryConfirmedAt` string, date-time — The time at which the platform confirmed delivery of the receipt to their customer.
    - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.
    - `description` string — Optional memo or description for the payment
    - `sentAmount` CurrencyAmount, required
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `exchangeRate` number — Number of sending currency units per receiving currency unit.
    - `quoteId` string — The ID of the quote that was used to trigger this payment
    - `refund` Refund
      - `reference` string, required — The unique reference ID of the refund
      - `initiatedAt` string, date-time, required — When the refund was initiated
      - `settledAt` string, date-time — When the refund was settled
      - `status` 'PENDING' | 'COMPLETED' | 'FAILED', required — Current status of the refund
      - `reason` 'TRANSACTION_FAILED' | 'USER_CANCELLATION' | 'TIMEOUT' — Reason for the refund
    - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
    - `source` union, required
      - AccountTransactionSource — Source account details
        - `sourceType` 'ACCOUNT', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `accountId` string, required — Source account identifier
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required — Type of transaction source
        - `currency` string — Currency code for the source
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides.
        - `sourceType` 'REALTIME_FUNDING', required — Type of transaction source
        - `currency` string, required — Currency code for the funding source
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `accountHolderName` string — The name of the originator (sender) of the payment.
        - `accountIdentifier` string — The originator's account number or IBAN. May be masked or partial depending on the rail.
        - `bankName` string — The name of the originating bank.
        - `bankIdentifier` string — The identifier of the originating bank, such as a routing number, BIC, or SWIFT code.
        - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
        - `remittanceInformation` string — Free-form information about the payment provided by the originator. The source field depends on the payment rail: the Addenda record for ACH, the OBI / beneficiary information for wires, and the remittanceInformation field for RTP and FedNow.
        - `endToEndId` string — The originator's own end-to-end reference for the payment.
        - `traceNumber` string — Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation.
        - `onChainTransaction` OnChainTransaction
          - `transactionHash` string, required — On-chain transaction hash of the crypto transfer for this leg of the transaction.
          - `network` 'BITCOIN' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'POLYGON' | 'TRON' | 'PLASMA' | 'SPARK', required — The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API.
    - `receivedAmount` CurrencyAmount
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `fees` integer — The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
    - `platformFees` integer — The portion of `fees` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `fees`.
    - `reconciliationInstructions` ReconciliationInstructions — Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead.
      - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
      - `transactionHash` string — Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination.
    - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. — unresolved $ref
    - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.
      - `counterpartyMultiplier` number, double, required — The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution.
      - `counterpartyFixedFee` integer, required — The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents).
      - `gridApiMultiplier` number, double, required — The underlying multiplier from the sending currency to mSATS, including variable fees.
      - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents).
      - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount.
      - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate.
    - `failureReason` 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' | 'LIGHTNING_PAYMENT_FAILED' | 'FUNDING_AMOUNT_MISMATCH' | 'COUNTERPARTY_POST_TX_FAILED' | 'SCA_NOT_COMPLETED' | 'EXECUTION_FAILED_POST_DEBIT' | 'SETTLEMENT_FAILED' | 'TIMEOUT' | 'MANUAL_REFUND' — Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live.
    - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts.
    - `railSelectionMode` 'AUTO' | 'MANUAL' — How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it.
    - `expectedSettlementAt` string, date-time, nullable — Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved.
    - `settlementTimelineSeconds` integer, nullable — Expected number of seconds from quote creation to settlement. Null when not yet known.
  - CardTransaction — Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the `pullSummary`, `refundSummary`, and `settlementSummary` aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition.
    - `type` 'CARD', required — Discriminator identifying this transaction as a card transaction in the `Transaction` list.
    - `id` string, required — System-generated unique card transaction identifier
    - `cardId` string — The id of the `Card` this transaction was made on.
    - `customerId` string, required — System ID of the customer (cardholder) this transaction belongs to.
    - `platformCustomerId` string, required — Platform-specific ID of the customer (cardholder) this transaction belongs to.
    - `issuerTransactionToken` string — Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks.
    - `status` 'AUTHORIZED' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'REFUNDED' | 'EXCEPTION', required — Lifecycle status of a card transaction. | Status | Description | |--------|-------------| | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. | | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). | | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. | | `REFUNDED` | A `RETURN` was received from the merchant; the net settled amount has been refunded in part or whole. | | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. |
    - `direction` 'CREDIT' | 'DEBIT', required — Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.
    - `merchant` CardMerchant, required
      - `descriptor` string, required — Merchant descriptor string captured from the card network at authorization time.
      - `mcc` string — Merchant Category Code (ISO 18245) — four-digit numeric string.
      - `country` string — Two-letter ISO 3166-1 alpha-2 country code of the merchant.
    - `authorizedAmount` CurrencyAmount, required
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `settledAmount` CurrencyAmount
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `refundedAmount` CurrencyAmount
      - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
      - `currency` Currency, required
        - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
        - `name` string — Full name of the currency
        - `symbol` string — Symbol of the currency
        - `decimals` integer — Number of decimal places for the currency
    - `accountId` string, required — Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time).
    - `pullSummary` CardPullSummary
      - `count` integer, required — Total number of pulls (debits) executed against the funding source for this transaction. `> 1` indicates one or more post-hoc pulls — e.g. restaurant tip / over-auth clearings.
      - `totalAmount` integer, required — Sum of all pull amounts in the smallest unit of the funding source's currency.
      - `pendingCount` integer — Number of pulls still in the `PENDING` state. Drops to zero when every pull has reached a terminal state. Non-zero values that persist beyond the expected settlement window are an early signal for the `EXCEPTION` path.
    - `refundSummary` CardRefundSummary
      - `count` integer, required — Number of refund (return) events received for this transaction.
      - `totalAmount` integer, required — Sum of all refund amounts in the smallest unit of the funding source's currency.
    - `settlementSummary` CardSettlementSummary
      - `count` integer, required — Number of settlement (clearing) events received for this transaction.
      - `totalAmount` integer, required — Sum of all settled amounts in the smallest unit of the funding source's currency.
    - `authorizedAt` string, date-time, required — When the auth was approved.
    - `lastEventAt` string, date-time — Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction.
    - `createdAt` string, date-time, required — Creation timestamp (same as `authorizedAt` for card transactions).
    - `updatedAt` string, date-time, required — Last update timestamp.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `404` — Customer or account not found
- `500` — Internal service error

---

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