--- 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` object, required — Source external account details - `accountId` string, required — Reference to an external account ID - `destination` object, required — Destination internal account details - `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' | 'SENT' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PROCESSING` | Funding has been received and payment initiated | | `SENT` | Cross border settlement has been initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired | - `type` 'INCOMING', required — Type of transaction (incoming payment or outgoing payment) - `destination` union, required - AccountTransactionDestination — Destination account details - `currency` string — Currency code for the destination - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressTransactionDestination — UMA address destination details - `currency` string — Currency code for the destination - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - ExternalAccountDetailsTransactionDestination — Transaction destination where external account details were provided inline at quote creation rather than using a pre-registered external account. - `currency` string — Currency code for the destination - `destinationType` 'EXTERNAL_ACCOUNT_DETAILS', required - `externalAccountDetails` ExternalAccountCreateRequest, required - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform. - `currency` string, required — The ISO 4217 currency code - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier. - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. - `accountInfo` union, required - BrlExternalAccountInfo - … - CadExternalAccountInfo - … - DkkExternalAccountInfo - … - EurExternalAccountInfo - … - GbpExternalAccountInfo - … - HkdExternalAccountInfo - … - IdrExternalAccountInfo - … - InrExternalAccountInfo - … - MxnExternalAccountInfo - … - MyrExternalAccountInfo - … - NgnExternalAccountInfo - … - PhpExternalAccountInfo - … - SgdExternalAccountInfo - … - ThbExternalAccountInfo - … - UsdExternalAccountInfo - … - VndExternalAccountInfo - … - SparkWalletExternalAccountInfo - … - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. - … - SolanaWalletExternalAccountInfo - … - TronWalletExternalAccountInfo - … - PolygonWalletExternalAccountInfo - … - BaseWalletExternalAccountInfo - … - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming) - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming) - `settledAt` string, date-time — When the payment was or will be settled - `createdAt` string, date-time — When the transaction was created - `updatedAt` string, date-time — When the transaction was last updated - `description` string — Optional memo or description for the payment - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses. - `source` union - AccountTransactionSource — Source account details - `currency` string — Currency code for the source - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - UmaAddressTransactionSource — UMA address source details - `currency` string — Currency code for the source - `sourceType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the sender - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). - `currency` string, required — Currency code for the funding source - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — The customer on whose behalf the transaction was initiated. - `receivedAmount` CurrencyAmount, required - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `reconciliationInstructions` ReconciliationInstructions - `reference` string, required — Unique reference code that must be included with the payment to match it with the correct incoming transaction - `rateDetails` IncomingRateDetails — Details about the rate and fees for an incoming transaction. - `gridApiMultiplier` number, double, required — The underlying multiplier from the mSATS to the receiving currency, including variable fees. - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. - OutgoingTransaction - `id` string, required — Unique identifier for the transaction - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'SENT' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PROCESSING` | Funding has been received and payment initiated | | `SENT` | Cross border settlement has been initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired | - `type` 'OUTGOING', required — Type of transaction (incoming payment or outgoing payment) - `destination` union, required - AccountTransactionDestination — Destination account details - `currency` string — Currency code for the destination - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressTransactionDestination — UMA address destination details - `currency` string — Currency code for the destination - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - ExternalAccountDetailsTransactionDestination — Transaction destination where external account details were provided inline at quote creation rather than using a pre-registered external account. - `currency` string — Currency code for the destination - `destinationType` 'EXTERNAL_ACCOUNT_DETAILS', required - `externalAccountDetails` ExternalAccountCreateRequest, required - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform. - `currency` string, required — The ISO 4217 currency code - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier. - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. - `accountInfo` union, required - BrlExternalAccountInfo - … - CadExternalAccountInfo - … - DkkExternalAccountInfo - … - EurExternalAccountInfo - … - GbpExternalAccountInfo - … - HkdExternalAccountInfo - … - IdrExternalAccountInfo - … - InrExternalAccountInfo - … - MxnExternalAccountInfo - … - MyrExternalAccountInfo - … - NgnExternalAccountInfo - … - PhpExternalAccountInfo - … - SgdExternalAccountInfo - … - ThbExternalAccountInfo - … - UsdExternalAccountInfo - … - VndExternalAccountInfo - … - SparkWalletExternalAccountInfo - … - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. - … - SolanaWalletExternalAccountInfo - … - TronWalletExternalAccountInfo - … - PolygonWalletExternalAccountInfo - … - BaseWalletExternalAccountInfo - … - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming) - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming) - `settledAt` string, date-time — When the payment was or will be settled - `createdAt` string, date-time — When the transaction was created - `updatedAt` string, date-time — When the transaction was last updated - `description` string — Optional memo or description for the payment - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses. - `source` union, required - AccountTransactionSource — Source account details - `currency` string — Currency code for the source - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - UmaAddressTransactionSource — UMA address source details - `currency` string — Currency code for the source - `sourceType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the sender - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). - `currency` string, required — Currency code for the funding source - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — The customer on whose behalf the transaction was initiated. - `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). - `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 - `countries` string[], required - `paymentRails` string[], required - `accountNumber` string, required — The account number of the bank - `routingNumber` string, required — The routing number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentBrlAccountInfo - `accountType` 'BRL_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `pixKey` string, required — The PIX key of the bank - `pixKeyType` string, required — The type of PIX key of the bank - `taxId` string, required — The tax ID of the bank account - PaymentMxnAccountInfo - `accountType` 'MXN_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `clabeNumber` string, required — The CLABE number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentDkkAccountInfo - `accountType` 'DKK_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `iban` string, required — The IBAN of the bank - `swiftBic` string — The SWIFT BIC of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentEurAccountInfo - `accountType` 'EUR_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `iban` string, required — The IBAN of the bank - `swiftBic` string — The SWIFT BIC of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentInrAccountInfo - `accountType` 'INR_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `vpa` string, required — The VPA of the bank - PaymentNgnAccountInfo - `accountType` 'NGN_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `accountNumber` string, required — Nigerian bank account number - `bankName` string, required — Name of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentCadAccountInfo - `accountType` 'CAD_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankCode` string, required — Canadian financial institution number (3 digits) - `branchCode` string, required — Transit number identifying the branch (5 digits) - `accountNumber` string, required — Bank account number (7-12 digits) - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentGbpAccountInfo - `accountType` 'GBP_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens) - `accountNumber` string, required — UK bank account number (8 digits) - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentHkdAccountInfo - `accountType` 'HKD_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — The bank name of the bank - `accountNumber` string, required — The account number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentIdrAccountInfo - `accountType` 'IDR_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `sortCode` string, required — The sort code of the bank - `accountNumber` string, required — The account number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentMyrAccountInfo - `accountType` 'MYR_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — The bank name of the bank - `accountNumber` string, required — The account number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentPhpAccountInfo - `accountType` 'PHP_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — Name of the beneficiary's bank - `accountNumber` string, required — Bank account number - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentSgdAccountInfo - `accountType` 'SGD_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — Name of the beneficiary's bank - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `accountNumber` string, required — Bank account number - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentThbAccountInfo - `accountType` 'THB_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — The bank name of the bank - `accountNumber` string, required — The account number of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentVndAccountInfo - `accountType` 'VND_ACCOUNT', required - `countries` string[], required - `paymentRails` string[], required - `bankName` string, required — The bank name of the bank - `accountNumber` string, required — The account number of the bank - `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 - `refund` Refund - `reference` string, required — The unique reference code of the refund - `initiatedAt` string, date-time, required — When the refund was initiated - `settledAt` string, date-time — When the refund was or will be settled - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. - `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' | 'TIMEOUT' — 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-02-25** `c62cf646aaeb` — 28 breaking, 9 warning - added `#/components/schemas/Error400_INVALID_INPUT, #/components/schemas/Error400_MISSING_MANDATORY_USER_INFO, #/components/schemas/Error400_INVITATION_ALREADY_CLAIMED, #/components/schemas/Error400_INVITATIONS_NOT_CONFIGURED, #/components/schemas/Error400_INVALID_UMA_ADDRESS, #/components/schemas/Error400_INVITATION_CANCELLED, #/components/schemas/Error400_QUOTE_REQUEST_FAILED, #/components/schemas/Error400_INVALID_PAYREQ_RESPONSE, #/components/schemas/Error400_INVALID_RECEIVER, #/components/schemas/Error400_PARSE_PAYREQ_RESPONSE_ERROR, #/components/schemas/Error400_CERT_CHAIN_INVALID, #/components/schemas/Error400_CERT_CHAIN_EXPIRED, #/components/schemas/Error400_INVALID_PUBKEY_FORMAT, #/components/schemas/Error400_MISSING_REQUIRED_UMA_PARAMETERS, #/components/schemas/Error400_SENDER_NOT_ACCEPTED, #/components/schemas/Error400_AMOUNT_OUT_OF_RANGE, #/components/schemas/Error400_INVALID_CURRENCY, #/components/schemas/Error400_INVALID_TIMESTAMP, #/components/schemas/Error400_INVALID_NONCE, #/components/schemas/Error400_INVALID_REQUEST_FORMAT, #/components/schemas/Error400_INVALID_BANK_ACCOUNT, #/components/schemas/Error400_SELF_PAYMENT, #/components/schemas/Error400_LOOKUP_REQUEST_FAILED, #/components/schemas/Error400_PARSE_LNURLP_RESPONSE_ERROR, #/components/schemas/Error400_INVALID_AMOUNT, #/components/schemas/Error400_WEBHOOK_ENDPOINT_NOT_SET, #/components/schemas/Error400_WEBHOOK_DELIVERY_ERROR` to the response body `oneOf` list for the response status `400` - added `#/components/schemas/Error401_UNAUTHORIZED, #/components/schemas/Error401_INVALID_SIGNATURE` to the response body `oneOf` list for the response status `401` - added `#/components/schemas/Error404_TRANSACTION_NOT_FOUND, #/components/schemas/Error404_INVITATION_NOT_FOUND, #/components/schemas/Error404_USER_NOT_FOUND, #/components/schemas/Error404_QUOTE_NOT_FOUND, #/components/schemas/Error404_LOOKUP_REQUEST_NOT_FOUND, #/components/schemas/Error404_TOKEN_NOT_FOUND, #/components/schemas/Error404_BULK_UPLOAD_JOB_NOT_FOUND, #/components/schemas/Error404_REFERENCE_NOT_FOUND` to the response body `oneOf` list for the response status `404` - added `#/components/schemas/Error500_GRID_SWITCH_ERROR, #/components/schemas/Error500_INTERNAL_ERROR` to the response body `oneOf` list for the response status `500` - …33 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/c62cf646aaeb/schema)