GET
/
collections
/
{collectionId}
Get collection.
curl --request GET \
  --url https://sandbox.api.openfx.com/v1/collections/{collectionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>'
{
  "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.

Path Parameters

​
collectionId
string
required

Unique identifier of the collection (col_ prefix). Collection resource identifier.

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

"col_01953e1a5f4b7c00"

Response

Collection details.

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"