Attributes

• 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 perform an ACH payment using Nuvei Web SDK 2.0.

Additional Resources

• What’s new in Nuvei Web SDK 2.0 and the advantages of using it as an integration method – Web SDK 2.0
• Other Nuvei Web SDK 2.0 integration guides:
  • Getting Started with Nuvei Web SDK 2.0 – Card payment
  • Apple Pay
  • Google Pay
  • Nuvei Payment Tokens – Payment with an existing payment token
• All Web SDK 2.0 methods

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 ACH 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.

Payment (Deposit) Flow

To perform an ACH payment using Nuvei Web SDK 2.0, follow these steps:

1. Server-to-Server Authentication – Before submitting a payment using the client-side Web SDK 2.0, you need to send a server-to-server POST /orders REST API 2.0 request that authenticates your Nuvei merchant credentials and creates a session.
2. Frontend Web SDK Initialization – Import the websdk2.0.js library and instantiate Web SDK 2.0.
   1. ACH Details Retrieval (Optional) – Retrieve information about ACH to display on your payment page.
3. Payment Page Generation – Generate a payment page that includes ACH as a payment method.
4. ACH Payment Information Collection – Prompt the customer to provide bank account and other information ACH requires.
5. Frontend ACH Payment Submission – Send a payment() request with its required parameters, including parameters required by ACH.
6. Response Verification – Verify the response by sending a GET /entities/{processing-entity-id}/transactions/{transaction-id} REST API 2.0 request or by using webhooks.

1. Server-to-Server Authentication

Before submitting a payment using the client-side Web SDK 2.0, you need to send a server-to-server POST /orders REST API 2.0 request that authenticates your Nuvei merchant credentials and creates a session. For details, press here.

2. Frontend Web SDK 2.0 Initialization

For details, press here.

2a. ACH Details Retrieval (Optional)

To retrieve information about ACH to display on your payment page, send a getPaymentOptions() Web SDK 2.0 request with its required parameters and include:

• countryCode: “US“
• currency: “USD“

getPaymentOptions() Request for ACH

function getPaymentOptions() {
  nuveiWebSDK.getPaymentOptions({
    "countryCode": "US",
    "currency": "USD",
    "includeOptionalFields": false
  }).then(console.log);
}

The response includes the paymentOptions class with:

• fields array containing:
  • name: “<name of parameter to include in payment() request>“
• logoUrl

getPaymentOptions() Response for ACH

{
  "paymentOptions": [
    {
      "name": "ACH",
      "isDirect": true,
      "supportsFieldsRecovery": true,
      "fields": [
        {
          "name": "firstName",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "lastName",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "email",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "phone",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "nationalIdentificationNumber",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "address",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "city",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "state",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "zip",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "accountNumber",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        },
        {
          "name": "routingNumber",
          "dataType": "STRING",
          "isMandatory": true,
          "minimumLength": 1,
          "maximumLength": 30
        }
      ],
      "restrictions": [
        {
          "countryCode": "string",
          "currency": "string",
          "minimumAmount": 0,
          "maximumAmount": 0
        }
      ],
      "logoUrl": "https://secure.safecharge.com/ppp/resources/img/svg/solid-white/bank_transfer_new.svg"
    }
  ],
  "result": {
    "status": "success",
  }
}

3. Payment Page Generation

Generate a payment page that includes Bank Transfer (ACH) as a payment method. Use the logoUrl from the getPaymentOptions() response.

4. ACH Payment Information Collection

After the customer selects Bank Transfer (ACH), prompt the customer to provide:

• First name
• Last name
• Email
• Phone number
• Social Security number
• Address
• City
• State
• ZIP code
• Bank account number
• Bank ACH routing number

5. Frontend ACH Payment Submission

Send a Web SDK 2.0 payment() request with its mandatory parameters and include:

• paymentOption.alternativePaymentMethod class containing:
  • name: “ACH“
• custom class containing:
  • accountNumber: “<customer’s bank account number>“
  • routingNumber: “<bank’s nine-digit ACH routing number, including leading zeros>“
• buyerDetails class containing:
  • buyerId: “<unique customer identifier in the merchant system>”
  • firstName, lastName, email, and phone
  • nationalIdentificationNumber: “<customer’s Social Security number>“
  • billingAddress class containing:
    • address, city,  state, and zip
    • countryCode: “US“
• deviceDetails.ipAddress

Buyer Details Precedence Rule

In a payment() request, if the merchant includes any values in the billingAddress class (for example, country and email), the Nuvei system uses those values instead of values provided in the root of the buyerDetails class.

Example payment() Request for ACH

function payment() {
  nuveiWebSDK.payment({
    "merchantTransactionId": "<unique transaction ID in merchant system>",
    "sourceApplication": "string",
    "paymentOption": {
      "store": "none",
      "alternativePaymentMethod": {
        "name": "ACH",
        "merchantReference": "<unique request ID in merchant system>",
        "data": {
          "accountNumber": "111111111",
          "routingNumber": "012345678"
        },
      }
    },
    "buyerDetails": {
      "billingAddress": {
        "countryCode": "US"
      }
    }
  });
}

As an ACH payment progresses in the flow from pending to update and then to approved or declined, Nuvei sends you responses and webhooks:

1. Pending
   • Response with result.status = “pending“ and paymentTokenId.
     Example of Some Parameters in Response
     Plain text

     Copy to clipboard

     Open code in new window

     EnlighterJS 3 Syntax Highlighter

     {

     "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"

     }

     }

     }

     { "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" } } }

     {
       "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 with status=PENDING.
2. Update
   After a short time period, Nuvei generates a preApprovalId and stores it in the payment token record. Nuvei uses preApprovalId 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.
   Nuvei sends you a webhook containing status=UPDATE.
3. Approved or Declined
   The payment request is processed and Nuvei sends you a response and webhook with the final status within 2–5 days.
   • Approved
     • Response with result.status= “approved“.
     • Webhook with status=APPROVED.
   • Declined
     • Response with result.status= “declined“, along with an error code.
     • Webhook with status=DECLINE.

For more information about the output parameters in the Web SDK 2.0 payment() response, see Web SDK 2.0 Methods. For more information about Web SDK 2.0 webhooks, see the REST API 2.0 Webhooks page.

After receiving a payment() response, notify your server side and you can display a relevant message to the customer.

6. Response Verification

Before storing complete payment information in your system, you need to verify the response.

For details, press here.

Testing

For ACH test data, see the Testing section of the main ACH APM guide.