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.

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.

Note

ACH bank transfers are only supported by the Web Payments SDK and the Payments API in the United States. For more information, see Supported Payment Methods by Country.

If you're creating a new application or updating an existing one to add the ACH payment method, make sure that you update the following global constants inside the <script> tag in the code (ach.html in the example app), substituting the IDs from the Developer Dashboard for the placeholder ({APPLICATION_ID} and {LOCATION_ID}) values:

<script>
  const appId = '{APPLICATION_ID}';
  const locationId = '{LOCATION_ID}';

</script>

The following steps involve updating index.html in the root directory of the application to add the ACH payment method. These steps also apply if you are updating the example code in ach.html.

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>
  <form id="payment-form">
     <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" type="button">Pay with Bank Account</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 redirectURI must not contain query parameters; if they are present, you will see an error.
The redirectURI should be able to repopulate the payment flow, and re-initialize the Web Payments SDK payment form from either the URI or the transactionId. The transactionId is 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

Start up your local test server and navigate to it in your browser. If you're following the quickstart guide steps in the README, the default URL is http://localhost:3000.

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,
     intent: 'CHARGE',
     total: {
       amount: 100,
       currencyCode: 'USD'
     };
   };
 }

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(tokenResult.token);
    } catch (e) {
      cardButton.disabled = false;
      achButton.disabled = false;
      // add code here to handle errors
    }
  }
};

Test the application

This test simulates submitting bank account details and confirming the bank debit authorization for the payment.

Navigate to your test service (default http://localhost:3000).
Enter a first and last name.
Choose the Pay with Bank Account 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.
When prompted, confirm the payment details.
Important
If you added your own ACH authorization text in the application, you must remove the text and not add any additional text. The Web Payments SDK provides the ACH authorization text in the user prompt, which contains all of the bank transfer authorization instructions for the buyer to follow.
Success
You see the Plaid interface and are able to complete the flow using the test credentials provided at the bottom of the screen. You also confirm the payment details to allow bank account debit authorization. When these steps are completed, your application gets a payment token that is used to take an ACH bank transfer payment on your backend. The payment token that is returned uses the bauth: prefix.

Link to section

Step 3: Create a payment with bank authorization

Add the payment token as the source_id in a new payment request with the amount that the buyer has authorized. Your application can then run the payment request to process the payment.

The following example sends a Payments API CreatePayment request to create a new payment for $5.00 USD.

Create payment

The amount and currency values need to match the payment to be processed with Payments API.

Link to section

Step 4: Verify ACH payment

After the application authorizes the buyer's bank account information and processes payments, verify the completed payments with the following developer tools:

Check the Seller Dashboard and review the reports on the Transactions page. Note that only completed transactions show up in a report. ACH transactions take about 2-3 days to settle and to appear in a report. For more information, see Seller Dashboard.
Call the GetPayment endpoint to ensure that bank payments have been processed by reviewing the payment details. For more information about the ACH payment state statuses, see ACH Bank Transfer Payment.
Call the Square GraphQL endpoint to ensure that payments show up in the Payments query results. For more information, see GraphQL Overview.

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

Important

Success

Step 3: Create a payment with bank authorization

Step 4: Verify ACH payment

See also

On this page