ACH

Home    Online Payments    REST 2.0 (Beta Version)    APMs    ACH

On this page:
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 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

  1. 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
  2. Send a POST /payments request with its mandatory parameters, including:
    • amount
    • currency: “USD“
    • paymentOption.alternativePaymentMethod class containing:
      • name: “ACH“
      • data 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
    • 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>"
    }
  }
}

See Handling the Response.

Payment with Payment Token

  1. 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 a buyerId.
    If the response does not include any appropriate payment tokens, then follow the instructions for Payment without Payment Token instead.
  2. 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.
  3. Send a POST /payments request with its mandatory parameters including:
    • amount
    • currency: “USD“
    • paymentOption.paymentToken.paymentTokenId: “<ID of the previously stored payment token>“
    • buyerDetails class containing:
      • buyerId: “<unique customer identifier in the merchant system>”
      • firstName, lastName, email, and phone
      • billingAddress class containing:
        • address, city,  state, and zip
        • 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:

  1. Pending
    • Response that includes result.status = “pending“ and paymentTokenId.
      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.
  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.
    • Webhook that includes  result.status= “update“. See Example Update Status Webhook.
  3. 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:
    • If the transfer was not successful, then Nuvei sends a webhook that includes result.status= “declined“, along with an error code.

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"
    }
  }
}
Last update iconLast modified November 2024