MVP API (v0.1) — The ACH collections surface covers core collection creation and lifecycle tracking.

​
What Are ACH Debit Collections?

ACH debit collections pull funds from an external US bank account into your OpenFX account via the ACH network. The counterparty’s payment method must be of type us_bank (routing number and account number). Unlike ACH credit payments where you push funds to a counterparty, ACH debit collections pull funds from the counterparty’s bank account into yours. This requires prior authorization from the account holder. 
Counterparty's US Bank Account
  |
  |  <-- ACH Debit (pull)
  |
  v
Your OpenFX Account (acc_)
  +-- Funds credited after settlement
Authorization required. Before initiating an ACH debit collection, you must have obtained proper authorization from the account holder. The NACHA SEC code you specify indicates the type of authorization obtained. Unauthorized debits will be returned and may result in compliance issues.

​
SEC Codes for Collections

NACHA SEC (Standard Entry Class) codes indicate how the debit was authorized. Choose the appropriate code based on how you obtained the account holder’s consent.
SEC CodeNameUse Case
WEBInternet-initiatedConsumer authorized via web form or online portal. Default for collections.
PPDPrearranged PaymentConsumer authorized via signed agreement (recurring payments).
CCDCorporate CollectionBusiness-to-business debits with corporate authorization.
Use WEB for consumer-facing online payment collection. Use CCD for B2B invoice collection where you have a corporate authorization agreement in place.

​
Creating an ACH Debit Collection

The rail-specific POST /collections/ach endpoint provides ACH-native parameters including SEC code and processing speed. 
curl -X POST https://sandbox.api.openfx.com/v1/collections/ach \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationAccountId": "acc_01953e1a5f4b7002",
    "counterpartyId": "cpt_01953e1a5f4b7004",
    "paymentMethodId": "pm_01953e1a5f4b7300",
    "achType": "standard",
    "secCode": "WEB",
    "amount": {
      "currency": "USD", "value": "120000"
    },
    "reference": "MEMBERSHIP-2026-02",
    "purpose": "Subscription payment"
  }'
The response returns the full collection resource: 
{
  "id": "col_01953e1a5f4b7e01",
  "customerId": "cus_01953e1a5f4b7000",
  "destinationAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "amount": {
    "currency": "USD",
    "exponent": 2,
    "value": "120000",
    "displayValue": "1200.00"
  },
  "direction": "inbound",
  "status": "pending",
  "reference": "MEMBERSHIP-2026-02",
  "purpose": "Subscription payment",
  "railDetails": {
    "achType": "standard",
    "secCode": "WEB"
  },
  "metadata": {},
  "createdAt": "2026-02-25T10:00:00Z",
  "updatedAt": "2026-02-25T10:00:00Z"
}

​
Required Fields

FieldTypeDescription
destinationAccountIdstringThe OpenFX account to credit with collected funds
paymentMethodIdstringPayment method of type us_bank on the counterparty
amountMoneyAmount to collect ({ "currency": "USD", "value": "120000" })

​
Optional Fields

FieldTypeDefaultDescription
counterpartyIdstringDerived from payment methodThe counterparty being debited
achTypeenumstandardstandard (1-2 days) or same_day
secCodeenumWEBNACHA SEC code: WEB, PPD, or CCD
referencestring—Payment reference for reconciliation
purposestring—Purpose of the collection
metadataobject{}Your custom key-value pairs

​
ACH Processing Speed

TypeSettlement TimeDescription
standard1-2 business daysStandard ACH processing. Lower cost, suitable for most use cases.
same_daySame business daySame-day ACH processing. Higher cost, funds available sooner.
Same-day ACH has cutoff times. Submissions after the cutoff are processed on the next business day. Check with OpenFX for specific cutoff schedules.

​
ACH Return Handling

ACH debits can be returned by the originating bank for various reasons. Returns can arrive up to 60 calendar days after settlement.

​
Common ACH Return Codes

CodeReasonDescription
R01Insufficient fundsThe account does not have sufficient funds
R02Account closedThe bank account has been closed
R03No account / Unable to locateThe account number does not correspond to an account
R04Invalid account numberThe account number structure is invalid
R07Authorization revokedThe receiver revoked authorization
R08Payment stoppedThe receiver placed a stop payment
R10Not authorizedThe receiver claims they did not authorize the debit
R29Corporate not authorizedCorporate entry not authorized
When a return is received, the collection transitions to returned status, and the achReturnCode field is populated with the reason code. 
{
  "id": "col_01953e1a5f4b7e01",
  "status": "returned",
  "achReturnCode": "R01",
  "completedAt": "2026-02-26T14:00:00Z"
}
Design for late returns. Even after a collection reaches completed status and funds are credited to your account, a return may arrive weeks later. Your system should handle the reversal of already-credited funds. Subscribe to webhook events to be notified immediately.

​
Retrieving an ACH Collection

Use the rail-specific GET endpoint for ACH-native response fields. 
curl -X GET https://sandbox.api.openfx.com/v1/collections/ach/col_01953e1a5f4b7e01 \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"

​
Webhook Events

Subscribe to these events to track collection lifecycle changes:
EventDescription
collection.createdCollection has been created
collection.submittedCollection submitted to the ACH network
collection.processingACH network is processing the debit
collection.completedFunds received and credited to your account
collection.returnedThe debit was returned by the external bank
collection.failedCollection failed

​
API Reference