Sign in
Transfers

Create a new transfer

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

post/v1/transfers

Headers

X-API-Keystring

API key

Idempotency-Keystring

Optional idempotency key (UUID) to prevent duplicate transfers

Request body

clientReferenceIdstring

Client's internal reference ID (e.g., order ID, transaction ID)

onBehalfOfstring required

Primary customer ID (on whose behalf the transfer is made)

counterpartyIdstring

Counterparty ID for third-party recipient transfers. Omit for first-party transfers.

quoteIdstring

Quote ID to use for rate and amount calculation

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)

remarksstring

Free-form remarks or notes about the transfer (e.g., invoice discrepancy explanations)

internalRemarksstring

Internal remarks visible only within your organization. Never forwarded to payment rails (SWIFT, ACH, etc.) or counterparties.

developerFeeFixednumber

Fixed developer fee in minor units of source currency. Added on top of provider fees and deducted from the transfer amount.

developerFeePercentnumber

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%).

documentIdsstring[]

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).

expiresAtstring 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.

confirmboolean

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.

requiresAuthorizationboolean

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.

Example request

{
  "clientReferenceId": "order_abc123",
  "onBehalfOf": "cus_abc123",
  "counterpartyId": "cp_abc123",
  "amount": {
    "currency": "USD",
    "rawValue": "1000000"
  },
  "quoteId": "quote_xyz789",
  "source": {
    "accountId": "inw_abc123",
    "currency": "USDC",
    "paymentRail": "ETHEREUM",
    "direction": "CREDIT",
    "refundAccountId": "inw_abc123"
  },
  "destination": {
    "correspondentBankName": "Bank of America",
    "correspondentBankSwiftCode": "IRVTUS3NXXX",
    "correspondentAccountNumber": "9876543210",
    "accountId": "acc_def456",
    "currency": "USDC",
    "paymentRail": "ETHEREUM",
    "wireMessage": "Payment for invoice INV-2026-001",
    "sepaReference": "INV-2026-001",
    "achReference": "ORDER123",
    "blockchainMemo": "MEMO123456",
    "swiftReference": "Payment for Invoice\\nReference: INV-2026-001",
    "rtpReference": "Payment for invoice INV-2026-001"
  },
  "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
  "remarks": "Partial payment - remaining balance to be paid next month",
  "internalRemarks": "Approved by ops on 2026-04-15",
  "developerFeeFixed": 100,
  "developerFeePercent": 0.015,
  "documentIds": [
    "doc_abc123",
    "doc_def456"
  ],
  "expiresAt": "2026-12-31T23:59:59Z"
}

Response

Transfer created successfully

idstring required

Transfer ID (tfr_xxx)

organizationIdstring required

Organization ID

clientReferenceIdstring nullable

Client's internal reference ID

sourceCustomerIdstring required

Source customer ID

counterpartyIdstring nullable

Counterparty ID for third-party recipient transfers

agentIdstring nullable

Agent whose key created or submitted this transfer. Null when the transfer was not made by an agent key.

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

quoteIdstring nullable

Quote ID if transfer was created from a quote

exchangeRatestring nullable

Exchange rate applied to the currency conversion, inclusive of all fees. Expressed on minor-unit amounts: destinationAmount = sourceAmount * exchangeRate. Populated for FX trades.

referenceRatestring

Independent reference rate used to price this transfer, expressed as destination major units per source major unit. Present for benchmark-priced FX transfers.

referenceRateAsOfstring

Timestamp of the independent reference rate used to price this transfer (ISO 8601).

referenceProvider'XE'

Independent market that published referenceRate. Present when referenceRate is present.

developerFeeFixedstring nullable

Fixed developer fee in minor units of source currency. Prefer the developerFee object, which also carries the collected amount and payout hash.

developerFeePercentnumber 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.

createdAtstring date-time required

Transfer creation date

updatedAtstring date-time required

Transfer last update date

currentLegIndexnumber nullable

Index of the current active leg in the legs array (0-indexed). Null if all legs are done.

fundingNeededboolean required

Whether the transfer is waiting for the customer to send funds (deposit)

isThirdPartyboolean

Whether this is a third-party payment (destination account belongs to someone other than the customer)

remarksstring nullable

Free-form remarks or notes about the transfer

internalRemarksstring nullable

Internal remarks visible only within your organization. Never forwarded to payment rails or counterparties.

uetrstring nullable

SWIFT UETR (Universal End-to-End Transaction Reference)

imadstring nullable

Wire IMAD (Input Message Accountability Data)

omadstring nullable

Wire OMAD (Output Message Accountability Data)

achTraceNumberstring nullable

ACH trace number from the payment network

txHashstring nullable

Blockchain transaction hash

systemRemarkstring nullable

System-generated status note with important transfer context for the customer

metadataobject

Additional non-contractual transfer metadata for UI display

estimatedSettlementAtstring 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.

nextCutoffAtstring date-time nullable

Next time the customer can submit and still settle same business day. Past this time, transfers settle next business day.

cutoffTimezonestring nullable

IANA timezone for the cutoff time, e.g. "America/New_York".

Example response

{
  "id": "tfr_1234567890abcdef",
  "organizationId": "org_abc123",
  "clientReferenceId": "order_abc123",
  "sourceCustomerId": "cus_abc123",
  "counterpartyId": "cp_abc123",
  "agentId": "agt_abc123",
  "flow": "CRYPTO_TO_FIAT",
  "status": "COMPLETED",
  "source": {
    "currency": "usd",
    "fundingCurrency": "usdc",
    "paymentRail": "ACH",
    "direction": "CREDIT",
    "accountId": "vba_abc123",
    "accountType": "VIRTUAL_BANK",
    "externalAccountId": "ext_bank_456",
    "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "refundAccountId": "inw_abc123",
    "accountName": "Acme Corporation",
    "originator": {
      "name": "Acme Suppliers LLC",
      "bankName": "Example National Bank",
      "routingNumber": "021000021",
      "accountNumber": "987654321",
      "swiftBic": "CHASUS33",
      "bankCountry": "US"
    }
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM",
    "accountId": "vwa_def456",
    "accountType": "EXTERNAL_BANK",
    "externalAccountId": "ext_bank_789",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "accountName": "Acme Corporation",
    "bankName": "JPMorgan Chase Bank",
    "bankCountryCode": "US",
    "wireMessage": "Payment for invoice INV-2026-001",
    "achReference": "ORDER123",
    "swiftReference": "Payment for invoice INV-2026-001",
    "rtpReference": "Payment for invoice INV-2026-001",
    "payoutReference": "INV2026"
  },
  "sourceAmount": {
    "currency": "USD",
    "exponent": 2,
    "value": "12345",
    "displayValue": "123.45"
  },
  "destinationAmount": {
    "currency": "USD",
    "exponent": 2,
    "value": "12345",
    "displayValue": "123.45"
  },
  "refund": {
    "status": "COMPLETED",
    "reason": "Fees exceed deposit amount",
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "txHash": "0x1234567890abcdef..."
  },
  "quoteId": "quote_abc123",
  "exchangeRate": "0.99985",
  "referenceRate": "1.158691536019208779",
  "referenceRateAsOf": "2026-09-02T18:30:04.000Z",
  "referenceProvider": "XE",
  "developerFeeFixed": "100",
  "developerFeePercent": 0.005,
  "developerFee": {
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "fixed": "100",
    "percent": 0.005,
    "txHash": "0x1234567890abcdef..."
  },
  "depositInstructions": {
    "type": "crypto",
    "paymentRail": "ETHEREUM",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "accountId": "acc_abc123"
  },
  "createdAt": "2026-09-15T10:00:00.000Z",
  "updatedAt": "2026-09-15T10:00:00.000Z",
  "legs": [
    {
      "id": "tleg_abc123",
      "type": "DEPOSIT_CRYPTO",
      "inputCurrency": "USDC",
      "outputCurrency": "USD",
      "inputRail": "ETHEREUM",
      "outputRail": "ACH",
      "status": "PENDING",
      "uetr": "9b6f37f2-21f0-4b2b-b03c-1893364782ce",
      "imad": "20260309EREBBANK000002",
      "omad": "20260309MMQFMP0B012345",
      "achTraceNumber": "021000021234567",
      "txHash": "0x1234567890abcdef...",
      "developerFee": {
        "currency": "USD",
        "exponent": 2,
        "value": "12345",
        "displayValue": "123.45"
      },
      "feeTxHash": "0x1234567890abcdef..."
    }
  ],
  "remarks": "Partial payment - remaining balance to be paid next month",
  "uetr": "9b6f37f2-21f0-4b2b-b03c-1893364782ce",
  "imad": "20260309EREBBANK000002",
  "omad": "20260309MMQFMP0B012345",
  "achTraceNumber": "021000021234567",
  "txHash": "0x1234567890abcdef...",
  "systemRemark": "Tracking is unavailable for this SWIFT transfer. We will auto-complete it after 24 hours and mark it with an asterisk because settlement is assumed rather than confirmed.",
  "metadata": {
    "swiftRouting": {
      "source": "GPI_ROUTE",
      "senderBic": "CHASUS33",
      "receiverBic": "CLRBGB22",
      "checkedAt": "2026-05-10T16:34:42.597Z",
      "steps": [
        {
          "label": "Sender bank",
          "bic": "CHASUS33",
          "bankName": "JP Morgan Chase",
          "status": "Confirmed Active"
        }
      ]
    }
  },
  "estimatedSettlementAt": "2026-05-26T13:00:00.000Z",
  "nextCutoffAt": "2026-05-19T19:00:00.000Z",
  "cutoffTimezone": "America/New_York",
  "counterparty": {
    "id": "cp_abc123",
    "name": "Jane Doe",
    "beneficiaryType": "INDIVIDUAL",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "transliterated": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "city": "Beijing",
        "state": "Hebei"
      }
    }
  }
}

Changes

Changed in 6 of the 19 revisions of this API.62

  • bb2702829ce054See the full diff
    • ○

      added the new AED enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new ARS enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new AUD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new BHD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new BRL enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CAD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CASH enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CHF enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CNH enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CNY enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new COP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new CZK enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new DAI enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new DAI enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new DKK enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new EGP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new ETH enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new ETH enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new EURC enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new EURC enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new GBP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new HKD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new HUF enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new IDR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new ILS enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new INR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new JPY enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new KRW enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new KWD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new MYR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new NOK enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new NZD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new PHP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new PKR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new PLN enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new PYUSD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new PYUSD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new QAR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new RON enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new RUB enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new SAR enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new SEK enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new SGD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new THB enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new TRY enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new TWD enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDB enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDB enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDP enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDS enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new USDS enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new VND enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new ZAR enum value to the request property /////

      request-property-enum-value-added

  • da62fa03793e3See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property ///// to the response with the status

      response-optional-property-added

    • ○

      added the optional property ///// to the response with the status

      response-optional-property-added

  • b83888a376d81See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 03a24c5c95252See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 382abbca8b011See the full diff
    • ○

      added the optional property ////////// to the response with the status

      response-optional-property-added

  • bca54100a6371See the full diff
    • ○

      added the optional property ///// to the response with the status

      response-optional-property-added