- METHOD TYPEACH
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
ACH (Automated Clearing House) is a US-based financial network used for electronic payments and money transfers. ACH payments, also known as direct payments, are a way to transfer money from one bank account to another without using paper checks, credit card networks, wire transfers, or cash.
This guide describes how to implement the Bank Transfer (ACH) APM into payment flows using Nuvei REST API 2.0.
The Bank Transfer (ACH) APM supports payments, refunds, and voids. Subscriptions (rebilling) and merchant-initiated transactions (MITs) are currently not supported.
Supported Countries
- United States
Supported Currencies
- USD
Prerequisites and Notes
- This document assumes that the merchant has completed all the account setup prerequisites, and is ready to integrate the APM into the payment flow.
- ACH only supports US-based IP addresses. IP addresses outside the US do not work.
- Transactions are conducted in US Dollars.
- Test credentials and testing scenarios should be obtained from Nuvei.
- You can contact Nuvei Support for any type of assistance.
- In addition to a response to a transaction request, Nuvei sends a webhook that includes the transaction processing result to the
webhookUrl
that Nuvei recommends the merchant provide in the transaction request.
Payment
The payment flow begins on the merchant’s payment page when a customer selects the Bank Transfer (ACH) payment method.
- For a new customer or if the customer’s ACH payment method details have not been previously captured, follow the instructions for Payment without Payment Token.
- For a returning customer, the merchant can offer the option to select previously captured ACH payment method details. Follow the instructions for Payment with Payment Token.
Payment without Payment Token
- After the customer selects Bank Transfer (ACH), prompt the customer to provide:
- First name
- Last name
- Phone number
- Social Security number
- Address
- City
- State
- ZIP code
- Bank account number
- Bank ACH routing number
- Send a POST
/payments
request with its mandatory parameters, including:amount
currency
: “USD“paymentOption.alternativePaymentMethod
block containing:name
: “ACH“data
block containing:accountNumber
: “<customer’s bank account number>“routingNumber
: “<bank’s nine-digit ACH routing number, including leading zeros>“
buyerDetails
block containing:buyerId
: “<unique customer identifier in the merchant system>”firstName
,lastName
,email
, andphone
nationalIdentificationNumber
: “<customer’s Social Security number>“billingAddress
block containing:address
,city
,state
, andzip
countryCode
: “US“
deviceDetails.ipAddress
urlDetails.webhookUrl
: “<URL to which Nuvei sends webhooks>”
Example /payments
Request without Payment Token
{ "processingEntityId": "<your processingEntityId>", "merchantTransactionId": "<ID of the transaction in the merchant system>", "amount": 10.5, "currency": "USD", "paymentOption": { "alternativePaymentMethod": { "name": "ACH", "data": { "accountNumber": "111111111", "routingNumber": "999999992" } } }, "custom": { "description": "Some description" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "buyerDetails": { "buyerId": "<unique customer identifier in your system>", "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "nationalIdentificationNumber": "123456789", "billingAddress": { "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "phone": "6175551414", "countryCode": "US" }, "urlDetails": { "webhookUrl": "<URL to which Nuvei sends webhooks>" } } }
Payment with Payment Token
- After a returning customer selects Bank Transfer (ACH), send a GET
/buyers/{buyer-id}/payment-tokens
request to retrieve a list of the customer’s existing payment tokens. In this flow, a returning customer is a customer for which Nuvei previously stored abuyerId
.
If the response does not include any appropriate payment tokens, then follow the instructions for Payment without Payment Token instead. - Offer the customer the option to select an existing payment method (stored in a payment token that represents the customer’s bank account), instead of collecting bank account details again.
- If the customer selects a previously captured payment method (payment token), then continue with the step 3.
- If not, then follow the instructions for Payment without Payment Token instead.
- Send a POST
/payments
request with its mandatory parameters including:amount
currency
: “USD“paymentOption.paymentToken.paymentTokenId
: “<ID of the previously stored payment token>“buyerDetails
block containing:buyerId
: “<unique customer identifier in the merchant system>”firstName
,lastName
,email
, andphone
billingAddress
block containing:address
,city
,state
, andzip
countryCode
: “US“
deviceDetails.ipAddress
urlDetails.webhookUrl
: “<URL to which Nuvei sends webhooks>”
Example of /payments
Request with a Payment Token
{ "processingEntityId": "<your processingEntityId>", "merchantTransactionId": "<ID of the transaction in the merchant system>", "amount": 10.5, "currency": "USD", "paymentOption": { "paymentToken": { "paymentTokenId": "test123" } }, "custom": { "description": "Some description" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "buyerDetails": { "buyerId": "<unique customer identifier in your system>", "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "nationalIdentificationNumber": "123456789", "billingAddress": { "address": "22 Main Street", "zip": "02460", "city": "Boston", "phone": "6175551414" }, "urlDetails": { "webhookUrl": "<URL to which webhooks are sent>" } } }
Handling the Response
As the transaction progresses in the flow from pending to update and then to approved or declined, Nuvei sends responses and webhooks:
- Pending
- Response that includes
result.status
= “pending“ andpaymentTokenId
.
Example of Some Parameters in Response
{ "paymentId": "34564567", "transactionId": "711000000015442640", "externalTransactionId": "20230613202325336703000000", "amount": 1, "currency": "USD", "transactionType": "Auth", "result": { "status": "pending" }, "authCode": "075449", "partialApproval": { "requestedAmount": 0, "requestedCurrency": "USD" }, "paymentOption": { "alternativePaymentMethod": { "name": "ACH", "data": { "accountNumber": "111111111", "routingNumber": "999999992" }, "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } }
- Webhook that includes
result.status
= “pending“. See Example Pending Status Webhook.
- Response that includes
- Update
- After a short time period, Nuvei generates a
preApprovalId
and stores it in the payment token record. Nuvei usespreApprovalId
to automatically approve certain payment transactions when the customer uses this payment method in the future. The parameter indicates that the payment method is authenticated; there is no need to perform the authentication process again. - Webhook that includes
result.status
= “update“. See Example Update Status Webhook.
- After a short time period, Nuvei generates a
- Approved or Declined
The payment request is processed and Nuvei sends a response and webhook with the final status within 2–5 days.- If the transfer was successful, then Nuvei sends:
- Response that includes
result.status
= “approved“. - Webhook that includes
result.status
= “approved“.
See Example Approved Status Webhook.
- Response that includes
- If the transfer was not successful, then Nuvei sends a webhook that includes
result.status
= “declined“, along with an error code.
- If the transfer was successful, then Nuvei sends:
Testing
For ACH test data, see the Testing section of the main ACH APM guide.
Example Payment Webhooks
Example Payment Webhook with status
=pending
{ "authorizingEntityId": "<your authorizingEntityId>", "processingEntityId": "<your processingEntityId>", "merchantTransactionId": "<ID of the transaction in the merchant system>", "buyerId": "JohnSmith123", "version": "2.0", "amount": 10.5, "currency": "USD", "transactionType": "Auth", "result": { "status": "pending" }, "timeStamp": "2024-08-28T12:11:47.337302438Z", "paymentOption": { "alternativePaymentMethod": { "name": "ACH", "data": { "accountNumber": "111111111", "routingNumber": "123456780" }, "merchantReference": "12391284AF87C7D2", "paymentTokenId": "c19ec945499a4641977ef5be6deb74df" } } }
Example Payment Webhook with status
=updated
{ "authorizingEntityId": "<your authorizingEntityId>", "processingEntityId": "<your processingEntityId>", "merchantTransactionId": "<ID of the transaction in the merchant system>", "buyerId": "JohnSmith123", "version": "2.0", "amount": 10.5, "currency": "USD", "transactionType": "Auth", "result": { "status": "updated" }, "timeStamp": "2024-08-28T12:11:47.337302438Z", "paymentOption": { "alternativePaymentMethod": { "name": "ACH", "data": { "accountNumber": "111111111", "routingNumber": "123456780" }, "merchantReference": "12391284AF87C7D2", "paymentTokenId": "c19ec945499a4641977ef5be6deb74df" } } }
Example Payment Webhook with status
=approved
{ "authorizingEntityId": "<your authorizingEntityId>", "processingEntityId": "<your processingEntityId>", "merchantTransactionId": "<ID of the transaction in the merchant system>", "buyerId": "JohnSmith123", "version": "2.0", "amount": 10.5, "currency": "USD", "transactionType": "Auth", "result": { "status": "approved" }, "timeStamp": "2024-08-28T12:11:47.337302438Z", "paymentOption": { "alternativePaymentMethod": { "name": "ACH", "data": { "accountNumber": "111111111", "routingNumber": "123456780" }, "merchantReference": "12391284AF87C7D2", "paymentTokenId": "c19ec945499a4641977ef5be6deb74df" } } }