Learn how to take ACH bank transfer payments in a web client with the Web Payments SDK.
Web Payments SDK

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.

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.

The following code attaches the ACH method to the page:

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

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

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    <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>
    
  2. 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.

  3. 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:

Test the application

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

    A graphic showing a typical buyer information input and the ACH Pay layout for Web Payments SDK integrations.

    Success

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

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

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

  2. Update the tokenize function to:

    • Take in a second optional options parameter.

    • Update the paymentMethod.tokenize call to include the options parameter.

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

  4. Update the handlePaymentMethodSubmission function to:

    • Take in a third options parameter.

    • Update the tokenize call to add options as the second parameter.

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

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

    • Add achButton.disabled = true;

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

    • Add achButton.disabled = false;

Test the application

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

  2. Enter a first and last name.

  3. Choose the Pay button.

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

  5. Choose a bank.

    An animation showing the buyer ACH payment experience in the Web Payments SDK Quickstart.

    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.

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.

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.

We've made improvements to our docs.
Prefer the old format?