Skip to main content
POST
CLI

Authorizations

​
Authorization
string
header
required

API Key in Bearer format (e.g., Bearer sk_test_...)

Headers

​
X-API-Key
string

API key

​
Idempotency-Key
string

Optional idempotency key (UUID) to prevent duplicate transfers

Body

application/json
​
onBehalfOf
string
required

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

Example:

"cus_abc123"

​
amount
object
required

Transfer amount

Example:
​
source
object
required

Source payment details

​
destination
object
required

Destination payment details

​
paymentReason
enum<string>
required

Reason for the payment (compliance/AML)

Available options:
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
Example:

"PAYMENT_FOR_GOODS_AND_SERVICES"

​
clientReferenceId
string

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

Maximum string length: 256
Example:

"order_abc123"

​
counterpartyId
string

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

Example:

"cp_abc123"

​
quoteId
string

Quote ID to use for rate and amount calculation

Example:

"quote_xyz789"

​
remarks
string

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

Maximum string length: 1000
Example:

"Partial payment - remaining balance to be paid next month"

​
internalRemarks
string

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

Maximum string length: 1000
Example:

"Approved by ops on 2026-04-15"

​
developerFeeFixed
number

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

Example:

100

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

Required range: x <= 0.1
Example:

0.015

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

Example:
​
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.

Example:

"2026-12-31T23:59:59Z"

​
confirm
boolean
default:false

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
default:false

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

Transfer created successfully

​
id
string
required

Transfer ID (tfr_xxx)

Example:

"tfr_1234567890abcdef"

​
organizationId
string
required

Organization ID

Example:

"org_abc123"

​
sourceCustomerId
string
required

Source customer ID

Example:

"cus_abc123"

​
flow
enum<string>
required

Transfer flow type describing the asset conversion

Available options:
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
Example:

"CRYPTO_TO_FIAT"

​
status
enum<string>
required

Transfer status

Available options:
DRAFT,
PENDING_AUTHORIZATION,
IN_REVIEW,
PENDING,
PROCESSING,
COMPLETED,
FAILED,
CANCELLED,
REVERSED
Example:

"COMPLETED"

​
source
object
required

Source payment details

​
destination
object
required

Destination payment details

​
sourceAmount
object
required

Source amount with currency details

​
createdAt
string<date-time>
required

Transfer creation date

Example:

"2026-09-15T10:00:00.000Z"

​
updatedAt
string<date-time>
required

Transfer last update date

Example:

"2026-09-15T10:00:00.000Z"

​
legs
object[]
required

Transfer route legs (steps in the transfer)

​
fundingNeeded
boolean
required

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

Example:

false

​
clientReferenceId
string | null

Client's internal reference ID

Example:

"order_abc123"

​
counterpartyId
string | null

Counterparty ID for third-party recipient transfers

Example:

"cp_abc123"

​
agentId
string | null

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

Example:

"agt_abc123"

​
agentApprovalStatus
enum<string> | null

Owner approval for an agent payment that went over its limits. PENDING: the draft waits for POST /v1/transfers/{id}/agent-approval. Null when no approval was needed.

Available options:
PENDING,
APPROVED,
DECLINED
​
destinationAmount
object | null

Destination amount with currency details

​
refund
object | null

Refund details when this transfer has been refunded or a refund is in progress

​
quoteId
string | null

Quote ID if transfer was created from a quote

Example:

"quote_abc123"

​
exchangeRate
string | null

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

Example:

"0.99985"

​
referenceRate
string

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

Example:

"1.158691536019208779"

​
referenceRateAsOf
string

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

Example:

"2026-09-02T18:30:04.000Z"

​
referenceProvider
enum<string>

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

Available options:
XE
Example:

"XE"

​
developerFeeFixed
string | null

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

Example:

"100"

​
developerFeePercent
number | null

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.

Example:

0.005

​
developerFee
object | null

Developer fee charged on this transfer: the configured components plus the collected amount and the on-chain payout hash for reconciliation against your fee wallet. Null when the transfer has no developer fee. Per-step collected amounts and fee tx hashes are on legs[].

​
depositInstructions
object

Deposit instructions if customer needs to send funds (onramps). Either crypto or fiat instructions depending on the transfer flow.

​
returnedToAccountId
string | null

Account credited when a settled payout is returned. Null unless the return is attributed to one account on this transfer.

Example:

"acc_123"

​
returnedAt
string<date-time> | null

When the payout return was recorded. Account history uses this time for returned credits.

Example:

"2026-09-15T10:00:00.000Z"

​
currentLegIndex
number | null

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

Example:

0

​
isThirdParty
boolean

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

Example:

false

​
remarks
string | null

Free-form remarks or notes about the transfer

Example:

"Partial payment - remaining balance to be paid next month"

​
internalRemarks
string | null

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

​
uetr
string | null

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

Example:

"9b6f37f2-21f0-4b2b-b03c-1893364782ce"

​
imad
string | null

Wire IMAD (Input Message Accountability Data)

Example:

"20260309EREBBANK000002"

​
omad
string | null

Wire OMAD (Output Message Accountability Data)

Example:

"20260309MMQFMP0B012345"

​
achTraceNumber
string | null

ACH trace number from the payment network

Example:

"021000021234567"

​
originatingAccount
object | null

Sending bank and account used for the fiat payout, when known

​
txHash
string | null

Blockchain transaction hash

Example:

"0x1234567890abcdef..."

​
systemRemark
string | null

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

Example:

"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
object

Additional non-contractual transfer metadata for UI display

Example:
​
estimatedSettlementAt
string<date-time> | null

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.

Example:

"2026-05-26T13:00:00.000Z"

​
nextCutoffAt
string<date-time> | null

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

Example:

"2026-05-19T19:00:00.000Z"

​
cutoffTimezone
string | null

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

Example:

"America/New_York"

​
counterparty
object

Expanded counterparty details (only included when expand=counterparty)