Take ACH Bank Transfer Payments

Learn how to add a payment method to the application you built using the Quickstart project sample in Take a Card Payment with the Web Payments SDK to integrate the Web Payments SDK into your application.

Link to section

Overview

The steps in this topic add code to the application you created from the quickstart project sample. If you haven't created an application using the Quickstart, you need to do so before completing the following steps.

Note

ACH bank transfers are only supported by the Web Payments SDK in the United States.
As of July 29, 2022, the Web Payments SDK has updated its API requirements for applications that support a new Plaid OAuth-based authentication flow for banks that mandate it.

Square supports instant authentication through Plaid for verifying a buyer's bank account before making an ACH payment. Plaid lets your application quickly authenticate the bank account and uses the Web Payments SDK to connect to the ACH network to accept payments.

The following is the Plaid window that is rendered by the Web Payments SDK:

A graphic showing the Plaid ACH window that is rendered by the Web Payments SDK.

You can find a complete example of the code in GitHub.

Link to section

Step 1: Attach ACH to the page

The following code attaches the ACH method to the page:

Add the following HTML elements to the body of index.html before the existing card payment elements:

 <fieldset class="buyer-inputs">
   <input
     type="text"
     autocomplete="given-name"
     aria-required="true"
     aria-label="First Name"
     required="required"
     placeholder="Given Name"
     name="givenName"
     spellcheck="false"
   />

   <input
     type="text"
     autocomplete="family-name"
     aria-required="true"
     aria-label="Last Name"
     required="required"
     placeholder="Family Name"
     name="familyName"
     spellcheck="false"
   />
 </fieldset>
 <button id="ach-button">Pay with Bank Account</button>

The HTML for the body of index.html should look like the following:

<body>
 <fieldset class="buyer-inputs">
   <input
     type="text"
     autocomplete="given-name"
     aria-required="true"
     aria-label="First Name"
     required="required"
     placeholder="Given Name"
     name="givenName"
     spellcheck="false"
   />

   <input
     type="text"
     autocomplete="family-name"
     aria-required="true"
     aria-label="Last Name"
     required="required"
     placeholder="Family Name"
     name="familyName"
     spellcheck="false"
   />
 </fieldset>
 <button id="ach-button">Pay with Bank Account</button>

 <form id="payment-form">
   <div id="card-container"></div>
   <button id="card-button" type="button">Pay $1.00</button>
 </form>
 <div id="payment-status-container"></div>   
</body>

Add an initializeACH function below the initializeCard function in the <script> tag.
In the options for initializing the ACH payment method, add the redirectURI and transactionId parameters to the payments.ach object property. The redirect URI must not contain query parameters; if they are present, you will see an error.
The redirect URI should be able to repopulate the payment flow, and re-initialize the Web Payments SDK payment form from either the URI or the transaction ID. The transaction ID will be added to the URI as a query parameter.
```
 async function initializeACH(payments) {
   const ach = await payments.ach({ redirectURI, transactionId });
   // Note: ACH doesn't have an .attach(...) method
   // the ACH auth flow is triggered by .tokenize(...)
   return ach;
 }
```

In the DOMContentLoaded event listener, add code to initialize the ACH payment method:

let ach;
ach = await initializeACH(payments);

After adding the previous code, the listener should look like the following:

async function initializeACH(payments); {
     let card;
     let ach;
     try {
       card = await initializeCard(payments);
       ach = await initializeACH(payments);
     } catch (e) {
       console.error('Initializing Card failed', e);
       return;
     }
}

Test the application

Navigate to http://localhost:3000/ in your browser.

Success

You see a form that collects the buyer's first and last name along with a button to start an ACH bank transfer.

Link to section

Step 2: Get the payment token from the ACH payment method

Include the ontokenization event listener to get access to the payment token result.

Add the following code after // Checkpoint 2 in the DOMContentLoaded event listener function.

ach.addEventListener(`ontokenization`, function (event) {
  const { tokenResult, error } = event.detail;
  if (error) {
    // add code here to handle error
  }
  else if (tokenResult.status == 'OK') {
    const paymentResults = await createPayment(token);
  }
});

The ontokenization event fires after a buyer authorizes a payment using Plaid.

Update the tokenize function to:
- Take in a second optional options parameter.
- Update the paymentMethod.tokenize call to include the options parameter.
```
function tokenize(paymentMethod, options = {}) {
   paymentMethod.tokenize(options);
 }
```

Add the following two helper functions below the tokenize function in the <script> tag:

 function getBillingContact(form) {
   const formData = new FormData(form);
   // It's expected that the developer performs form field validation,
   // which doesn't occur in this example.
   return {
     givenName: formData.get('givenName'),
     familyName: formData.get('familyName'),
   };
 }

 function getACHOptions(form) {
   const billingContact = getBillingContact(form);
   const accountHolderName = `${billingContact.givenName} ${billingContact.familyName}`;

   return { accountHolderName };
 }

Update the handlePaymentMethodSubmission function to:

Take in a third options parameter.
Update the tokenize call to add options as the second parameter.

 async function handlePaymentMethodSubmission(
   event,
   paymentMethod,
   options // Add the options parameter here
 ) {
     // code preceding tokenize call.
     // update the tokenize function to add an `options` parameter.
     tokenize(paymentMethod, options); 
   }

Add the following code in the document.addEventListener('DOMContentLoaded', async function () { function:

 const achButton = document.getElementById('ach-button');
 achButton.addEventListener('click', async function (event) {
   const paymentForm = document.getElementById('payment-form');
   const achOptions = getACHOptions(paymentForm);
   await handlePaymentMethodSubmission(event, ach, achOptions);  // tokenize
   // ACH with the `accountHolderName` as an option.
 });

Update the handlePaymentMethodSubmission function to disable the achButton when tokenizing the payment.

Add achButton.disabled = true;

 async function handlePaymentMethodSubmission(event, paymentMethod) {
   event.preventDefault();

   try {
     // disable the submit button as we await tokenization and make a
     // payment request.
     cardButton.disabled = true;
     achButton.disabled = true; // Add this line.
     tokenize(paymentMethod, options);
   } catch (e) {
     // add code here to handle errors
   }
 }

Update the ontokenization event listener to re-enable the achButton during a failed payment.

Add achButton.disabled = false;

ach.addEventListener(`ontokenization`, function (event) {
  const { tokenResult, error } = event.detail;
  if (error) {
    cardButton.disabled = false;
    achButton.disabled = false; // Add this line.
    // add code here to handle errors
  }
  else if (tokenResult.status === `OK`) {
    try {
      const paymentResults = await createPayment(token);
    } catch (e) {
      cardButton.disabled = false;
      achButton.disabled = false;
      // add code here to handle errors
    }
  }
};

Test the application

Navigate to http://localhost:3000/ in your browser.
Enter a first and last name.
Choose the Pay button.
In the Plaid dialog box, enter user_good for the name and pass_good for the password. These test values are provided by the Plaid API and might change in the future.
Choose a bank.

Success

You see the Plaid interface and are able to complete the flow using the test credentials provided at the bottom of the screen. When complete, your application gets a payment token that is used to take an ACH bank transfer payment on your backend.

Link to section

Step 3: Process an ACH payment token on your backend

The payment token that your application generated for an ACH bank transfer payment is processed on your backend in the same way a payment token from one of the other payment methods is processed, with some exceptions. To learn about the specific processing requirements for ACH bank transfers, see ACH Bank Transfer Payment.

Link to section

ACH authorization

ACH authorization from a buyer must be captured prior to processing the ACH payment (for example, attempting to debit their bank account). Square requires that you present authorization to each buyer specifying the terms of the payment, and the buyer must agree to this mandate before you can initiate any payments from their bank account.

When you develop your application, add the following mandate text on the payment form for the buyer:

By clicking [“Accept"], you authorize [name of seller's business] to debit the bank account specified above for [specific amount of debit], pursuant to [seller]’s website and terms, until this authorization is revoked. You may revoke this authorization at any time by providing notice to [seller] within 30 (thirty) days of [date of this authorization]. Please print a copy of this authorization screen (or otherwise store it on your device) for your records.

Link to section

Docs

Take ACH Bank Transfer Payments

Overview

Note

Step 1: Attach ACH to the page

Success

Step 2: Get the payment token from the ACH payment method

Success

Step 3: Process an ACH payment token on your backend

ACH authorization

See also

On this page