Create ACH debit collection.

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

{
  "id": "col_01953e1a5f4b7c00",
  "customerId": "cus_01953e1a5f4b7000",
  "destinationAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "amount": {
    "currency": "USD",
    "amount": "2500.00"
  },
  "direction": "inbound",
  "status": "completed",
  "cancellationState": "not_cancelable",
  "totalCreditAmount": {
    "currency": "USD",
    "amount": "2495.00"
  },
  "reference": "INVOICE-2026-001",
  "createdAt": "2026-02-25T10:00:00Z",
  "updatedAt": "2026-02-25T10:05:00Z",
  "submittedAt": "2026-02-25T10:00:01Z",
  "completedAt": "2026-02-25T10:05:00Z"
}

POST

collections

ach

Create ACH debit collection.

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

{
  "id": "col_01953e1a5f4b7c00",
  "customerId": "cus_01953e1a5f4b7000",
  "destinationAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "amount": {
    "currency": "USD",
    "amount": "2500.00"
  },
  "direction": "inbound",
  "status": "completed",
  "cancellationState": "not_cancelable",
  "totalCreditAmount": {
    "currency": "USD",
    "amount": "2495.00"
  },
  "reference": "INVOICE-2026-001",
  "createdAt": "2026-02-25T10:00:00Z",
  "updatedAt": "2026-02-25T10:05:00Z",
  "submittedAt": "2026-02-25T10:00:01Z",
  "completedAt": "2026-02-25T10: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

Create an ACH debit collection with rail-native parameters.

destinationAccountId

string

required

Account where collected funds will be credited.

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

Example:

"acc_01953e1a5f4b7002"

paymentMethodId

string

required

Payment method of type us_bank.

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 being debited. Derived from payment method if omitted.

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

Example:

"cpt_01953e1a5f4b7004"

achType

enum<string>

ACH processing speed. Defaults to standard.

Available options:

standard,

same_day

secCode

enum<string>

NACHA SEC code. Defaults to WEB.

Available options:

WEB,

PPD,

CCD

reference

string

Payment reference for reconciliation.

purpose

string

Purpose of the collection.

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 collection created.

An initiated inbound pull payment. Collections debit an external account (via the counterparty's payment method) and credit an OpenFX account. ACH debit collections have a 60-day return window even after completion.

string

required

Collection resource identifier.

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

Example:

"col_01953e1a5f4b7c00"

customerId

string

required

Customer resource identifier.

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

Example:

"cus_01953e1a5f4b7000"

destinationAccountId

string

required

Account where collected funds are credited.

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

Example:

"acc_01953e1a5f4b7002"

counterpartyId

string

required

Counterparty resource identifier.

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

Example:

"cpt_01953e1a5f4b7004"

paymentMethodId

string

required

External account being debited (e.g., us_bank type).

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

Example:

"pm_01953e1a5f4b7300"

rail

enum<string>

required

Rail used for the collection. Currently ACH only. SEPA Direct Debit and other pull-payment rails will be added in future versions.

Available options:

ach

amount

object

required

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

direction

enum<string>

required

Always inbound — funds flow from external to OpenFX. Collections are pull payments initiated by the platform.

Available options:

inbound

status

enum<string>

required

Collection lifecycle status. ACH debits have a 60-day return window even after reaching completed.

Available options:

pending,

requires_action,

submitted,

processing,

completed,

returned,

failed,

canceled

createdAt

string<date-time>

required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

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

cancellationState

enum<string>

Whether the payment can currently be canceled.

Available options:

cancelable,

not_cancelable

requiresActionReason

enum<string> | null

Reason why a collection is in requires_action status.

Available options:

compliance_hold,

rfi_pending,

authorization_required

compliance

object

Read-only compliance metadata on payments and counterparties.

Show child attributes

fees

object

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

Show child attributes

totalCreditAmount

object

Net amount credited after fees.

Show child attributes

Example:

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

reference

string

Payment reference for reconciliation.

purpose

string

Purpose of the collection.

railDetails

object

Rail-specific details (ACH trace number, etc.).

achReturnCode

enum<string> | null

ACH return reason code, present when status is returned.

Available options:

R01,

R02,

R03,

R04,

R05,

R06,

R07,

R08,

R09,

R10,

R11,

R13,

R14,

R15,

R16,

R17,

R20,

R23,

R29,

R51

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

updatedAt

string<date-time>

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

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

submittedAt

string<date-time> | null

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

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

completedAt

string<date-time> | null

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

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

Get collection Get ach collection

Identity & Onboarding

Accounts & Balances

FX & Conversions

Counterparties & Payment Methods

Payments & Transfers

Ledger

Events & Webhooks

Payment Rails Discovery

Create ACH debit collection.

Authorizations

Headers

Body

Response