Take ACH Bank Transfer Payments

Applies to: Web Payments SDK | Payments API

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

Link to section


You can add a payment method to the application you built using the quickstart project sample in Web Payments SDK Quickstart to integrate the Web Payments SDK into your application.

The following steps 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 these 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 on GitHub.


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're updating the example code in ach.html.

Link to section

1. Attach ACH to the page

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:

  2. Add an initializeACH function after 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're present, you get an error.

    The redirectURI should be able to repopulate the payment flow and reinitialize 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; }
  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:

    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 your local test server and navigate to it in your browser. If you're following the quickstart guide steps in the README file, the default URL is http://localhost:3000.

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


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

Link to section

2. Get the payment token from the ACH payment method

  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:

    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.

  2. 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); }
  3. Add the following two helper functions after 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.
    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); }
  5. 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. });
  6. 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 } }
  7. Update the ontokenization event listener to re-enable the achButton during a failed payment. Add achButton.disabled = false;.

Test the application

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

  1. Navigate to your test service (defaults to http://localhost:3000).

  2. Enter a first and last name.

  3. Choose the Pay with Bank Account 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.

  6. When prompted, confirm the payment details.

    A modal of the ACH bank authorization to confirm debit of bank account for payment.


    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 the bank transfer authorization instructions for the buyer to follow.


    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's used to take an ACH bank transfer payment on your backend. The payment token that's returned uses the oauth: prefix.

Link to section

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

4. Verify ACH payments

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 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 states, 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 Square GraphQL.

Link to section

See also