POST
/
collections
Create collection.
curl --request POST \
  --url https://sandbox.api.openfx.com/v1/collections \
  --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",
  "rail": "ach",
  "amount": {
    "currency": "USD",
    "value": "150000"
  },
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "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 a collection (pull payment) via the unified endpoint.

​
destinationAccountId
string
required

Account where collected funds will be credited.

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

"acc_01953e1a5f4b7002"

​
paymentMethodId
string
required

External account to debit (must support pull/debit operations).

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 for request input. Value MUST be in smallest currency unit (e.g., cents for USD, pence for GBP). Server derives exponent from currency.

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"

​
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.

Response

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.

​
id
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.

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.

​
fees
object

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

​
totalCreditAmount
object

Net amount credited after fees.

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.

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