All pages
Powered by GitBook
2 of 9

ACH Transaction Integration

Clearent supports ACH transactions through the ACH transactions APIs.

Clearent’s ACH Transaction and Check Processing solution enables you to accept various types of payment transactions from your customers, including:

  • Credit

  • Debit

  • Validate (Validate ACH Information)

Clearent’s ACH Transaction processing utilizes the following third-party providers for handling ACH transactions and reporting:

  • Paya

  • DCS

Note: Clearent does not settle and fund ACH transactions in the system.

The following articles provide the information for working with Clearent’s ACH Transaction integration:

Integration Methods for the ACH Transactions

The following table provides the information of transaction types when you use Clearent’s different integration methods to process the ACH transactions:

Integration Method
Transaction Type

API

When you integrate with Clearent’s ACH Transaction API solution, you can accept the following types of transaction:

  • Credit

  • Debit

  • Validate (Validate ACH Information)

Virtual Terminal

When you integrate with Clearent’s Virtual Terminal solution, you can accept the following types of transaction:

  • Credit

  • Debit

  • Validate (Validate ACH Information)

Hosted Payment Page

When you integrate with Clearent’s Hosted Payments solution, you can accept the following types of transaction:

  • Debit

  • Validate (Validate ACH Information)

Paylink

When you integrate with Clearent’s Hosted Payments solution, you can accept the following types of transaction:

  • Debit

  • Validate (Validate ACH Information)

JavaScript SDK

When you integrate with Clearent’s JavaScript SDK solution, you can accept the following types of transaction:

  • Credit

  • Debit

  • Validate (Validate ACH Information)

Mobile EMV SDK

Currently, Clearent’s Mobile EMV SDK does not support ACH transactions.

Processing an ACH Transaction

Clearent allows you to process an ACH transaction, submitting the transaction request and validating the payer's bank account information and transaction details. Also. you can monitor the transaction status to ensure successful completion or to identify any issues that may arise.

To process an ACH transaction using Clearent’s ACH Transaction API integration method:

1

Use the POST method for /rest/v2/ach/transactions endpoint to start the ACH transaction process. Refer to the following sample code for the request:

{ 
  "check-field": "invoice", 
  "client-ip": "111.22.22.333",
  "dob-year": "dob-year",
  "email-receipt": "true",
  "software-type-version": "1.0",
  "type": "Debit",
  "validate-account": "true",
  "amount": "string",
  "routing-number": "string",
  "account-number": "string",
  "account-type": "Checking",
  "standard-entry-class-code": "PPD",
  "check-number": "string",
  "create-token": "false",
  "create-description": "false",
  "individual-name": "string"
}
2

Calling the ach-transaction validates an authentication token.

Note: If an authentication token is expired or the signature does not match, the ach-transaction returns a 401-error code.

3

Calling the ach-transaction validates the request.

Note: If the request has an issue related to letters in the routing number, the ach-transaction returns a 500-error code.
4

Calling the ach-transaction looks up real ACH data from the ach-vault if the ACH Account Number is an authentication token.

5

Calling the ach-transaction looks up the provider for the merchant if the provider is in the authentication token or associated with the provided API key.

6

Calling the ach-transaction routes to the appropriate provider for merchant.

Note: The ach-transaction returns the success and failure response.

7

Listening the ach-transaction-consumer stores the generated transaction ID and the relevant information in the database for future ACH transactions.

8

Listening the ach-status-consumer stores the generated transaction ID and the status of the ACH transactions in the database for ACH transactions that are in the queue.

Getting an ACH Transaction

Clearent allows you to retrieve the status of an ACH transaction accessing the transaction's unique identifier. The unique identifier provides real-time updates on the transaction's progress and address any issues that may arise during the transaction process.

To get an ACH transaction:

1

Use the GET method for /rest/v2/ach/transactions endpoint.

Note: You may receive 20 paginated results at a time when the authentication token in the GET request does not include parameters.

2

The ach-transaction forwards GET request to the ach-wharehouse.

3

The ach-wharehouse validates a token.

Note: The ach-wharehouse returns a 401-error code when a token fails to authenticate.

4

The ach-warehouse searches the read-only replicated database of tables using ach-consumer and ach-status-consumer to find transactions that match the search criteria. The ach-warehouse returns a 200-success code with the following response sample code, including a list of ACH transactions.

{ 
 "ach-transaction": 
  [ 
   { 
    "check-field": "invoice", 
    "client-ip": "111.22.22.333", 
    "dob-year": "dob-year", 
    "email-receipt": "true", 
    "software-type-version": "1.0", 
    "type": "Debit", 
    "validate-account": "true", 
    "amount": "string", 
    "routing-number": "string", 
    "account-number": "string", 
    "account-type": "Checking", 
    "standard-entry-class-code": "PPD", 
    "check-number": "string", 
    "create-token": "false", 
    "create-description": "false", 
    "individual-name": "string", 
    "token-id": "1188888888888888", 
    "id": "string", 
    "status": "Pending", 
    "billing": 
     { 
      "city": "City", 
      "company": "Company", 
      "country": "Country", 
      "first-name": "John", 
      "last-name": "Doe", 
      "phone": "Phone", 
      "state": "State", 
      "street": "Street", 
      "street2": "Street2", 
      "zip": "Zip" 
     }, 
      "shipping": 
       { 
        "city": "City", 
        "company": "Company", 
        "country": "Country", 
        "first-name": "John", 
        "last-name": "Doe", 
        "phone": "Phone", 
        "state": "State", 
        "street": "Street", 
        "street2": "Street2", 
        "zip": "Zip" 
       }, 
        "invoice": "string", 
        "purchase-order": "string", 
        "customer-id": "string", 
        "order-id": "string", 
        "email-address": "string", 
        "description": "string", 
        "comments": "string", 
        "billing-is-shipping": "true", 
        "status-change-date": "string", 
        "display-message": "string", 
        "provider-transaction-id": "string", 
        "trace-number": "string", 
        "settled-date": "string", 
        "returned-date": "string", 
        "returned-code": "string", 
        "returned-message": "string", 
        "ach-token": 
         { 
          "account-number": "1111", 
          "account-type": "Checking", 
          "created": "1100000000000000", 
          "customer-key": "customer123", 
          "default": true, "individual-name": 
          "John Doe", "last-used": "1100000000000000", 
          "merchant-id": "000008888", 
          "routing-number": "081009813", 
          "times-used": 14, 
          "token-description": "Travel checking account", 
          "token-id": "1100000000000000", 
          "updated": "1100000000000000" 
         }, 
          "merchant-id": "string", 
          "terminal-id": "string", 
          "software-type": "MySoftware_Version1.3", 
          "paya-authorization": "string" 
   } 
  ] 
}

Note: The ach-warehouse returns a 204-error code when it does not match the search criteria.

Creating an ACH Transaction Token

Clearent allows you to initiate a request through the ACH Transaction API to create a token. This token includes essential details such as the payer's bank account information, the transaction amount, and any relevant metadata. Clearent generates a unique token that securely represents the data, allowing for the processing of an ACH transaction without storing sensitive information. Clearent processes ACH transactions in adherence to security and compliance with industry standards.

To create an ACH transaction token using Clearent’s Hosted Payment Page, Paylink, Virtual Terminal, and JavaScript SDK integrations:

1

Use the POST method for /rest/v2/ach/token endpoint. Refer to the following sample code for the request:

{ 
 "account-number": "123456789", 
 "account-type": "Checking", 
 "individual-name": "John Doe", 
 "routing-number": "081009813", 
 "software-type": "MySoftware", 
 "software-type-version": "v1.0", 
 "token-description": "Business checking account" 
}
2

The ach-vault validates a request token.

Note: The ach-vault returns a 401-error code when a token fails to authenticate.

3

The ach-vault validates a payload.

Note: The ach-vault returns a 400-error code when a payload fails to authenticate.

4

The ach-vault calls to the HSM to create an ACH transaction token after successful validation.

Note: An ACH transaction token has an ach_ prefix and a 12 to 19-digit number starting with 11.

5

The ach-vault returns a 200-status code with the response, including an ACH transaction token. Refer to the following sample code for the response:

{ 
 "ach-token": 
  { 
   "account-number": "1111", 
   "account-type": "Checking", 
   "created": "1100000000000000", 
   "individual-name": "John Doe", 
   "last-used": "1100000000000000", 
   "merchant-id": "000008888", 
   "routing-number": "081009813", 
   "times-used": 14, 
   "token-description": "Travel checking account", 
   "token-id": "1100000000000000", 
   "updated": "1100000000000000" 
  }, 
 "payloadType": "string" 
}
6

The ach-vault stores the plaintext payload.

Note: The ach-vault returns a 500-error code when it fails to create an ACH transaction token.

Handling Returns for the ACH Transactions

Clearent’s third-party providers handle returns for ACH transactions in unique ways. Clearent’s specific Corn Services run periodically at scheduled times throughout the day to look for returns using a .csv file. Third-party providers handle returns when Clearent calls the ach-status-paya to look up specific status requests, such as all pending ACH transactions. When the new status of the transactions is found, Clearent uses the ach-status-consumer listener to store the message on the queue with the new status and sends status messages to your customer.

The following table provides information about handlers for returns of ACH transactions:

Handler
Description

ach-status-updater

This handler finds ACH transaction numbers that are in final status and stores a new status on the queue through DCS if applicable.

ach-status-paya

This handler finds ACH transaction numbers that are in final status and stores a new status on the queue through Paya if applicable.

ach-returns-dcs

This handler retrieves a return .csv file from DCS and matches transactions. It then stores the new status on the queue through DCS.

Checking an ACH Transaction Status

Clearent provides an ACH transaction status after every two hours, including PENDING or SETTLING statuses.

For example, when you receive the response for an ACH transaction, including a transaction ID d4a07b56-aa70-4f51-bac8-88bffb6b7de9 and other transaction details.

{
    "code": "200",
    "status": "success",
    "exchange-id": "ID-clearent-ach-transaction-2-7b71513a-535e-4918-89b9-8ea72ee636c3",
    "links": [
        {
            "rel": "self",
            "href": "https://gateway-sb.clearent.net/rest/v2/ach/transactions/d4a07b56-aa70-4f51-bac8-88bffb6b7de9",
            "id": "d4a07b56-aa70-4f51-bac8-88bffb6b7de9"
        },
        {
            "rel": "token",
            "href": "https://gateway-sb.clearent.net/rest/v2/ach/tokens/ach_1100000000041201",
            "id": "ach_1100000000041201"
        }
    ],
    "payload": {
        "ach-transaction": {
            "type": "Debit",
            "amount": "19.99",
            "status": "PENDING",
            "routing-number": "490000018",
            "account-number": "XXXXXX7890",
            "account-type": "CHECKING",
            "standard-entry-class-code": "WEB",
            "check-number": "1001",
            "individual-name": "Buffy Summers",
            "id": "d4a07b56-aa70-4f51-bac8-88bffb6b7de9",
            "invoice": "a04d9ff5-830c-4d43-8622-83f8681c3656",
            "purchase-order": "1731016624",
            "customer-id": "customer-id_c4145539-1cbc-4bcb-bd75-33ad6527d0d3",
            "order-id": "order-id-cd669947-e3ac-459d-85a0-42ffad34f63f",
            "email-address": "bob@bob.com",
            "description": "a big boat",
            "comments": "these are comments",
            "display-message": "Transaction submitted",
            "provider-transaction-id": "d4a07b56-aa70-4f51-bac8-88bffb6b7de9",
            "ach-token": {
                "token-id": "ach_1100000000041201",
                "times-used": 10,
                "last-used": "2024-11-07T21:57:04.355175",
                "merchant-id": "000000502914",
                "routing-number": "490000018",
                "account-number": "7890",
                "account-type": "checking",
                "individual-name": "James Dude",
                "token-description": "cus_JdW0ZauDFfHkfi",
                "created": "2022-05-17T21:17:44.501638",
                "updated": "2024-11-07T21:57:04.357962"
            },
            "merchant-id": "000000502914",
            "terminal-id": "22122221",
            "software-type": "Postman",
            "paya-authorization": "272-172"
        },
        "payloadType": "ach-transaction"
    }
}

To check the status for this ACH transaction:

  1. Use the GET method for the https://gateway.clearent.net/rest/v2/ach/transactions?id=d4a07b56-aa70-4f51-bac8-88bffb6b7de9 endpoint, passing the transaction ID as a URL parameter.

You will receive the response for a transaction ID d4a07b56-aa70-4f51-bac8-88bffb6b7de9 with the current transaction status.

{
    "code": "200",
    "status": "success",
    "exchange-id": "ID-clearent-ach-transaction-2-f53f6340-983d-45c7-a701-01d95856d1e8",
    "links": [
        {
            "rel": "self",
            "href": "https://gateway-sb.clearent.net/rest/v2/ach/transactions?id=d4a07b56-aa70-4f51-bac8-88bffb6b7de9"
        }
    ],
    "payload": {
        "ach-transactions": {
            "ach-transaction": [
                {
                    "type": "Debit",
                    "amount": "19.99",
                    "status": "SETTLED",
                    "routing-number": "490000018",
                    "account-number": "7890",
                    "account-type": "CHECKING",
                    "standard-entry-class-code": "WEB",
                    "check-number": "1001",
                    "individual-name": "Buffy Summers",
                    "id": "d4a07b56-aa70-4f51-bac8-88bffb6b7de9",
                    "billing": {},
                    "shipping": {},
                    "invoice": "a04d9ff5-830c-4d43-8622-83f8681c3656",
                    "purchase-order": "1731016624",
                    "customer-id": "customer-id_c4145539-1cbc-4bcb-bd75-33ad6527d0d3",
                    "order-id": "order-id-cd669947-e3ac-459d-85a0-42ffad34f63f",
                    "email-address": "bob@bob.com",
                    "description": "a big boat",
                    "comments": "these are comments",
                    "billing-is-shipping": "false",
                    "status-change-date": "2024-11-07T21:57:04Z",
                    "provider-transaction-id": "d4a07b56-aa70-4f51-bac8-88bffb6b7de9",
                    "ach-token": {
                        "token-id": "ach_1100000000041201"
                    },
                    "merchant-id": "000000502914",
                    "software-type": "Postman",
                    "paya-authorization": "272-172"
                }
            ]
        },
        "payloadType": "ach-transactions"
    },
    "page": {
        "number": 1,
        "size": 25,
        "sort": {
            "field": {
                "createDateTimeUtc": "DESC"
            }
        },
        "first": true,
        "last": true,
        "total-pages": 1,
        "number-of-elements": 1,
        "total-elements": 1
    }
}

Similarly, you can search for various ACH transactions using the following ways:

  • Search by status (including paging options)

https://gateway.clearent.net/rest/v2/ach/transactions?status=settled&pagesize=50&page=10

  • Search by order ID (if provided with original transaction)

https://gateway.clearent.net/rest/v2/ach/transactions?orderid=order-id-cd669947-e3ac-459d-85a0-42ffad34f63f

  • Search by customer ID (if provided with original transaction)

https://gateway.clearent.net/rest/v2/ach/transactions?customer-id=customer-id_c4145539-1cbc-4bcb-bd75-33ad6527d0d3

  • Search by invoice (if provided with original transaction)

https://gateway.clearent.net/rest/v2/ach/transactions?invoice=a04d9ff5-830c-4d43-8622-83f8681c3656

  • Search with no parameters.

https://gateway.clearent.net/rest/v2/ach/transactions

ACH Transaction Statuses

The following table provides the information of the ACH transaction statuses:

Status
Description

PENDING

This status indicates that an ACH transaction is pending.

SETTLED

This status indicates that an ACH transaction is settled.

SETTLING

This status indicates that an ACH transaction is settling.

RETURNED

This status indicates that an ACH transaction is returned.

VOID

This status indicates that an ACH transaction is void.

CHARGEBACK

This status indicates that an ACH transaction is chargeback.

MERCHANT_RETURNED

This status indicates that an ACH transaction is returned. This status also indicates you to check Merchant Setup.

NO CREDIT

This status indicates that an ACH transaction does not have credit.

TO RESERVE

This status indicates that an ACH transaction is to reserve.

UNPROCESSED

This status indicates that an ACH transaction is unprocessed.

ERROR

This status indicates that an ACH transaction has an error.

Note: Clearent sets the status as PENDING for an ACH transaction initially. An ACH transaction process transitions from SETTLING to SETTLED status.

ACH Transaction Return Codes

Clearent handles returns for an ACH transaction that are returned by the receiving bank due to various reasons such as insufficient funds, closed accounts, or incorrect account information. Clearent identifies returns and notifies you to take appropriate corrective actions. Clearent allows you to resubmit the transaction or alternative payment processing method.

The following table provides the information of the return codes for an ACH transaction:

Return Code
Message

R02

Account closed A previously open account is now closed

R03

No account or unable to locate account The account number does not correspond to the individual identified in the entry or a valid account.

R04

Invalid account number The account number fails the check digit validation or may contain an incorrect number of digits

R05

Unauthorized debit to consumer account A business debit entry was transmitted to a members consumer account, and the member had not authorized the entry

R06

Returned per ODFI’s request The ODFI has requested that the RDFI return the entry

R07

Authorization revoked by customer Member who previously authorized an entry has revoked authorization with the Originator

R08

Payment stopped or stop payment on item Member had previously requested a stop payment of a single or recurring entry

R09

Uncollected funds Available balance is sufficient, but collected balance is not sufficient to cover the entry

R10

Customer advises not authorized Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document

R11

Check truncation entry return To be used when returning a check truncation entry

R12

Branch sold to another DFI RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution

R13

Invalid ACH routing number Financial institution does not receive commercial ACH entries

R14

Representment payee deceased or unable to continue in that capacity Representative payee is deceased or unable to continue in that capacity, beneficiary is not deceased

R15

Beneficiary of account holder deceased Beneficiary or Account Holder Deceased

R16

Account frozen Access to account is restricted due to specific action taken by the RDFI or by legal action

R17

File record edit criteria Fields rejected by RDFI processing (identified in return addenda)

R18

Improper effective entry date Entries have been presented prior to the first available processing window for the effective date.

R19

Amount field error Improper formatting of the amount field

R20

Nontransaction account Policies or regulations (such as Regulation D) prohibit or limit activity to the account indicated

R21

Invalid company identification The company ID information not valid (normally CIE entries)

R22

Invalid individual ID number Individual id used by receiver is incorrect (CIE entries)

R23

Credit entry refused by receiver Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account

R24

Duplicate entry RDFI has received a duplicate entry

R25

Addenda error Improper formatting of the addenda record information

R26

Mandatory field error Improper information in one of the mandatory fields

R27

Trace number error Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record

R28

Routing number or check digit error Check digit for the transit routing number is incorrect

R29

Corporate customer advises not authorized RDFI has been notified by business account holder that a specific transaction is unauthorized

R30

RDFI not participant in check truncation program Financial institution not participating in automated check safekeeping application

R31

Permissible return entry RDFI has been notified by business account holder that a specific transaction is unauthorized

R32

RDFI nonsettlement RDFI is not able to settle the entry

R33

Return of XCK entry RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry

R34

Limited participation DFI RDFI participation has been limited by a federal or state supervisor

R35

Return of improper debit entry ACH debit not permitted for use with the CIE standard entry class code (except for reversals)

R36

Return of improper credit entry

R37

Source Document Presented for Payment Check used for an ARC, BOC or POP entry has also been presented for payment

R38

Stop payment on source document Stop payment has been placed on a check used for an ARC entry

R40

Return of ENR entry by federal government agency (ENR only)

R41

Invalid transaction code (ENR only)

R42

Routing number or check digit error (ENR only)

R43

Invalid DFI account number (ENR only)

R44

Invalid individual ID number (ENR only)

R45

Invalid individual name/company name (ENR only)

R46

Invalid representative payee indicator (ENR only)

R47

Duplicate enrollment

R50

State law affecting RCK acceptance

R51

Item is ineligible, notice not provided, signature not genuine

R52

Stop payment on item

R61

Misrouted return Return entry was sent by RDFI to an incorrect ODFI routing/transit number

R62

Incorrect trace number

R63

Incorrect dollar amount

R64

Incorrect individual identification

R65

Incorrect transaction code

R66

Incorrect company identification

R67

Duplicate return ODFI has received more than one return entry for the same original entry

R68

Untimely return Return entry did not meet the return deadline

R69

Multiple errors

R70

Permissible return entry not accepted

R71

Misrouted dishonored return

R72

Untimely dishonored return

R73

Timely original return

R74

Corrected return

R80

Cross-border payment coding error

R81

Nonparticipant in cross-border program

R82

Invalid foreign receiving DFI identification