---
title: "Create a new transfer"
method: POST
path: "/v1/transfers"
tags: ["Transfers"]
---

# Create a new transfer

`POST /v1/transfers`

Create a new transfer. Use the Idempotency-Key header to prevent duplicate creation.

## Headers

- `X-API-Key` string
- `Idempotency-Key` string

## Request body

- CreateTransferDto
  - `clientReferenceId` string — Client's internal reference ID (e.g., order ID, transaction ID)
  - `onBehalfOf` string, required — Primary customer ID (on whose behalf the transfer is made)
  - `counterpartyId` string — Counterparty ID for third-party recipient transfers. Omit for first-party transfers.
  - `amount` MoneyInputDto, required
    - `currency` string, required — Currency code (ISO 4217 for fiat, symbol for crypto)
    - `rawValue` string, required — Amount in smallest unit as a string (cents for USD, satoshi for BTC, etc.)
  - `quoteId` string — Quote ID to use for rate and amount calculation
  - `source` TransferSourceDto, required
    - `accountId` string — Source account ID. For Infinite Wallets: if TREASURY wallet, funds will be automatically transferred on submit. If TRANSACTION wallet, deposit instructions will be provided.
    - `currency` 'USD' | 'EUR' | 'MXN' | 'USAT' | 'USDC' | 'USDT' | 'BTC', required — Source currency code
    - `paymentRail` 'ACH' | 'ACH_SAME_DAY' | 'WIRE' | 'FED_NOW' | 'RTP' | 'EREBOR' | 'EREBOR_RAIL' | 'BALANCE' | 'SWIFT' | 'SEPA' | 'SEPA_INSTANT' | 'TIPS' | 'FASTER_PAYMENTS' | 'BACS' | 'CHAPS' | 'ELIXIR' | 'NICS' | 'EFT' | 'INTERAC' | 'NPP' | 'BECS' | 'UPI' | 'IMPS' | 'IMPS_WITH_FIRC' | 'NEFT' | 'RTGS' | 'BI_FAST' | 'ARTAJASA' | 'PIX' | 'TED' | 'TEF' | 'SPEI' | 'COELSA' | 'SINPE' | 'CIPS' | 'CFXPS' | 'CHATS' | 'ZENGIN' | 'KFTC' | 'FAST_SG' | 'MEPS' | 'DUITNOW' | 'PROMPTPAY' | 'INSTAPAY' | 'PESONET' | 'NAPAS' | 'BEFTN' | 'SLIPS' | 'ZAHAV' | 'GHIPSS' | 'NIBSS' | 'PESALINK' | 'RTC_ZA' | 'TZS_RTGS' | 'EGP_ACH' | 'JOD_ACH' | 'NPSS' | 'MADA' | 'QPS' | 'DOP_ACH' | 'GTQ_ACH' | 'HNL_ACH' | 'PEN_ACH' | 'JMD_ACH' | 'USD_ACH_SV' | 'USD_ACH_EC' | 'CLP_TEF' | 'PSE' | 'COP_ACH' | 'BOB_RTGS' | 'PYG_ACH' | 'CERTIS' | 'DKK_TIPS' | 'SENT' | 'NKS' | 'BANKGIROT' | 'HKD_FPS' | 'IBFT' | 'TRY_FAST' | 'ETHEREUM' | 'BASE' | 'POLYGON' | 'SOLANA' | 'TRON' | 'BITCOIN' | 'ARBITRUM', required — Payment rail for the source funds. For crypto, specify the blockchain (ETHEREUM, BASE, ARBITRUM, POLYGON, SOLANA, TRON). For fiat, specify the banking network (ACH, WIRE, SEPA, SWIFT). Provider-backed bank balances may also use EREBOR, and on-us Erebor bank transfers use EREBOR_RAIL.
    - `direction` 'CREDIT' | 'DEBIT' — ACH direction. Optional when source.paymentRail is ACH and source.accountId is provided. If omitted for an account-backed ACH source, the API defaults to CREDIT. DEBIT is currently provider-disabled for Erebor-backed virtual bank account sources.
    - `refundAccountId` string — Customer wallet account ID (inw_xxx or ewa_xxx) that receives refunds for failed crypto transfers or when fees exceed deposit. Must belong to the customer and include a wallet address; validated at request time.
  - `destination` TransferDestinationDto, required
    - `correspondentBankName` string — Correspondent/intermediary bank name
    - `correspondentBankSwiftCode` string — Correspondent/intermediary bank SWIFT/BIC code (8 or 11 characters)
    - `correspondentAccountNumber` string — Correspondent/intermediary account number
    - `accountId` string, required — Account ID for the destination of funds
    - `currency` 'USD' | 'EUR' | 'MXN' | 'USAT' | 'USDC' | 'USDT' | 'BTC', required — Destination currency code
    - `paymentRail` 'ACH' | 'ACH_SAME_DAY' | 'WIRE' | 'FED_NOW' | 'RTP' | 'EREBOR' | 'EREBOR_RAIL' | 'BALANCE' | 'SWIFT' | 'SEPA' | 'SEPA_INSTANT' | 'TIPS' | 'FASTER_PAYMENTS' | 'BACS' | 'CHAPS' | 'ELIXIR' | 'NICS' | 'EFT' | 'INTERAC' | 'NPP' | 'BECS' | 'UPI' | 'IMPS' | 'IMPS_WITH_FIRC' | 'NEFT' | 'RTGS' | 'BI_FAST' | 'ARTAJASA' | 'PIX' | 'TED' | 'TEF' | 'SPEI' | 'COELSA' | 'SINPE' | 'CIPS' | 'CFXPS' | 'CHATS' | 'ZENGIN' | 'KFTC' | 'FAST_SG' | 'MEPS' | 'DUITNOW' | 'PROMPTPAY' | 'INSTAPAY' | 'PESONET' | 'NAPAS' | 'BEFTN' | 'SLIPS' | 'ZAHAV' | 'GHIPSS' | 'NIBSS' | 'PESALINK' | 'RTC_ZA' | 'TZS_RTGS' | 'EGP_ACH' | 'JOD_ACH' | 'NPSS' | 'MADA' | 'QPS' | 'DOP_ACH' | 'GTQ_ACH' | 'HNL_ACH' | 'PEN_ACH' | 'JMD_ACH' | 'USD_ACH_SV' | 'USD_ACH_EC' | 'CLP_TEF' | 'PSE' | 'COP_ACH' | 'BOB_RTGS' | 'PYG_ACH' | 'CERTIS' | 'DKK_TIPS' | 'SENT' | 'NKS' | 'BANKGIROT' | 'HKD_FPS' | 'IBFT' | 'TRY_FAST' | 'ETHEREUM' | 'BASE' | 'POLYGON' | 'SOLANA' | 'TRON' | 'BITCOIN' | 'ARBITRUM', required — Payment rail for destination (banking network or blockchain)
    - `wireMessage` string — Wire transfer message (max 140 chars)
    - `sepaReference` string — SEPA reference (6-140 chars, limited charset: a-z A-Z 0-9 & - . / and space)
    - `achReference` string — ACH reference (max 10 chars, alphanumeric and spaces)
    - `blockchainMemo` string — Blockchain memo (for Stellar, Tron, etc.)
    - `swiftReference` string — SWIFT reference (max 4 lines, 35 chars per line, separated by \n)
    - `rtpReference` string — RTP reference (max 140 chars, limited charset: a-z A-Z 0-9 & - . / and space)
  - `paymentReason` 'CAPITAL_CONTRIBUTIONS' | 'CHARITABLE_CONTRIBUTIONS' | 'CONSULTING_FEES' | 'CORPORATE_TAX_PAYMENTS' | 'DOWN_PAYMENTS_FOR_REAL_ESTATE' | 'EDUCATION_FEES' | 'EMPLOYEE_SALARIES_OR_WAGES' | 'EXPENSES_REIMBURSEMENT' | 'GIFTS' | 'GOVERNMENT_GRANTS' | 'INCOME_TAX_PAYMENTS' | 'INHERITANCE_PAYMENTS' | 'INSURANCE_CLAIM_PAYOUTS' | 'INSURANCE_PREMIUM_PAYMENTS' | 'INVESTMENTS' | 'LOAN_ADVANCES' | 'MORTGAGE_PAYMENTS' | 'OTHER' | 'PAYMENT_FOR_GOODS_AND_SERVICES' | 'PERSONAL_TRANSFERS' | 'REAL_ESTATE_PURCHASES' | 'REMITTANCES' | 'RENT' | 'REPAYMENT_OF_LOANS' | 'ROYALTIES' | 'SELF' | 'TRADE_SETTLEMENT' | 'TRUST_FUND_DISTRIBUTIONS' | 'UTILITY_BILLS' | 'WELFARE_OR_BENEFITS' | 'WINNINGS_AND_PRIZES', required — Reason for the payment (compliance/AML)
  - `remarks` string — Free-form remarks or notes about the transfer (e.g., invoice discrepancy explanations)
  - `internalRemarks` string — Internal remarks visible only within your organization. Never forwarded to payment rails (SWIFT, ACH, etc.) or counterparties.
  - `developerFeeFixed` number — Fixed developer fee in minor units of source currency. Added on top of provider fees and deducted from the transfer amount.
  - `developerFeePercent` number — Developer fee as decimal percentage (e.g., 0.015 for 1.5%). Deducted from the transfer amount before sending to the destination. Maximum 0.1 (10%).
  - `documentIds` string[] — Supporting document IDs for the transfer. Required for third-party SWIFT payments (when the destination account is marked as third-party or the destination customer differs from the originating customer).
  - `expiresAt` string, date-time — Optional transfer expiration timestamp. If omitted, the transfer expires 7 days after creation when funded by a fiat pay-in (wire/ACH) and 48 hours after creation otherwise.
  - `confirm` boolean — If true, immediately submit the transfer for processing after creation. If false or omitted, transfer is created in DRAFT status and can be submitted later via POST /transfers/:id/submit.
  - `requiresAuthorization` boolean — If true, this payment must be authorized before it is processed. Attach the supporting invoice via documentIds. The transfer parks in PENDING_AUTHORIZATION and does not move funds until it is approved.

## Response `201`

Transfer created successfully

- TransferResponseDto
  - `id` string, required — Transfer ID (tfr_xxx)
  - `organizationId` string, required — Organization ID
  - `clientReferenceId` string, nullable — Client's internal reference ID
  - `sourceCustomerId` string, required — Source customer ID
  - `counterpartyId` string, nullable — Counterparty ID for third-party recipient transfers
  - `flow` 'CRYPTO_TO_CRYPTO' | 'CRYPTO_TO_FIAT' | 'FIAT_TO_CRYPTO' | 'FIAT_TO_FIAT' | 'FIAT_TO_CRYPTO_TO_FIAT' | 'FX' | 'INTERNAL' | 'FEE_CRYPTO' | 'REFUND_CRYPTO' | 'REFUND_FIAT', required — Transfer flow type describing the asset conversion
  - `status` 'DRAFT' | 'PENDING_AUTHORIZATION' | 'IN_REVIEW' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'REVERSED', required — Transfer status
  - `source` TransferSourceResponseDto, required
    - `currency` string, required — Source currency code
    - `fundingCurrency` string, nullable — Asset the transfer was funded with when it differs from the settlement currency (e.g. a stablecoin deposit settled as fiat at face value)
    - `paymentRail` string, required — Source payment rail
    - `direction` 'CREDIT' | 'DEBIT', nullable — ACH direction when the source rail is ACH
    - `accountId` string, nullable — Account ID if applicable
    - `accountType` 'VIRTUAL_BANK' | 'VIRTUAL_WALLET' | 'INFINITE_BANK' | 'INFINITE_WALLET' | 'EXTERNAL_BANK' | 'EXTERNAL_WALLET' | 'EXTERNAL_PROXY' | 'PROVIDER_BALANCE', nullable — Account type for quick filtering
    - `externalAccountId` string, nullable — External account ID if applicable
    - `fromAddress` string, nullable — Source wallet address (for crypto sources)
    - `refundAccountId` string, nullable — Customer wallet account ID (inw_xxx or ewa_xxx) that receives refunds for failed crypto transfers or when fees exceed deposit
    - `accountName` string, nullable — Account holder name
  - `destination` TransferDestinationResponseDto, required
    - `currency` string, required — Destination currency code
    - `paymentRail` string, required — Destination payment rail
    - `accountId` string, nullable — Account ID if applicable
    - `accountType` 'VIRTUAL_BANK' | 'VIRTUAL_WALLET' | 'INFINITE_BANK' | 'INFINITE_WALLET' | 'EXTERNAL_BANK' | 'EXTERNAL_WALLET' | 'EXTERNAL_PROXY' | 'PROVIDER_BALANCE', nullable — Account type for quick filtering
    - `externalAccountId` string, nullable — External account ID if applicable
    - `toAddress` string, nullable — Destination wallet address (for crypto destinations)
    - `accountName` string, nullable — Account holder name
    - `wireMessage` string, nullable — Wire message if applicable
    - `achReference` string, nullable — ACH reference if applicable
    - `swiftReference` string, nullable — SWIFT reference if applicable
    - `rtpReference` string, nullable — RTP reference if applicable
    - `payoutReference` string, nullable — Payment reference that appears on the recipient bank statement, for fiat payouts. Populated once the payout has been initiated.
  - `sourceAmount` MoneyOutputDto, required
    - `currency` string, required — Currency code
    - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
    - `value` string, required — Amount in smallest unit as a string
    - `displayValue` string, required — Human-readable decimal value
  - `destinationAmount` MoneyOutputDto
    - `currency` string, required — Currency code
    - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
    - `value` string, required — Amount in smallest unit as a string
    - `displayValue` string, required — Human-readable decimal value
  - `refund` TransferRefundResponseDto
    - `status` 'INITIATED' | 'COMPLETED', required — Current refund status
    - `reason` string, nullable — Reason the transfer was refunded
    - `amount` MoneyOutputDto
      - `currency` string, required — Currency code
      - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
      - `value` string, required — Amount in smallest unit as a string
      - `displayValue` string, required — Human-readable decimal value
    - `address` string, nullable — Destination address used for the refund
    - `txHash` string, nullable — Refund transaction hash
    - `initiatedAt` string, date-time, nullable — When the refund was initiated
    - `completedAt` string, date-time, nullable — When the refund completed
  - `quoteId` string, nullable — Quote ID if transfer was created from a quote
  - `exchangeRate` string, nullable — Exchange rate applied to the currency conversion, inclusive of all fees. Expressed on minor-unit amounts: destinationAmount = sourceAmount * exchangeRate. Populated for FX trades.
  - `developerFeeFixed` string, nullable — Fixed developer fee in minor units of source currency. Prefer the `developerFee` object, which also carries the collected amount and payout hash.
  - `developerFeePercent` number, nullable — Variable developer fee as decimal percentage (e.g., 0.005 = 0.5%). Prefer the `developerFee` object, which also carries the collected amount and payout hash.
  - `developerFee` TransferDeveloperFeeDto
    - `amount` MoneyOutputDto
      - `currency` string, required — Currency code
      - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
      - `value` string, required — Amount in smallest unit as a string
      - `displayValue` string, required — Human-readable decimal value
    - `fixed` string, nullable — Configured fixed fee component, in minor units of the source currency.
    - `percent` number, nullable — Configured variable fee component as a decimal fraction (e.g., 0.005 = 0.5%).
    - `txHash` string, nullable — Transaction hash of the on-chain movement that paid the fee out to your configured fee wallet. Shared with the payout hash when the fee was split atomically in the same transaction. Null when the fee settled without a dedicated on-chain hop.
  - `depositInstructions` union — Deposit instructions if customer needs to send funds (onramps). Either crypto or fiat instructions depending on the transfer flow.
    - CryptoDepositInstructionsDto
      - `type` string, required — Instruction type
      - `paymentRail` string, required — Payment rail (blockchain)
      - `toAddress` string, required — Destination wallet address
      - `amount` MoneyOutputDto, required
        - `currency` string, required — Currency code
        - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
        - `value` string, required — Amount in smallest unit as a string
        - `displayValue` string, required — Human-readable decimal value
      - `blockchainMemo` string, nullable — Blockchain memo (for chains that require it)
      - `accountId` string, nullable — Account ID for the deposit destination
    - FiatDepositInstructionsDto
      - `type` string, required — Instruction type
      - `paymentRail` string, required — Payment rail
      - `direction` 'CREDIT' | 'DEBIT', nullable — ACH direction when the funding instructions are ACH-specific
      - `amount` MoneyOutputDto, required
        - `currency` string, required — Currency code
        - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
        - `value` string, required — Amount in smallest unit as a string
        - `displayValue` string, required — Human-readable decimal value
      - `bankName` string, nullable — Bank name
      - `bankAddress` BankAddressDto
        - `addressLine1` string — Address line 1 (optional for bank addresses)
        - `addressLine2` string — Address line 2 (apartment, suite, etc.)
        - `city` string — City
        - `state` string — State / Province
        - `postalCode` string — Postal code / ZIP code (optional for bank addresses)
        - `country` string — Country code (ISO 3166-2)
      - `accountNumber` string, nullable — Account number
      - `routingNumber` string, nullable — Routing number (US)
      - `beneficiaryName` string, nullable — Beneficiary name
      - `beneficiaryAddress` BankAddressDto
        - `addressLine1` string — Address line 1 (optional for bank addresses)
        - `addressLine2` string — Address line 2 (apartment, suite, etc.)
        - `city` string — City
        - `state` string — State / Province
        - `postalCode` string — Postal code / ZIP code (optional for bank addresses)
        - `country` string — Country code (ISO 3166-2)
      - `iban` string, nullable — IBAN (international)
      - `swiftBic` string, nullable — SWIFT/BIC code
      - `depositMessage` string, nullable — Deposit message/reference to include in the transfer
      - `clabe` string, nullable — CLABE (Mexico)
      - `accountId` string, nullable — Account ID for the deposit destination
  - `createdAt` string, date-time, required — Transfer creation date
  - `updatedAt` string, date-time, required — Transfer last update date
  - `legs` TransferStepDto[], required — Transfer route legs (steps in the transfer)
    - `id` string, required — Step ID
    - `sequence` number, required — Sequence in the route (0-indexed)
    - `type` 'DEPOSIT_CRYPTO' | 'DEPOSIT_FIAT' | 'ONRAMP' | 'CONVERT' | 'OFFRAMP' | 'CRYPTO_TRANSFER' | 'BRIDGE' | 'OUTBOUND_TOP_UP' | 'INBOUND_TOP_UP' | 'REFUND_CRYPTO' | 'REFUND_FIAT' | 'LIQUIDITY_ADVANCE', required — Step type
    - `inputCurrency` string, required — Input currency
    - `outputCurrency` string, required — Output currency
    - `inputRail` string, required — Input rail
    - `outputRail` string, required — Output rail
    - `status` 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'SKIPPED', required — Step status
    - `startedAt` string, date-time, nullable — When the step started processing
    - `completedAt` string, date-time, nullable — When the step completed
    - `uetr` string, nullable — SWIFT UETR (Universal End-to-End Transaction Reference)
    - `imad` string, nullable — Wire IMAD (Input Message Accountability Data)
    - `omad` string, nullable — Wire OMAD (Output Message Accountability Data)
    - `achTraceNumber` string, nullable — ACH trace number from the payment network
    - `txHash` string, nullable — Blockchain transaction hash. Populated for on-chain customer wallet movements: crypto deposits, crypto sends to the destination wallet, and crypto refunds. Null for internal settlement steps.
    - `developerFee` MoneyOutputDto
      - `currency` string, required — Currency code
      - `exponent` number, required — Number of decimal places for this currency (e.g., 2 for USD, 6 for USDC)
      - `value` string, required — Amount in smallest unit as a string
      - `displayValue` string, required — Human-readable decimal value
    - `feeTxHash` string, nullable — Transaction hash of the on-chain movement that paid this step's developer fee to your configured fee wallet. Matches txHash when the fee was split atomically in the same transaction; null when the fee settled without a dedicated on-chain hop.
  - `currentLegIndex` number, nullable — Index of the current active leg in the legs array (0-indexed). Null if all legs are done.
  - `fundingNeeded` boolean, required — Whether the transfer is waiting for the customer to send funds (deposit)
  - `isThirdParty` boolean — Whether this is a third-party payment (destination account belongs to someone other than the customer)
  - `remarks` string, nullable — Free-form remarks or notes about the transfer
  - `internalRemarks` string, nullable — Internal remarks visible only within your organization. Never forwarded to payment rails or counterparties.
  - `uetr` string, nullable — SWIFT UETR (Universal End-to-End Transaction Reference)
  - `imad` string, nullable — Wire IMAD (Input Message Accountability Data)
  - `omad` string, nullable — Wire OMAD (Output Message Accountability Data)
  - `achTraceNumber` string, nullable — ACH trace number from the payment network
  - `txHash` string, nullable — Blockchain transaction hash
  - `systemRemark` string, nullable — System-generated status note with important transfer context for the customer
  - `metadata` object — Additional non-contractual transfer metadata for UI display
  - `estimatedSettlementAt` string, date-time, nullable — Estimated time the recipient will receive funds. Best-effort projection — fiat rails account for bank cutoff times, weekends, and US Federal Reserve holidays; crypto conversions project from recently observed processing times for the route. Not a guarantee.
  - `nextCutoffAt` string, date-time, nullable — Next time the customer can submit and still settle same business day. Past this time, transfers settle next business day.
  - `cutoffTimezone` string, nullable — IANA timezone for the cutoff time, e.g. "America/New_York".
  - `counterparty` CounterpartyResponseDto
    - `id` string, required — Counterparty ID
    - `name` string, required — Counterparty legal name
    - `beneficiaryType` 'INDIVIDUAL' | 'BUSINESS', required — Entity type (individual or business)
    - `address` AddressDto
      - `addressLine1` string, required — Address line 1
      - `addressLine2` string — Address line 2 (apartment, suite, etc.)
      - `city` string, required — City
      - `state` string — State / Province
      - `postalCode` string, required — Postal code / ZIP code. May be empty for countries without a postal-code system, including the United Arab Emirates.
      - `country` string, required — Country code (ISO 3166-2)
      - `transliterated` TransliteratedAddressDto
        - `addressLine1` string — Transliterated address line 1 (Latin characters)
        - `addressLine2` string — Transliterated address line 2 (Latin characters)
        - `city` string — Transliterated city (Latin characters)
        - `state` string — Transliterated state/province (Latin characters)
    - `createdAt` string, date-time, required — Creation timestamp
    - `updatedAt` string, date-time, required — Last update timestamp

## Other responses

- `401` — Unauthorized - Invalid or missing authentication credentials

---

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