Overview

The CardPointe Gateway is integrated with ACH Payment Services from Fiserv (also known as Fiserv ACH).

This guide provides information for using the CardPointe Gateway API to accept ACH payments from your application.

Fiserv ACH currently supports the US Dollar (USD) currency only.

What's New?

Date Updated: 2/6/2024

With this update, rejected transactions that are not funded will no longer generate a new ACH Reject record. 

Instead, the original transaction will be updated to "status": "Rejected"  and include an ACH return code (for example, "achreturncode": "R03").

The following example illustrates an ACH Reject record as returned by the CardPointe Gateway API's funding endpoint.

See our Fiserv ACH Reject Update for more information, including details on reporting in the  CardPointe Web Application.

Understanding ACH Rules and Regulations

Before you begin, you should review and understand the rules and regulations concerning ACH payments.

The National Automated Clearing House Association (NACHA) governs the industry-standard requirements that all merchants and service providers must abide by. The NACHA Operating Rules and Guidelines is a formal standard that outlines specific rules for accepting and processing ACH payments and data security guidelines to protect sensitive account information. As a merchant, it is your obligation to review and abide by these guidelines. To obtain a copy of the NACHA Operating Rules and Guidelines, see https://www.nacha.org/rulesyourway.

Additionally, the ACH Payment Services Operational Guidelines Overview provides helpful information for understanding and complying with the NACHA rules and guidelines.

Click below to download a copy

The ACH Payment Services Operational Guidelines Overview is a supplemental companion to the NACHA Operating Rules and Guidelines. If you have any questions or concerns regarding your compliance, refer to the NACHA Operating Rules and Guidelines.

Processing ACH Transactions

To process ACH payments on the CardPointe Gateway, you use the CardPointe Gateway API to make authorization requests just like you would for credit card transactions. The authorization request supports all of the required fields for processing ACH checking or savings account transactions, including sales and refunds. 

Unlike credit card payments, when a customer authorizes an ACH payment, the funds are withdrawn directly from his or her bank account. This process can take several days, so you should include a monitoring process in your integration to verify the status of the transaction.

To accept ACH payments, you must capture and handle the customer's bank account and routing number. While you can capture this information and pass it directly to the CardPointe Gateway in an authorization request, it is a best practice to instead capture this information and tokenize it using a CardSecure-integrated web form.

Account Validation

For WEB debit transactions (consumer payments originated on the internet or a mobile device or automatically debited), the account validation service checks the account and routing numbers against a list of known-good accounts to verify that the account can be used to complete the transaction.

If the account is successfully validated, the transaction is approved and settled. If the account is closed, unknown, or has been previously flagged, the transaction is declined in real time and must be reattempted with an alternate payment method. In the event of a decline, the CardPointe Gateway returns a declined authorization response with one of the following reasons:

  • "Declined: bank account failed validation"
  • "Declined: bank account previously failed validation"

See the Fiserv ACH Account Validation support article for detailed information on the account validation service and requirements.

ACH Reversals

An ACH reversal can be performed to correct an erroneous transaction (for example, the wrong bank account was debited). 

Similarly to a refund, a reversal credits the funds back to the debited account; however, a reversal is only acceptable in the event of an error by the initiator of the original transaction (merchant) and can only be performed by the initiator to correct the error. NACHA enforces strict rules and requirements for processing reversals, including:

  • The amount (amount) of the reversal must exactly match the amount of the original transaction
  • The SEC code (achEntryCode) in the reversal request must match the value used in the original transaction.
  • The ACH Description (achDescription) must be Reversal to identify the transaction as a reversal.

See the following article for important updates to the NACHA rules and enforcement for ACH reversals: 

https://www.nacha.org/rules/reversals-and-enforcement

Using a Web Form to Gather and Tokenize ACH Payment Data

To ensure the security of your customers' data, it is recommended that you use a customer-facing web form, integrated with CardSecure, to capture and tokenize bank account and routing information.

When using a web form to capture and tokenize customer bank account information, include separate fields for the routing number and account number. Send these fields in a CardSecure tokenization request in the format
"account" : "<routing number>/<account number>"

For example:

"account" : "123456789/1234123412341234"

CardSecure returns a token representing the ACH account information, which you can then use to make an authorization request to the CardPointe Gateway.

Making an ACH Authorization Request

The following table describes the authorization request fields that you must include when processing an ACH payment:

  • Fields in bold are required.
  • Underlined fields can be saved to a profile, if "profile" : "y" in the request. See the Profile endpoint description for more information.

    Note: If the authorization request fails or is declined, the profile is not created.

  • Most fields in the authorization request correspond to columns on the CardPointe application's Transactions table. See the CardPointe Web App User's Guide for more information.
FieldMax LengthTypeComments
merchid16NCardPointe merchant ID, required for all requests.
amount14N

Amount with decimal or without decimal in currency minor units. 

Notes: 

  • Only USD is currently supported.
  • Negative amounts (forced credits) are currently not supported.
accttype4AThe ACH account type. One of the following values:
  • ECHK - checking account
  • ESAV - savings account
account19NCan be:
  • CardSecure Token - A token, including the bank account and checking numbers, retrieved from the Bolt API, CardSecure API, or the Hosted iFrame Tokenizer 
  • Bank Account Number - The clear checking or savings account number. When using this field, the bankaba field is also required to include the routing number.
Note: To use a stored profile, omit the account property and supply the profile ID in the profile field instead. See the Profile description for more information.
achDescription10AN

An optional description for the transaction, truncated to a maximum of 10 characters.

For ACH reversals, you must specify this field as Reversal, as required by NACHA guidelines. See ACH Reversals for more information.

achEntryCode3ANDetermines the type of ACH transaction. If omitted, this value is determined by the CardPointe Gateway.

One of the following values:

  • CCD - B2B payment with a signed company agreement on file.
  • PPD - Recurring payment, with a signed customer agreement on file.
  • TEL - Phone payment (call center), with the customer's recorded verbal consent on file.
  • WEB - Web or mobile payment, with a customer's web authorization or agreement on file.

Note: For refunds, this field is converted to either CCD or PPD depending on the merchant account configuration.

bankaba9NBank routing (ABA) number. Required for ACH authorizations when a bank account number is provided in the account field. bankaba is not required if a CardSecure token (generated from the account/bankaba pair) is provided in the account field.
name30ANAccount holder's name.
receipt1AOptional, to return receipt data fields in the authorization response. 

Specify Y to return additional merchant and authorization data to print on a receipt. 

Defaults to if not provided.
profile24ANOptional, to create an account profile or to use an existing profile.

To create a profile using the account holder data provided in the request, specify Y.

To use an existing profile for this authorization, omit the account parameter and instead use the profile parameter to supply the 20-digit profile id and 1-3-digit account id string in the format <profile>/<account>. 

See Profiles for more information.
tokenize1AOptional, specify N or omit to return an account token in the account field in the response. 

If tokenize is Y, the masked account number is returned in the response.
signature6144ANJSON-escaped, Base64-encoded, Gzipped, BMP of signature data. If the authorization is using a token with associated signature data, then the signature from the token is used.
address30ANAccount holder's street address, required for AVS verification.
address230ANSecond address line (for example, apartment or suite number) if applicable.
city30ANAccount holder's city.
postal9ANThe account holder's postal code.

If country is "US", must be 5 or 9 digits. Otherwise any alphanumeric string is accepted. Defaults to "55555" if not included in the request or stored profile.

Note: It is strongly recommended that your application prompts for postal code for e-commerce or telephone transactions to prevent fraud and downgrades, and to avoid declines on the CardPointe Gateway if the AVS verification option is enabled for your merchant account.
region20ANAccount holder's region, US State, Mexican State, Canadian Province
country2ANAccount holder's country (2-character country code), defaults to "US". 

Required for all non-US addresses
phone15ANAccount holder's phone number.
email128ANAccount holder's email address.
orderid19ANSource system order number.

Note: If you include an order ID it must meet the following requirements:
  • The order ID must be a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.
  • The order ID must not include any portion of a payment account number, and no portion of the order ID should be mistaken for a PAN. If the order ID passes the Luhn check performed by the CardPointe Gateway, the value will be masked in the database, and attempts to use the order ID in an inquire, void, or refund request will fail.
authcode6ANAuthorization code from original authorization (VoiceAuth). 

For Voice/Capture-Only, the request must include a valid authcode.
taxexempt1AIf taxexempt is set to "N" for the transaction and a tax is not passed, the default configuration data is used. 

If taxexempt is set to "Y" the taxamnt is $0.00. 
taxamnt12NTax amount for the order, either decimal or in currency minor units (for example, USD Pennies or MXN Centavos).
If taxexempt is "Y" taxamnt must be zero or omitted. If taxexempt is "N", taxamnt must be a positive, non-zero value.

This table does not include the complete list of authorization request parameters. See the CardPointe Gateway API's authorization service description for more detailed information on the authorization request and response parameters.

Verifying ACH Transactions

ACH transactions typically take several business days to process and settle, therefore, it is a best practice to periodically check the status of the transaction to ensure that it is successfully processed and that you are credited for the authorized amount.

You can use the CardSecure Gateway API to programmatically verify the transaction status using the funding and inquire service endpoints.

Using the Funding Endpoint

To use the funding endpoint to retrieve your ACH funding data, you must use your Fiserv ACH MID and API credentials associated with this MID.

The funding endpoint provides additional useful information for ACH transactions. Specifically, you can use the funding endpoint to retrieve an ACH return code (achreturncode), which provides additional information for rejected ACH transactions.

To use the funding endpoint, you make a request using the merchant ID and the date of the funding event that included the transaction. The funding endpoint returns an array of transaction details for that date.

Use the retref for the ACH transaction to locate it in the txns node of the response data. For ACH transactions, the response includes an achreturncode field that includes a specific code that explains the reason for the rejection.

The following table describes the possible ACH return code values.

ACH Return Codes

The following codes are returned when an ACH transaction is rejected. 

CodeDescription

R01

Insufficient funds

R02

Bank account closed

R03

No bank account/unable to locate account

R04

Invalid bank account number

R06

Returned per ODFI request

R07

Authorization revoked by customer

R08

Payment stopped

R09

Uncollected funds

R10

Customer advises not authorized

R11

Check truncation entry return

R12

Branch sold to another RDFI

R13

RDFI not qualified to participate

R14

Representative payee deceased or unable to continue in that capacity

R15

Beneficiary or bank account holder

R16

Bank account frozen

R17

File record edit criteria

R18

Improper effective entry date

R19

Amount field error

R20

Non-payment bank account

R21

Invalid company ID number

R22

Invalid individual ID number

R23

Credit entry refused by receiver

R24

Duplicate entry

R25

Addenda error

R26

Mandatory field error

R27

Trace number error

R28

Transit routing number check digit error

R29

Corporate customer advises not authorized

R30

RDFI not participant in check truncation program

R31

Permissible return entry (CCD and CTX only)

R32

RDFI non-settlement

R33

Return of XCK entry

R34

Limited participation RDFI

R35

Return of improper debit entry

R36Return of Improper Credit Entry
R39Improper Source Document
R40Non-Participant in ENR program
R41Invalid transaction code
R42Transit/Routing check digit error
R43Invalid DFI account number
R44Invalid individual ID number
R45Invalid individual name
R46Invalid representative payee indicator
R47Duplicate enrollment
R50State Law affecting RCK Acceptance
R51Item is Ineligible, Notice Not Provided, Signature Not Genuine, or Item Altered (adjustment entries)
R52Stop Payment on Item (adjustment entries)
R61Misrouted return
R62Incorrect trace number
R63Incorrect dollar amount
R64Incorrect individual identification
R65Incorrect transaction code
R66Incorrect company identification
R67Duplicate return
R68Untimely return
R69Multiple errors
R70Permissible return entry not accepted
R71Misrouted dishonored return
R72Untimely dishonored return
R73Timely original return
R74Corrected return
R80Cross Border Payment Coding Error
R81Non-Participant in Cross-Border Program
R82Invalid Foreign Receiving DFI identification
R83Foreign Receiving DFI Unable to Settle

Using the Inquire Endpoint

The inquire endpoint provides information on completed authorizations.

You can use the inquire endpoint if you have the retrieval reference number (retref) from the authorization response. If you don't have the retref, but you included a unique order ID in the authorization request, then you can use the inquireByOrderId endpoint instead.

The inquire response includes a settlement status (setlstat) field that displays the settlement status of the transaction. Note that the settlement status initially displays "Queued for Capture" for ACH transactions, and the value is updated once the batch is transmitted. If "setlstat" : "rejected" you can use the funding endpoint to gather more detailed information.