Accept ACH credit and direct debit payments by:
The following integration methods support accepting ACH payments:
Quest API – Supports ACH credit and direct debit payments.
Hosted Payments – Supports ACH direct debit payments.
Paylink – Supports ACH direct debit payments.
JavaScript SDK – Supports ACH credit and direct debit payments.
The following articles explain how to process ACH transactions:
To submit the payment request:
Use the POST method with the /rest/v2/ach/transactions endpoint and the following sample 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",
}The following table describes the request body parameters:
check-field
String
Optional
Specifies the field for check identification. For example, invoice.
client-ip
Integer
Optional
The IP address of the client initiating the request. For example, 111.22.22.333
dob-year
Integer
Optional
The customer's year of birth.
email-receipt
Boolean
Optional
Indicates whether to send an email receipt.
software-type-version
Integer
Optional
The version of the specification used to initiate the transaction.
type
String
Optional
The type of ACH transaction.
validate-account
Boolean
Optional
Indicates whether to validate the bank account.
amount
String
Optional
The transaction amount.
routing-number
String
Optional
The bank routing number.
account-number
String
Optional
The bank account number.
account-type
String
Optional
The type of bank account.
standard-entry-class-code
String
Optional
The ACH standard entry class code.
check-number
String
Optional
The check number associated with the transaction.
create-token
Boolean
Optional
Indicates whether to create a reusable token.
create-description
Boolean
Optional
Indicates whether to create a transaction description.
individual-name
String
Optional
The name of the individual associated with the transaction.
The ach-transaction returns the following status and error codes:
401
If the authentication token has expired or the signature does not match the token.
500
If the request is invalid—for example, if the routing number contains letters.
Creating an ACH token validates the account number or routing number for transaction.
To create an ACH token:
Use the POST method with the /rest/v2/ach/tokens endpoint and the following sample 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"
}The following table describes the request body parameters:
account-number
String
Optional
The bank account number used for the ACH transaction.
account-type
String
Optional
The type of bank account. For example, Checking or Savings.
individual-name
String
Optional
The name of the individual associated with the bank account.
routing-number
String
Optional
The bank routing number used to identify the financial institution.
software-type
String
Optional
The name of the software initiating the request.
software-type-version
String
Optional
The version of the software used to initiate the request.
token-description
String
Optional
A description of the token being created, such as the account purpose.
Set create-token to true in the transaction payload to generate and store a token for future use, for example:
{
type:credit
amount:2.00
account-number: 323434333
routing-number: 333333333
create-token: true
}The ach-token returns the following 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"
}The following table describes the response body fields:
account-number
String
The bank account number.
account-type
String
The type of bank account.
created
String
The timestamp when the token was created.
individual-name
String
The name of the individual associated with the token.
last-used
String
The timestamp when the token was last used.
merchant-id
String
The unique identifier of the merchant associated with the token.
routing-number
String
The bank routing number associated with the account.
times-used
String
The number of times the token has been used.
token-description
String
A description of the token, such as the account’s purpose.
token-id
String
The unique identifier of the token.
updated
String
The timestamp when the token was last updated.
payloadType
String
The type of payload returned in the response.
The ach-token returns the following status and error codes:
401
If the ACH token has expired or the signature does not match the token.
500
If the request is invalid—for example, if the routing number contains letters.
200
An ACH token created successfully.
To get an ACH transaction:
Use the GET method with the /rest/v2/ach/transactions endpoint.
Enter the ID returned in the ACH payment response in the search criteria to find the transaction.
The ach-transaction returns the following response:
{
"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"
}
]
}The following table describes the fields in the response body:
ach-transaction
Array of strings
Contains the details of the ACH transaction.
check-field
String
Specifies the field used for check identification, such as an invoice number.
client-ip
String
The IP address of the client initiating the request.
dob-year
String
The customers year of birth.
email-receipt
String
Indicates whether to send an email receipt.
software-type-version
String
The version of the software used to initiate the transaction.
type
String
The transaction type. For example, Debit.
validate-account
String
Indicates whether to validate the bank account.
amount
String
The transaction amount.
routing-number
String
The bank routing number.
account-number
String
The bank account number.
account-type
String
The type of bank account. For example, Checking or Savings.
standard-entry-class-code
String
The ACH standard entry class code. For example, PPD.
check-number
String
The check number associated with the transaction.
create-token
String
Indicates whether to create a reusable token.
create-description
String
Indicates whether to create a transaction description.
individual-name
String
The name of the individual associated with the transaction.
token-id
String
The unique identifier of the token.
id
String
The unique identifier of the transaction.
status
String
The current status of the transaction. For example, Pending.
billing
Object
Contains billing address details.
billing.city
String
The billing city.
billing.company
String
The billing company.
billing.country
String
The billing country.
billing.first-name
String
The first name of the billing contact.
billing.last-name
String
The last name of the billing contact.
billing.phone
String
The phone number of the billing contact.
billing.state
String
The billing state.
billing.street
String
The billing street address.
billing.street2
String
The second line of the billing street address.
billing.zip
String
The billing ZIP code.
shipping
Object
Contains shipping address details.
shipping.city
String
The shipping city.
shipping.company
String
The shipping company.
shipping.country
String
The shipping country.
shipping.first-name
String
The first name of the shipping contact.
shipping.last-name
String
The last name of the shipping contact.
shipping.phone
String
The phone number of the shipping contact.
shipping.state
String
The shipping state.
shipping.street
String
The shipping street address.
shipping.street2
String
The second line of the shipping street address.
shipping.zip
String
The shipping ZIP code.
invoice
String
The invoice number associated with the transaction.
purchase-order
String
The purchase order number associated with the transaction.
customer-id
String
The unique identifier of the customer.
order-id
String
The unique identifier of the order.
email-address
String
The email address of the customer.
description
String
A description of the transaction.
comments
String
Additional comments about the transaction.
billing-is-shipping
String
Indicates whether the billing address is the same as the shipping address. Use true or false.
status-change-date
String
The date when the transaction status last changed.
display-message
String
A message to be displayed to the user.
provider-transaction-id
String
The unique identifier of the transaction from the payment provider.
trace-number
String
The trace number associated with the transaction.
settled-date
String
The date when the transaction was settled.
returned-date
String
The date when the transaction was returned.
returned-code
String
The code indicating the reason for the transaction return.
returned-message
String
The message indicating the reason for the transaction return.
ach-token
Object
Contains details of the ACH token.
ach-token.account-number
String
The masked bank account number associated with the token.
ach-token.account-type
String
The type of bank account. For example, Checking or Savings.
ach-token.created
String
The timestamp when the ACH token was created.
ach-token.customer-key
String
The unique key of the customer associated with the ACH token.
ach-token.default
Boolean
Indicates whether the ACH token is the default token.
ach-token.individual-name
String
The name of the individual associated with the ACH token.
ach-token.last-used
String
The timestamp when the ACH token was last used.
ach-token.merchant-id
String
The unique identifier of the merchant associated with the ACH token.
ach-token.routing-number
String
The bank routing number associated with the account.
ach-token.times-used
String
The number of times the ACH token has been used.
ach-token.token-description
String
A description of the ACH token, such as the accounts purpose.
ach-token.token-id
String
The unique identifier of the ACH token.
ach-token.updated
String
The timestamp when the ACH token was last updated.
merchant-id
String
The unique identifier of the merchant.
terminal-id
String
The unique identifier of the terminal.
software-type
String
The name and version of the software initiating the request.
paya-authorization
String
The authorization code from Paya.
The ach-transaction returns the following status and error codes:
401
If the ACH token has expired or the signature does not match the token.
204
Not found.
200
The ACH transaction list was generated successfully.
The following table describes the ACH transaction statuses:
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.
The status of the ACH transaction initially appears as Pending. The status changes from Settling to Settled when the ACH transaction is processed successfully.
The following table describes the codes returned by the receiving bank for ACH transactions:
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.
The member who previously authorized an entry has revoked authorization with the Originator.
R08
Payment stopped or stop payment on item.
The 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.
The 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.
The financial institution does not receive commercial ACH entries.
R14
Representment payee deceased or unable to continue in that capacity.
The representative payee is deceased or unable to continue in that capacity, beneficiary is not deceased.
R15
Beneficiary of account holder deceased.
The 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
Non transaction 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.
The 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 records 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.
The 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 non settlement.
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.
None
R37
Source Document Presented for Payment Check used for an ARC, BOC or POP entry has also been presented for payment.
None
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)
None
R41
Invalid transaction code. (ENR only)
None
R42
Routing number or check digit error. (ENR only)
None
R43
Invalid DFI account number. (ENR only)
None
R44
Invalid individual ID number. (ENR only)
None
R45
Invalid individual name/company name. (ENR only)
None
R46
Invalid representative payee indicator. (ENR only)
None
R47
Duplicate enrollment.
None
R50
State law affecting RCK acceptance.
None
R51
Item is ineligible, notice not provided, signature not genuine.
None
R52
Stop payment on item.
None
R61
Misrouted return.
Return entry was sent by RDFI to an incorrect ODFI routing/transit number.
R62
Incorrect trace number.
None
R63
Incorrect dollar amount.
None
R64
Incorrect individual identification.
None
R65
Incorrect transaction code.
None
R66
Incorrect company identification.
None
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.
None
R70
Permissible return entry not accepted.
None
R71
Misrouted dishonored return.
None
R72
Untimely dishonored return.
None
R73
Timely original return.
None
R74
Corrected return.
None
R80
Cross-border payment coding error.
None
R81
Nonparticipant in cross-border program.
None
R82
Invalid foreign receiving DFI identification.
None