v1

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-023911.7 KB

Transfers

Create a transfer

Initiate a new payment transfer. Idempotent via optional idempotency-key header. The transfer enters the INITIATED state and proceeds through the state machine: INITIATED → SUBMITTED → ACCEPTED → SETTLED (or → RETURNED / → FAILED).

post/api/transfers

Headers

x-tenant-idstring required

Tenant identifier

x-canonical-version'1' required

API version — must be "1"

idempotency-keystring uuid

Optional idempotency key. If a transfer with the same key already exists, the original transfer is returned with 200 instead of 201.

Request body

tenantIdstring required

intent'AUTH' | 'CAPTURE' | 'PUSH' | 'PULL' required

sourceCurrencystring required

ISO 4217 currency code

targetCurrencystring required

ISO 4217 currency code

fxStrategy'NOT_APPLICABLE' | 'QUOTE_AT_SUBMIT' | 'PASS_THROUGH' required

railHintsstring[]

Preferred rails for routing

feeModelstring

Fee model identifier

endUserRefstring

End-user reference (e.g., invoice number)

externalRefstring

External system reference

traceparentstring

W3C traceparent header for distributed tracing

metadataobject

Arbitrary key-value metadata

Response

Idempotent duplicate — returns existing transfer

transferIdstring uuid

railstring nullable