ACH Bank Transfer Payment
Applications take ACH bank transfer payments using the Square Web Payments SDK and the Payments API. This topic explains how to use the Payments API (CreatePayment endpoint) to accept ACH bank transfer payments.
The Square API platform manages the complexity of ACH payment processing. The Web Payments SDK uses Plaid for bank account verification. You don't need to have a Plaid account to process ACH payments. Square manages the entire bank account verification process and the ACH bank transfer.
An ACH payment results in a Payment
object whose source_type
is BANK_ACCOUNT
. Square ACH doesn't move money directly from the buyer's account to the bank account linked to the seller. Instead, it moves money from a buyer's bank account to the Square bank account, which then credits the Seller Balance. The seller can then transfer the money from Square to their linked bank account in the Seller Dashboard Banking application. If they've set up automated payouts, the money is moved into their linked bank account on the next payout.
Taking an ACH bank transfer payment is a two-step process:
Generate a payment token - When a buyer chooses ACH bank transfer as the payment method, the Web Payments SDK renders a Plaid UI to let the buyer provide bank account verification. After the bank account is verified, the SDK generates a payment token.
Charge the payment token - Your application makes a server-side
CreatePayment
call to charge the payment token. Thesource_id
field in the request holds the payment token.The following is an example
CreatePayment
request. It directs Square to charge $100 to the bank account identified by the payment token in thesource_id
field.Square processes the ACH payment and returns a Payment object in the response as shown:
Note the following response attributes:
The
source_type
isBANK_ACCOUNT
and thetransfer_type
isACH
.The payment
status
isPENDING
. When the transfer is complete, the status is updated toCOMPLETED
. If your application has subscribed to thepayment.updated
webhook event, it receives a notification when the transfer is complete.
Square provides an end-to-end sample application in GitHub. For more information, see the Web Payments SDK Quickstart sample project.
The following applies when using the Payments API for ACH payments:
The Payments API supports ACH payments only in the United States. In the
CreatePayment
request, theamount_money
must specify USD as thecurrency
.Only the Web Payments SDK supports bank payments.
ACH payments are asynchronous. It can take up to three to five business days to complete the payment.
For ACH payments, autocomplete must always be
true
.ACH payments cannot be canceled or completed using the Payments API. The payment is created in a
PENDING
state and moves toCOMPLETED
orFAILED
based on the success of the transfer. An ACH transfer can only be refunded after it'sCOMPLETED
. The refund amount returns to the buyer's bank account.Applications can apply only one ACH payment to an order and it must be for the full balance of the order. For more information, see Orders integration.
Disputes associated with ACH transactions differ from credit card disputes. Most notably, Square and its Originating Depository Financial Institution (ODFI) honor a customer's return request if it's submitted to the customer's bank within 60 days of the original transaction for customers with consumer bank accounts and within 2 days of the original transaction for customers with business bank accounts. When Square and its ODFI receive a return request from the customer's bank, it removes the funds from the seller's Square account. Unlike credit card disputes, a seller cannot contest ACH reversals. In the event of an ACH reversal, the seller must contact and handle the dispute directly with their customer.
To test ACH payments in the Square Sandbox, you can use the Web Payments SDK in Sandbox mode, which returns a Sandbox payment token. This provides you with an end-to-end payment experience of taking an ACH payment. For step-by-step instructions, see Take ACH Bank Transfer Payments.
The token is then used with the Payments API against the Sandbox CreatePayment
endpoint. If you want to test possible error scenarios on your backend Payments API code, you can bypass the Web Payments SDK and just use one of the Sandbox tokens provided by Square. For a list of ACH payment tokens for Sandbox testing, see Testing an ACH payment.
Note
Sandbox payment tokens don't represent a real bank, but the CreatePayment
endpoint returns a response appropriate for the Sandbox token used.
Although in production ACH payments can take three to five business days to complete, the Sandbox is configured to complete payments with a 1-minute delay. The CreatePayment
endpoint first sets the payment status
to PENDING
. After a 1-minute delay, it updates the status
to COMPLETED
or FAILED
(depending on the payment token used).
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.