Create crypto payment.

curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments/crypto \
  --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",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "amount": {
    "asset": "USDC",
    "value": "500000000",
    "chain": "ethereum"
  },
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "reference": "<string>",
  "travelRule": {
    "originator": {
      "name": "<string>",
      "accountNumber": "<string>",
      "address": {
        "line1": "123 Main Street",
        "city": "New York",
        "postalCode": "10001",
        "country": "US",
        "line2": "Suite 400",
        "state": "NY"
      },
      "dateOfBirth": "1985-03-15",
      "nationalIdentification": "<string>",
      "entityType": "individual"
    },
    "beneficiary": {
      "name": "<string>",
      "accountNumber": "<string>",
      "address": {
        "line1": "123 Main Street",
        "city": "New York",
        "postalCode": "10001",
        "country": "US",
        "line2": "Suite 400",
        "state": "NY"
      },
      "dateOfBirth": "1985-03-15",
      "nationalIdentification": "<string>",
      "entityType": "individual"
    },
    "originatorVasp": {
      "name": "<string>",
      "lei": "<string>",
      "jurisdiction": "US"
    },
    "beneficiaryVasp": {
      "name": "<string>",
      "lei": "<string>",
      "jurisdiction": "US"
    }
  },
  "metadata": {},
  "network": "ethereum"
}
'

{
  "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"
}

Crypto Payments

Create crypto payment.

Create an outbound crypto transfer. Creates the same Payment resource as POST /payments with rail: crypto, but with a crypto-native request schema.

Travel Rule (FATF Recommendation 16): For crypto transfers above jurisdictional thresholds ( $1,000 FATF/EU,$ 3,000 US), originator and beneficiary data must be provided via the travelRule field. EU and UK require travel rule data for ALL crypto transfers regardless of amount. Originator info is auto-populated from the customer’s entity record when omitted.

Networks: Specify the target blockchain via the network field. Supported chains: ethereum, solana, tron, base, polygon.

Confirmation tracking: The Payment response includes cryptoTransferStatus (pending_confirmation → confirmed or failed) to track on-chain confirmation.

POST

payments

crypto

Create crypto payment.

curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments/crypto \
  --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",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "amount": {
    "asset": "USDC",
    "value": "500000000",
    "chain": "ethereum"
  },
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "reference": "<string>",
  "travelRule": {
    "originator": {
      "name": "<string>",
      "accountNumber": "<string>",
      "address": {
        "line1": "123 Main Street",
        "city": "New York",
        "postalCode": "10001",
        "country": "US",
        "line2": "Suite 400",
        "state": "NY"
      },
      "dateOfBirth": "1985-03-15",
      "nationalIdentification": "<string>",
      "entityType": "individual"
    },
    "beneficiary": {
      "name": "<string>",
      "accountNumber": "<string>",
      "address": {
        "line1": "123 Main Street",
        "city": "New York",
        "postalCode": "10001",
        "country": "US",
        "line2": "Suite 400",
        "state": "NY"
      },
      "dateOfBirth": "1985-03-15",
      "nationalIdentification": "<string>",
      "entityType": "individual"
    },
    "originatorVasp": {
      "name": "<string>",
      "lei": "<string>",
      "jurisdiction": "US"
    },
    "beneficiaryVasp": {
      "name": "<string>",
      "lei": "<string>",
      "jurisdiction": "US"
    }
  },
  "metadata": {},
  "network": "ethereum"
}
'

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

Rail-specific crypto payment creation. For crypto transfers, FATF Travel Rule data may be required depending on the jurisdiction and transfer amount. Originator info is auto-populated from the customer's entity record when omitted.

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"

amount

object

required

Crypto amount for request input. Value MUST be in smallest unit (e.g., for USDC with 6 decimals, "500000000" = 500.000000).

Show child attributes

Example:

{
  "asset": "USDC",
  "value": "500000000",
  "chain": "ethereum"
}

counterpartyId

string

Counterparty resource identifier.

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

Example:

"cpt_01953e1a5f4b7004"

reference

string

travelRule

object

FATF Travel Rule data. Required for crypto transfers above jurisdictional thresholds ($1,000 FATF/EU, $3,000 US). EU/UK require data for ALL transfers.

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

network

enum<string>

Target blockchain network for the crypto payment.

Available options:

ethereum,

solana,

base,

ink,

sui

Response

Crypto 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 swift payment Get crypto payment

Identity & Onboarding

Accounts & Balances

FX & Conversions

Counterparties & Payment Methods

Payments & Transfers

Ledger

Events & Webhooks

Payment Rails Discovery

Create crypto payment.

Authorizations

Headers

Body

Response