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

# Create a transfer-in request

`POST /transfer-in`

Transfer funds from an external account to an internal account for a specific customer. This endpoint should only be used for external account sources with pull functionality (e.g. ACH Pull). Otherwise, use the paymentInstructions on the internal account to deposit funds.

## Headers

- `Idempotency-Key` string

## Request body

- TransferInRequest
  - `source` ExternalAccountReference, required
    - `accountId` string, required — Reference to an external account ID
  - `destination` InternalAccountReference, required
    - `accountId` string, required — Reference to an internal account ID
  - `amount` integer — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

## Response `201`

Transfer-in request created successfully

- union
  - IncomingTransaction
    - `id` string, required — Unique identifier for the transaction
    - `status` 'CREATED' | 'PENDING' | '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 | | `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)
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required
        - `accountId` string, required — Destination account identifier
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the recipient
    - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming)
    - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
    - `settledAt` string, date-time — When the payment was or will be settled
    - `createdAt` string, date-time — When the transaction was created
    - `updatedAt` string, date-time — When the transaction was last updated
    - `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
    - `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
        - `accountId` string, required — Source account identifier
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
        - `sourceType` 'REALTIME_FUNDING', required
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `currency` string, required — Currency code for the funding source
    - `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 receiving currency (eg. cents).
    - `reconciliationInstructions` ReconciliationInstructions
      - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
      - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available.
    - `rateDetails` IncomingRateDetails — Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` 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.
      - `gridApiMultiplier` number, double, required — The underlying multiplier from the mSATS to the receiving currency, including variable fees.
      - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents).
      - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount.
      - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate.
    - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted.
  - OutgoingTransaction
    - `id` string, required — Unique identifier for the transaction
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `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)
    - `destination` union, required
      - AccountTransactionDestination — Destination account details
        - `destinationType` 'ACCOUNT', required
        - `accountId` string, required — Destination account identifier
      - UmaAddressTransactionDestination — UMA address destination details
        - `destinationType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the recipient
    - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming)
    - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
    - `settledAt` string, date-time — When the payment was or will be settled
    - `createdAt` string, date-time — When the transaction was created
    - `updatedAt` string, date-time — When the transaction was last updated
    - `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
    - `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
        - `accountId` string, required — Source account identifier
      - UmaAddressTransactionSource — UMA address source details
        - `sourceType` 'UMA_ADDRESS', required
        - `umaAddress` string, required — UMA address of the sender
      - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
        - `sourceType` 'REALTIME_FUNDING', required
        - `customerId` string — The customer on whose behalf the transaction was initiated.
        - `currency` string, required — Currency code for the funding source
    - `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
    - `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
    - `exchangeRate` number — Number of sending currency units per receiving currency unit.
    - `fees` integer — The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
    - `reconciliationInstructions` ReconciliationInstructions
      - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
      - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available.
    - `quoteId` string — The ID of the quote that was used to trigger this payment
    - `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
        - PaymentUsdAccountInfo
          - `accountType` 'USD_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `routingNumber` string, required — The ABA routing number
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBrlAccountInfo
          - `accountType` 'BRL_ACCOUNT'
          - `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.
        - PaymentMxnAccountInfo
          - `accountType` 'MXN_ACCOUNT', required
          - `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
        - PaymentDkkAccountInfo
          - `accountType` 'DKK_ACCOUNT', required
          - `iban` string, required — Danish IBAN (18 characters, starting with DK)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentEurAccountInfo
          - `accountType` 'EUR_ACCOUNT', required
          - `iban` string, required — The IBAN of the bank account
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentInrAccountInfo
          - `accountType` 'INR_ACCOUNT', required
          - `vpa` string, required — The UPI Virtual Payment Address
          - `paymentRails` string[], required
        - PaymentNgnAccountInfo
          - `accountType` 'NGN_ACCOUNT', required
          - `accountNumber` string, required — Nigerian bank account number
          - `bankName` string, required — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentCadAccountInfo
          - `accountType` 'CAD_ACCOUNT', required
          - `bankCode` string, required — Canadian financial institution number (3 digits)
          - `branchCode` string, required — Transit number identifying the branch (5 digits)
          - `accountNumber` string, required — Bank account number (7-12 digits)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGbpAccountInfo
          - `accountType` 'GBP_ACCOUNT', required
          - `sortCode` string, required — The UK sort code
          - `accountNumber` string, required — UK bank account number (8 digits)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentHkdAccountInfo
          - `accountType` 'HKD_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Hong Kong bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentIdrAccountInfo
          - `accountType` 'IDR_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Indonesian bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `phoneNumber` string, required — Indonesian phone number for e-wallet payments
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentMyrAccountInfo
          - `accountType` 'MYR_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Malaysian bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentPhpAccountInfo
          - `accountType` 'PHP_ACCOUNT', required
          - `bankName` string, required — Name of the beneficiary's bank
          - `accountNumber` string, required — Bank account number
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSgdAccountInfo
          - `accountType` 'SGD_ACCOUNT', required
          - `bankName` string, required — Name of the beneficiary's bank
          - `accountNumber` string, required — Bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentThbAccountInfo
          - `accountType` 'THB_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Thai bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentVndAccountInfo
          - `accountType` 'VND_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — Vietnamese bank account number
          - `swiftCode` string, required — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentAedAccountInfo
          - `accountType` 'AED_ACCOUNT', required
          - `iban` string, required — UAE IBAN (23 characters, starting with AE)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentKesAccountInfo
          - `accountType` 'KES_ACCOUNT', required
          - `phoneNumber` string, required — Kenyan mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentMwkAccountInfo
          - `accountType` 'MWK_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentRwfAccountInfo
          - `accountType` 'RWF_ACCOUNT', required
          - `phoneNumber` string, required — Rwandan mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentTzsAccountInfo
          - `accountType` 'TZS_ACCOUNT', required
          - `phoneNumber` string, required — Tanzanian mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentUgxAccountInfo
          - `accountType` 'UGX_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentXofAccountInfo
          - `accountType` 'XOF_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `region` 'BJ' | 'CI' | 'SN' | 'TG', required — Country code within the West African CFA franc zone
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentZarAccountInfo
          - `accountType` 'ZAR_ACCOUNT', required
          - `accountNumber` string, required — South African bank account number
          - `bankName` string, required — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentZmwAccountInfo
          - `accountType` 'ZMW_ACCOUNT', required
          - `phoneNumber` string, required — Zambian mobile money phone number
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBwpAccountInfo
          - `accountType` 'BWP_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentXafAccountInfo
          - `accountType` 'XAF_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `provider` string, required — The mobile money provider name
          - `region` 'CM' | 'CG', required — Country code within the Central African CFA franc zone
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentBdtAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'BDT_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `branchCode` string — The branch code
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `phoneNumber` string — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentArsAccountInfo
          - `accountType` 'ARS_ACCOUNT', required
          - `accountNumber` string, required — The static CVU (Clave Virtual Uniforme) bank account number to pay to.
        - PaymentCopAccountInfo
          - `accountType` 'COP_ACCOUNT'
          - `paymentUrl` string, uri, required — A payment URL where the customer can complete their COP deposit.
        - PaymentEgpAccountInfo
          - `accountType` 'EGP_ACCOUNT', required
          - `bankName` string, required — The name of the bank
          - `accountNumber` string, required — The account number of the bank
          - `iban` string — Egyptian IBAN (29 characters, starting with EG)
          - `swiftCode` string — The SWIFT/BIC code of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGhsAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'GHS_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `phoneNumber` string — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentGtqAccountInfo
          - `accountType` 'GTQ_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentHtgAccountInfo
          - `accountType` 'HTG_ACCOUNT', required
          - `phoneNumber` string, required — The phone number in international format
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentJmdAccountInfo
          - `accountType` 'JMD_ACCOUNT', required
          - `accountNumber` string, required — The account number of the bank
          - `branchCode` string, required — The branch code
          - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentPkrAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: bankName, phoneNumber
          - `accountType` 'PKR_ACCOUNT', required
          - `accountNumber` string — The account number of the bank
          - `iban` string — Pakistani IBAN (24 characters, starting with PK)
          - `phoneNumber` string — The phone number in international format
          - `bankName` string — The name of the bank
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSlvAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankAccountType, accountNumber - MOBILE_MONEY: phoneNumber
          - `accountType` 'SLV_ACCOUNT', required
          - `bankName` string — The name of the bank (BANK_TRANSFER only)
          - `accountNumber` string — The account number of the bank (BANK_TRANSFER only)
          - `bankAccountType` 'CHECKING' | 'SAVINGS' — The bank account type (BANK_TRANSFER only)
          - `phoneNumber` string — The phone number in international format (MOBILE_MONEY only — e.g. Tigo Money)
          - `paymentRails` string[], required
          - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
        - PaymentSparkWalletInfo
          - `accountType` 'SPARK_WALLET', required
          - `address` string, required — Spark wallet address
          - `assetType` 'BTC' | 'USDB', required — Type of asset
          - `invoice` string — Invoice for the payment
        - PaymentLightningInvoiceInfo
          - `accountType` 'LIGHTNING'
          - `invoice` string, required — Invoice for the payment
        - PaymentSolanaWalletInfo
          - `accountType` 'SOLANA_WALLET', required
          - `address` string, required — Solana wallet address
          - `assetType` 'USDC' | 'USDT' — Type of asset
        - PaymentTronWalletInfo
          - `accountType` 'TRON_WALLET', required
          - `address` string, required — Tron wallet address
          - `assetType` 'USDT' — Type of asset
        - PaymentPolygonWalletInfo
          - `accountType` 'POLYGON_WALLET', required
          - `address` string, required — Polygon eth wallet address
          - `assetType` 'USDC' — Type of asset
        - PaymentBaseWalletInfo
          - `accountType` 'BASE_WALLET', required
          - `address` string, required — Base eth wallet address
          - `assetType` 'USDC' — Type of asset
        - PaymentEthereumWalletInfo
          - `accountType` 'ETHEREUM_WALLET', required
          - `address` string, required — Ethereum L1 wallet address
          - `assetType` 'USDC' — 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 Turnkey API-key stamp is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet.
    - `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
    - `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' — 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.

## Other responses

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

## Changes

- **2026-05-28** `d0bce562bffd` — 14 breaking, 6 warning, 9 info
  - the response property `oneOf[subschema #1: Incoming Transaction]/allOf[subschema #2]/reconciliationInstructions/reference` became optional for the status `201`
  - the response property `oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/accountNumber` became optional for the status `201`
  - the response property `oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/branchCode` became optional for the status `201`
  - the response property `oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/phoneNumber` became optional for the status `201`
  - …25 more
- …earlier changes not shown

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

---

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