Create ACH payment.

curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments/ach \
  --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": {
    "currency": "USD",
    "value": "150000"
  },
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "achType": "standard",
  "secCode": "WEB",
  "reference": "<string>",
  "metadata": {}
}
'

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

ACH Payments

Create ACH payment.

Create a domestic US ACH payment. Creates the same Payment resource as POST /payments with rail: ach, but with a simpler request schema.

ACH-specific options:

achType: standard — next-day settlement (default)
achType: same_day — same-day settlement (cutoff ~2:45 PM ET)
secCode — NACHA Standard Entry Class: WEB (consumer internet), PPD (prearranged consumer), CCD (corporate), CTX (corporate with addenda)

Returns: ACH payments may be returned up to 60 days after settlement. The achReturnCode field on the Payment provides the NACHA return reason (R01-R51).

POST

payments

ach

Create ACH payment.

curl --request POST \
  --url https://sandbox.api.openfx.com/v1/payments/ach \
  --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": {
    "currency": "USD",
    "value": "150000"
  },
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "achType": "standard",
  "secCode": "WEB",
  "reference": "<string>",
  "metadata": {}
}
'

{
  "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 ACH payment creation. Creates a standard Payment resource.

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

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

counterpartyId

string

Counterparty resource identifier.

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

Example:

"cpt_01953e1a5f4b7004"

achType

enum<string>

ACH transfer speed.

Available options:

standard,

same_day

secCode

enum<string>

NACHA Standard Entry Class code.

Available options:

WEB,

PPD,

CCD

reference

string

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

ACH 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 Get ach payment

Identity & Onboarding

Accounts & Balances

FX & Conversions

Counterparties & Payment Methods

Payments & Transfers

Ledger

Events & Webhooks

Payment Rails Discovery

Create ACH payment.

Authorizations

Headers

Body

Response