ACH Direct Debit

Learn how sellers can debit bank accounts using ACH (Automated Clearing House) networks.


Sellers in the US can accept payments from buyers using a US-based bank account. Payments that debit bank accounts get referred to as ACH Direct Debits.

Buyers often use their bank account and ACH Direct Debits as an alternative to credit and debit cards:

  • ACH Direct Debits get processed using the Automated Clearing House (ACH) payments system operated by Nacha.
  • ACH Direct Debits supports both recurring and one-time payments.

ACH Direct Debit Payments

Unlike credit card payments, ACH Direct Debit payments don't debit bank accounts in real time. Instead, it can take 4-10 business days to authorize the transaction with the buyer's bank and confirm if it failed or succeeded.

Additionally, buyers can dispute the transaction up to 60 days from the initial payment date.

To process a payment using ACH Direct Debit, collect the following from the buyer and create a Payment Instrument:

Detail Description
Bank Code The routing number of the buyer's bank account.
Account Number The account number of the buyer's bank account.
Buyer Name The buyer's name.

You can collect this information using our API or our Hosted Fields. Here's an example of using our Hosted Fields to collect bank details:

Hosted Fields

ACH Direct Debit States

You can review the three states for ACH Direct Debit payments below. ACH Direct Debit payment gets created with Transfer#state PENDING:

ACH States

Transfer#state Description
PENDING The ACH Direct Debit is being processed by Finix.
SUCCEEDED The ACH Direct Debit was accepted by Finix. The payment may or may not have been accepted by the buyer's bank at this time.
FAILED                     The ACH Direct Debit was not accepted by Finix.
attention

Transfer#state SUCCEEDED only means Finix submitted details to the ACH networks. It can take 4-10 business days for the buyer's bank to process and confirm the debit was successful.

ACH Timing

ACH Direct Debits take longer than credit card payments to move and settle funds.

To account for this, Finix creates a delay to accommodate any ACH Returns that could occur. This delay is called an ACH Settlement Delay.

By default, Finix puts in a 5-day delay before ACH Direct Debits can settle and become available for approval in a Settlement.

ACH Timing

Sellers may want ACH Debits to appear in settlements faster or slower based on their business. For example, the ACH Settlement Delay can be:

  • Decreased, so ACH Direct Debits appear in Settlements faster. This can result in ACH Returns appearing after paying out an ACH Direct Debit.
  • Increased, so sellers have more certainty before paying out ACH Direct Debits. This helps make sure payouts to sellers always include ACH Returns.

To configure or change this delay, reach out to your Finix point of contact or email the Finix Support team.

Validating Bank Accounts

In compliance with Nacha's bank account validation rule, Finix validates every bank account before proceeding with any ACH transactions. Finix validates the bank account the first time it's used, or after any change gets made.

The Transfer#bank_account_validation_check field details the results of this validation check. The following values get returned for Transfer#bank_account_validation_check when creating an ACH Direct Debit:

Value Description
NOT_ATTEMPTED Default value for new bank accounts that haven't been validated yet.
VALID Bank account was found and confirmed to accept ACH Direct Debits.
INVALID Bank account couldn't be found or validated. A Transfer created with a bank account marked INVALID will fail. Please contact the account holder to confirm details or request a different payment method.
INCONCLUSIVE Bank account couldn't be found and validation was INCONCLUSIVE. Bank accounts marked as inconclusive can still be used to create an ACH Transfer.

Failed ACH Direct Debits

An ACH Direct Debit can fail for a variety of reasons, including:

  • Incorrect or Invalid Account Number.
  • Buyer's bank account blocks ACH Direct Debits.
  • Insufficient funds from a buyer's bank account.
  • Buyer files a dispute on a payment they didn't agree to.

When a ACH Direct Debit fails, Finix creates an ACH Return to recover the original payment amount.

ACH Returns are represented by a Transfer with:

  • Transfer#type : REVERSAL
  • Transfer#subtype : SYSTEM .
attention

Most disputes arise within 3-5 business days of the transaction. However, buyers can dispute ACH Direct Debits for any reason up to 60 days after the payment got processed. ACH Direct Debits older than 60 days are guaranteed not to be disputed or get returned.

A full list of reasons why an ACH Direct Debit can result in an ACH Return is available below.

ACH Return Codes Table
Code Description
R01 Insufficient funds in account
R02 Account is closed
R03 No account on file
R04 Invalid account number
R05 Unauthorized debit to consumer account
R06 Returned at request of ODFI
R07 Authorization revoked by customer
R08 Payment stopped
R09 Insufficient collected funds in account being charged
R10 Customer advises not Authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document
R11 Check truncation return
R12 Account sold to another financial institution
R13 Invalid ACH routing number
R14 Representative payee is deceased or cannot continue in that capacity
R15 Beneficiary or account holder other than representative payee deceased
R16 Account funds have been frozen
R17 Item returned because of invalid data; refer to addenda fro information
R18 Improper effective date
R19 Amount error
R20 Account does not allow ACH transactions or limit for transactions has been exceeded
R21 Invalid company identification
R22 Invalid individual ID
R23 Credit entry refused by receiver
R24 Duplicate entry
R25 Addenda record error
R26 Mandatory field error
R27 Trace number error
R28 Routing/transit number check digit error
R29 Corporate customer advised not authorized
R30 RDFI not participant in check truncation program
R31 Permissible return entry
R32 RDFI non-settlement
R33 Return of item
R34 Limited participation ODFI
R35 Return of improper debit entry
R36 Return of improper credit entry
R37 Source document presented for payment
R38 Stop payment on source document
R39 Improper source document
R40 Return of item by government agency
R41 Invalid Transaction Code
R42 Routing/transit number check digit error
R43 Invalid account number
R44 Invalid individual ID
R45 Invalid individual name or company name
R46 Invalid representative payee indicator
R47 Duplicate enrollment
R50 State law affecting RCK acceptance
R51 Item is ineligible, notice not provided, signature not genuine, or original item altered for adjustment entry
R52 Stop payment on item
R53 Item and ACH entry presented for payment
R61 Misrouted return - RDFI for original entry has placed incorrect routing/transit number in RDFI identification field
R67 Duplicate return
R68 Untimely return - return was not sent within the established time frame
R69 Field errors
R70 Permissible return entry not accepted
R71 Misrouted dishonored return -incorrect routing/transit number in RDFI identification field
R72 Untimely return - dishonored return was not sent within the established time frame
R73 Timely original return - RDFI certifies the original return entry was sent within established time frame for original returns
R74 Corrected return - RDFI is correcting a previous return entry that was dishonored because it contained incomplete or incorrect information
R75 Original return not a duplicate
R76 No errors found
R80 Cross-border payment coding error
R81 Non-participant in cross-border program
R82 Invalid foreign RDFI identification
R83 Foreign RDFI unable to settle
R84 Cross-border entry not processed by originating gateway operator

The details of ACH Returns are available to review in the Dashboard.

ACH Return

Creating an ACH Direct Debit

First, create a Payment Instrument to represent your buyer's bank account. Use our Hosted Fields to collect the buyer's bank account and payment details.

info

You must create another Identity for your buyer. Create a Payment Instrument using this new Identity and the buyer's tokenized bank details.

Create a Transfer with the Payment Instrument you created to debit funds directly from the buyer's bank account.

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
-H "Content-Type: application/vnd.json+api" \
-H 'Finix-Version:2022-02-01' \
-uUSsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
	"amount": 6031,
	"currency": "USD",
	"fee": 603,
	"merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
	"source": "PIr1Ru7ewBkEYVVn7SP1u5FW",
	"tags": {
	"order_number": "21DFASJSAKAS"
	}
}'

A successful response returns 201:

  • ACH Direct Debits return Transfers#type DEBIT .
  • ACH Returns create a Transfer with Transfer#type REVERSAL and Transfer#subtype SYSTEM . This Transfer subtracts the amount from the actively accruing Settlement .

Example Response:

Copy
Copied
{
"id" : "TR6Gnj38UyPW3CoukdL9WaR1",
"created_at" : "2022-10-10T05:34:16.13Z",
"updated_at" : "2022-10-10T05:34:16.68Z",
"additional_buyer_charges" : null,
"additional_healthcare_data" : null,
"address_verification" : null,
"amount" : 662154,
"amount_requested" : 662154,
"application" : "APgPDQrLD52TYvqazjHJJchM",
"currency" : "USD",
"destination" : null,
"externally_funded" : "UNKNOWN",
"failure_code" : null,
"failure_message" : null,
"fee" : 0,
"idempotency_id" : null,
"merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
"messages" : [ ],
"raw" : null,
"ready_to_settle_at" : null,
"security_code_verification" : null,
"source" : "PImmCg3Po7oNi7jaZcXhfkEu",
"state" : "PENDING",
"statement_descriptor" : "FNX*DUNDER MIFFLIN",
"subtype" : "API",
"tags" : { },
"trace_id" : "236e1149-9b83-4b79-bfaf-7ff810dcf601",
"type" : "DEBIT",
"_links" : {
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"self" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1"
},
"merchant_identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/payment_instruments"
},
"reversals" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/reversals"
},
"fees" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/fees"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/disputes"
},
"source" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
},
"fee_profile" : {
"href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
}
}
}

Transfer#ready_to_settle_at details when the Transfer will get included in the next Settlement that closes for the Merchant. Like other Transfers, Transfer#ready_to_settle_at gets updated (within the hour) with a timestamp.

You'll also receive a webhook with Webhook#type created and Webhook#entity transfer.

Example ACH Direct Debit Transfer Created
Copy
Copied
{
  "type": "created",
  "entity": "transfer",
  "occurred_at": "2022-09-01T20:36:20.588717",
  "_embedded": {
    "transfers": [
      {
        "idempotency_id": null,
        "amount": 6031,
        "trace_id": "0156ff8f-88c1-4090-8eb6-9f33218b0ec5",
        "failure_code": null,
        "fee": 603,
        "destination": null,
        "raw": null,
        "created_at": "2022-09-01T20:36:08.13Z",
        "source": "PIr1Ru7ewBkEYVVn7SP1u5FW",
        "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
        "failure_message": null,
        "type": "DEBIT",
        "tags": {
          "order_number": "21DFASJSAKAS"
        },
        "statement_descriptor": "FNX*FINIX FLOWERS",
        "additional_buyer_charges": null,
        "ready_to_settle_at": null,
        "application": "APgPDQrLD52TYvqazjHJJchM",
        "updated_at": "2022-09-01T20:36:08.69Z",
        "subtype": "API",
        "externally_funded": "UNKNOWN",
        "messages": [],
        "currency": "USD",
        "id": "TRoom5emPxiP1TRAmHcSjHgz",
        "state": "PENDING"
      }
    ]
  }
}

For more information, see Paying out Transfers.

Refunding an ACH Direct Debit

Refunding an ACH Direct Debit is similar to refunding a Transfer. Use the /reversals endpoint to create a Transfer that moves funds back.

Create a Transfer reversal using the Transfer#id of the original ACH Direct Debit that you want to reverse.

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/reversals \
-H "Content-Type: application/vnd.json+api" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d'
{
"refund_amount" : 6031,
"tags" : {
"test" : "refund"
}
}'

A successful response returns 201 and a new Transfer with type REVERSAL. The original Transfer#id is listed under _links#parent at the end of the URL.

Copy
Copied
{
"id" : "TRnqh2Mt6pnnPumxvenDmVjX",
"created_at" : "2022-10-10T05:36:19.18Z",
"updated_at" : "2022-10-10T05:36:19.27Z",
"additional_buyer_charges" : null,
"additional_healthcare_data" : null,
"address_verification" : null,
"amount" : 6031,
"amount_requested" : 6031,
"application" : "APgPDQrLD52TYvqazjHJJchM",
"currency" : "USD",
"destination" : "PImmCg3Po7oNi7jaZcXhfkEu",
"externally_funded" : "UNKNOWN",
"failure_code" : null,
"failure_message" : null,
"fee" : 0,
"idempotency_id" : null,
"merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
"messages" : [ ],
"raw" : null,
"ready_to_settle_at" : null,
"security_code_verification" : null,
"source" : null,
"state" : "PENDING",
"statement_descriptor" : "FNX*DUNDER MIFFLIN",
"subtype" : "API",
"tags" : {
"test" : "refund"
},
"trace_id" : "5cc0ab4e-3609-4a13-a9c3-b435328360c1",
"type" : "REVERSAL",
"_links" : {
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"self" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRnqh2Mt6pnnPumxvenDmVjX"
},
"parent" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1"
},
"destination" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
},
"merchant_identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRnqh2Mt6pnnPumxvenDmVjX/payment_instruments"
},
"fee_profile" : {
"href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
}
}
}

The Transfer#state gets updated to SUCCEEDED when the refund gets processed. Buyers will see the refund returned as a credit within 5-10 business days, depending on their bank. ACH Direct Debit refunds can’t get canceled once processed.

ACH Refund Returns

Banks manage the ACH networks and often pre-fund transactions before debiting funds.

In some rare cases, an ACH Refund can get returned if the buyer:

  • Account is closed or frozen.
  • Makes a mistake while entering their bank information.
  • Requests to reverse a pre-funded transaction.

When an ACH Refund gets returned, two Transfers get created to credit the funds back to the original bank account. The webhook events you receive, include the subtype:

  • MERCHANT_CREDIT one Transfer to return the funds back to the original bank account.
  • PLATFORM_DEBIT: one Transfer to debit funds that got credited proactively.
Example ACH Merchant Credit
Copy
Copied
{
    "type": "created",
    "entity": "transfer",
    "occurred_at": "2022-09-01T20:49:23.437609",
    "_embedded": {
        "transfers": [{
            "idempotency_id": null,
            "amount": 6031,
            "trace_id": "FNX3Rs9AKNwUVoVu112D40ec5",
            "failure_code": null,
            "fee": 603,
            "destination": null,
            "raw": null,
            "created_at": "2022-09-01T20:36:08.13Z",
            "source": "PIr1Ru7ewBkEYVVn7SP1u5FW",
            "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
            "failure_message": null,
            "type": "REVERSAL",
            "tags": {
                "result_message_0": "ReasonCode: "
                R03 ",
                "result_message_1": "ReasonDescription: No Account Unable to Locate Account"
            },
            "statement_descriptor": "FNX*FINIX FLOWERS",
            "additional_buyer_charges": null,
            "ready_to_settle_at": null,
            "application": "APgPDQrLD52TYvqazjHJJchM",
            "updated_at": "2022-09-01T20:49:23.43",
            "subtype": "MERCHANT_CREDIT_ADJUSTMENT",
            "externally_funded": "UNKNOWN",
            "messages": [],
            "currency": "USD",
            "id": "TRzoL5FmpxIP2TRAmHKSlHgz",
            "state": "SUCCEEDED"
          }
        ]
    }
}
Example ACH Platform Debit
Copy
Copied
{
    "type": "created",
    "entity": "transfer",
    "occurred_at": "2022-09-01T20:49:23.437609",
    "_embedded": {
        "transfers": [{
            "idempotency_id": null,
            "amount": 6031,
            "trace_id": "FNXff8f88c140908eb69f3321",
            "failure_code": null,
            "fee": 603,
            "destination": null,
            "raw": null,
            "created_at": "2022-09-01T20:36:08.13Z",
            "source": "PIr1Ru7ewBkEYVVn7SP1u5FW",
            "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
            "failure_message": null,
            "type": "REVERSAL",
            "statement_descriptor": "FNX*FINIX FLOWERS",
            "additional_buyer_charges": null,
            "ready_to_settle_at": null,
            "application": "APgPDQrLD52TYvqazjHJJchM",
            "updated_at": "2022-09-01T20:49:23.43",
            "subtype": "PLATFORM_DEBIT_ADJUSTMENT",
            "externally_funded": "UNKNOWN",
            "messages": [],
            "currency": "USD",
            "id": "TRoom5emPxiP1TRAmHcSjHgz",
            "state": "SUCCEEDED"
          }
        ]
    }
}