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:
You can find a complete example of the code in GitHub.
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:
The HTML for the body of index.html should look like the following:
Add an
initializeACH
function below theinitializeCard
function in the<script>
tag.In the options for initializing the ACH payment method, add the
redirectURI
andtransactionId
parameters to thepayments.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.
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
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.
Include the
ontokenization
event listener to get access to the payment token result.Add the following code after
// Checkpoint 2
in theDOMContentLoaded
event listener function.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 theoptions
parameter.
Add the following two helper functions below the
tokenize
function in the<script>
tag:Update the
handlePaymentMethodSubmission
function to:Take in a third
options
parameter.Update the
tokenize
call to addoptions
as the second parameter.
Add the following code in the
document.addEventListener('DOMContentLoaded', async function () {
function:Update the
handlePaymentMethodSubmission
function to disable theachButton
when tokenizing the payment.Add
achButton.disabled = true;
Update the
ontokenization
event listener to re-enable theachButton
during a failed payment.Add
achButton.disabled = false;
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.
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.