curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "sendAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "amountInputSide": "send",
  "reference": "INV-2026-001"
}
'

{
  "id": "pmt_01953e1a5f4b7005",
  "customerId": "cus_01953e1a5f4b7000",
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "status": "completed",
  "direction": "outbound",
  "rail": "ach",
  "sendAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "receiveAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "amountInputSide": "send",
  "executionPreference": "at_market",
  "fees": {
    "feeAmount": {
      "currency": "USD",
      "amount": "2.50"
    },
    "feeCurrency": "USD",
    "feeComponents": [
      {
        "type": "ach_fee",
        "amount": "2.50",
        "currency": "USD"
      }
    ]
  },
  "totalDebitAmount": {
    "currency": "USD",
    "amount": "1502.50"
  },
  "cancellationState": "not_cancelable",
  "reference": "INV-2026-001",
  "metadata": {},
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:05:00Z",
  "completedAt": "2026-02-23T12:05:00Z"
}

Payments

Create payment.

Create an outbound payment via the unified endpoint. This endpoint accepts any supported rail via the rail field with discriminator-based polymorphism.

Prerequisites:

Source account must be active with sufficient balance
Counterparty and payment method must exist and be active
For cross-currency: either provide a quoteId or set executionPreference: at_market

What happens after creation:

Payment is created in created status (returned in response)
If compliance screening is required, enters requires_action
If CoP/VoP verification is needed, enters requires_action with cop_required or beneficiary_verification_required
Payment moves through in_review → processing → completed
Webhook payment.completed (or payment.failed) fires

Compliance gates are non-bypassable. If a payment requires action, it cannot proceed until the action is taken.

For simpler schemas, use rail-specific endpoints (POST /payments/ach, etc.) which don’t require the rail discriminator field.

POST

payments

curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "sendAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "amountInputSide": "send",
  "reference": "INV-2026-001"
}
'

{
  "id": "pmt_01953e1a5f4b7005",
  "customerId": "cus_01953e1a5f4b7000",
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "status": "completed",
  "direction": "outbound",
  "rail": "ach",
  "sendAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "receiveAmount": {
    "currency": "USD",
    "amount": "1500.00"
  },
  "amountInputSide": "send",
  "executionPreference": "at_market",
  "fees": {
    "feeAmount": {
      "currency": "USD",
      "amount": "2.50"
    },
    "feeCurrency": "USD",
    "feeComponents": [
      {
        "type": "ach_fee",
        "amount": "2.50",
        "currency": "USD"
      }
    ]
  },
  "totalDebitAmount": {
    "currency": "USD",
    "amount": "1502.50"
  },
  "cancellationState": "not_cancelable",
  "reference": "INV-2026-001",
  "metadata": {},
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:05:00Z",
  "completedAt": "2026-02-23T12:05:00Z"
}

Authorizations

Authorization

string

header

required

API key issued at onboarding. Passed as a Bearer token in the Authorization header: Authorization: Bearer <api-key>. Identifies the caller and determines organization scope. Invalid or revoked keys return 401 with error type authentication_error.

X-Signature

string

header

required

Ed25519 or RSA-SHA256 asymmetric signature over the request payload (ADR-0015). Provides request integrity and non-repudiation. The signature covers the HTTP method, path, query string, request body, and timestamp. Invalid signatures return 401 with error type authentication_error.

X-Timestamp

string

header

required

Unix timestamp (seconds) of when the request was signed. Server rejects requests where the timestamp drifts beyond +/-60 seconds from server time to prevent replay attacks. Must match the timestamp used in the signature computation.

Headers

Idempotency-Key

string

required

Idempotency key for this request. UUID v4 recommended. Max 128 characters. 24-hour retention. Same key + same body replays original response with Idempotency-Replayed: true. Same key + different body returns 409 (code: duplicate_idempotency_key). Same key while the original request is still processing returns 409 with a Retry-After header (code: idempotency_key_in_flight).

Maximum string length: 128

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Unified payment creation. Specify the rail and payment method. For cross-currency, provide either a quoteId (use_quote) or set executionPreference to at_market. For rail-specific options (achType, secCode, chargeBearer, sepaType), use the dedicated rail endpoints (POST /payments/{rail}).

sourceAccountId

string

required

Account resource identifier.

Pattern: ^acc_[A-Za-z0-9]+$

Example:

"acc_01953e1a5f4b7002"

paymentMethodId

string

required

Payment method resource identifier.

Pattern: ^pm_[A-Za-z0-9]+$

Example:

"pm_01953e1a5f4b7300"

rail

enum<string>

required

Payment rail used for delivery.

Available options:

ach,

fedwire,

swift,

crypto,

open

counterpartyId

string

Counterparty resource identifier.

Pattern: ^cpt_[A-Za-z0-9]+$

Example:

"cpt_01953e1a5f4b7004"

sendAmount

object

Monetary amount for request input. Value MUST be in smallest currency unit (e.g., cents for USD, pence for GBP). Server derives exponent from currency.

Show child attributes

Example:

{ "currency": "USD", "value": "150000" }

receiveAmount

object

Monetary amount for request input. Value MUST be in smallest currency unit (e.g., cents for USD, pence for GBP). Server derives exponent from currency.

Show child attributes

Example:

{ "currency": "USD", "value": "150000" }

amountInputSide

enum<string>

Which side of the payment amount is authoritative. 'send' means the sender's debit amount is fixed; 'receive' means the recipient's credit amount is fixed.

Available options:

send,

receive

executionPreference

enum<string>

Controls FX execution on cross-currency payments. use_quote requires a pre-locked quoteId. at_market executes at current market rate.

Available options:

use_quote,

at_market

quoteId

string

FX quote resource identifier.

Pattern: ^qte_[A-Za-z0-9]+$

Example:

"qte_01953e1a5f4b7006"

reference

string

purpose

enum<string>

Purpose of payment. Required for SWIFT and SEPA payments to certain corridors.

Available options:

goods_and_services,

intercompany_transfer,

investments,

payroll,

treasury_management,

pension,

tax_payment,

trade_of_goods,

financial_services,

donations_and_charity,

rent_and_lease,

reimbursement,

salary_and_compensation,

other

travelRule

object

FATF Travel Rule data. Required for crypto payments above jurisdictional thresholds. Originator info is auto-populated from the customer entity when omitted.

Show child attributes

metadata

object

Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.

Show child attributes

Response

Payment created.

An outbound payment instruction. Created via the unified POST /payments endpoint or rail-specific convenience endpoints. All create the same resource with the same status machine and webhook events.

string

required

Payment resource identifier.

Pattern: ^pmt_[A-Za-z0-9]+$

Example:

"pmt_01953e1a5f4b7005"

customerId

string

required

Customer resource identifier.

Pattern: ^cus_[A-Za-z0-9]+$

Example:

"cus_01953e1a5f4b7000"

status

enum<string>

required

External lifecycle status of a payment. Terminal states: completed, returned, reversed, refunded, failed, canceled.

Available options:

created,

requires_action,

in_review,

processing,

completed,

returned,

reversed,

refunded,

failed,

canceled

rail

enum<string>

required

Payment rail used for delivery.

Available options:

ach,

fedwire,

swift,

crypto,

open

createdAt

string<date-time>

required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

updatedAt

string<date-time>

required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

sourceAccountId

string

Account resource identifier.

Pattern: ^acc_[A-Za-z0-9]+$

Example:

"acc_01953e1a5f4b7002"

counterpartyId

string

Counterparty resource identifier.

Pattern: ^cpt_[A-Za-z0-9]+$

Example:

"cpt_01953e1a5f4b7004"

paymentMethodId

string

Payment method resource identifier.

Pattern: ^pm_[A-Za-z0-9]+$

Example:

"pm_01953e1a5f4b7300"

direction

enum<string>

default:outbound

Payment direction. Always 'outbound' — inbound payments are tracked via the separate InboundPayment resource.

Available options:

outbound

sendAmount

object

Monetary amount with exponent-based precision. Value is in smallest currency unit (e.g., cents for USD). displayValue is the human-readable decimal.

Show child attributes

Example:

{
  "currency": "USD",
  "exponent": 2,
  "value": "150000",
  "displayValue": "1500.00"
}

receiveAmount

object

Monetary amount with exponent-based precision. Value is in smallest currency unit (e.g., cents for USD). displayValue is the human-readable decimal.

Show child attributes

Example:

{
  "currency": "USD",
  "exponent": 2,
  "value": "150000",
  "displayValue": "1500.00"
}

amountInputSide

enum<string>

Which side of the payment amount is authoritative. 'send' means the sender's debit amount is fixed; 'receive' means the recipient's credit amount is fixed.

Available options:

send,

receive

executionPreference

enum<string>

Controls FX execution on cross-currency payments. use_quote requires a pre-locked quoteId. at_market executes at current market rate.

Available options:

use_quote,

at_market

quoteId

string | null

FX quote resource identifier.

Pattern: ^qte_[A-Za-z0-9]+$

Example:

"qte_01953e1a5f4b7006"

exchangeRate

object

FX rate information embedded in payments and conversions.

Show child attributes

fees

object

Fee details on payments and estimates. Per ADR-0006.

Show child attributes

totalDebitAmount

object

Monetary amount with exponent-based precision. Value is in smallest currency unit (e.g., cents for USD). displayValue is the human-readable decimal.

Show child attributes

Example:

{
  "currency": "USD",
  "exponent": 2,
  "value": "150000",
  "displayValue": "1500.00"
}

cancellationState

enum<string>

Whether the payment can currently be canceled.

Available options:

cancelable,

not_cancelable

requiresActionReason

enum<string> | null

Reason why a payment is in requires_action status.

Available options:

cop_required,

beneficiary_verification_required,

rfi_pending,

quote_expired,

return_action_required,

compliance_hold,

travel_rule_required

compliance

object

Read-only compliance metadata on payments and counterparties.

Show child attributes

railDetails

object

Rail-specific details (ACH SEC code, SWIFT charges, etc.).

reference

string

Consumer-defined payment reference.

Example:

"INV-2026-001"

purpose

enum<string>

Purpose of payment. Required for SWIFT and SEPA payments to certain corridors.

Available options:

goods_and_services,

intercompany_transfer,

investments,

payroll,

treasury_management,

pension,

tax_payment,

trade_of_goods,

financial_services,

donations_and_charity,

rent_and_lease,

reimbursement,

salary_and_compensation,

other

metadata

object

Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.

Show child attributes

completedAt

string<date-time> | null

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

achReturnCode

enum<string> | null

ACH return reason code. Present only when rail is ach and the payment has been returned.

Available options:

R01,

R02,

R03,

R04,

R05,

R06,

R07,

R08,

R09,

R10,

R11,

R13,

R14,

R15,

R16,

R17,

R20,

R23,

R29,

R51

cryptoNetwork

enum<string> | null

Blockchain network used for crypto payments. Present only when rail is crypto.

Available options:

ethereum,

solana,

base,

ink,

sui

cryptoTransferStatus

enum<string> | null

On-chain confirmation status for crypto payments. Present only when rail is crypto.

Available options:

pending_confirmation,

confirmed,

failed

travelRule

object

Travel rule data transmitted for this payment. Present only for crypto payments.

Show child attributes

verificationResult

object

Beneficiary name verification result (CoP/VoP). Present when payment has undergone beneficiary verification.

Show child attributes

Get payment method List payments

Identity & Onboarding

Accounts & Balances

FX & Conversions

Counterparties & Payment Methods

Payments & Transfers

Ledger

Events & Webhooks

Payment Rails Discovery

Create payment.

Authorizations

Headers

Body

Response