Learn how to take ACH bank transfer payments using the Square Payments API.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Payments API

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.

Link to section
Money movement

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:

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

  2. Charge the payment token - Your application makes a server-side CreatePayment call to charge the payment token. The source_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 the source_id field.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 10000,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_TOKEN}"
  }'
    Try in API Explorer

    Square processes the ACH payment and returns a Payment object in the response as shown:

    • 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
    {
  "payment": {
    "id": "VMnh7EfZj6XR7ykHLWCXAkYDnxEZY",
    "created_at": "2020-10-19T00:28:36.827Z",
    "amount_money": {
      "amount": 10000,
      "currency": "USD"
    },
    "status": "PENDING",
    "source_type": "BANK_ACCOUNT",
    "location_id": "LGEVM1WD8CF5Z",
    "order_id": "KiYkkC68kzRWroBkpyKN2RZYBeFZY",
    "total_money": {
      "amount": 10000,
      "currency": "USD"
    },
    "bank_account_details": {
      "bank_name": "Citizens Bank",
      "transfer_type": "ACH",
      "account_ownership_type": "INDIVIDUAL",
      "fingerprint": "sq-1-FlS9Z5LyPjofrv9KWv1...Pud8YioqOqAw",
      "country": "US",
      "ach_details": {
        "routing_number": "0111111111",
        "account_number_suffix": "000",
        "account_type": "CHECKING"
      }
    }
  }
}

    Note the following response attributes:

    • The source_type is BANK_ACCOUNT and the transfer_type is ACH.

    • The payment status is PENDING. When the transfer is complete, the status is updated to COMPLETED. If your application has subscribed to the payment.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.

Link to section
Guidelines and limitations

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, the amount_money must specify USD as the currency.

  • 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 to COMPLETED or FAILED based on the success of the transfer. An ACH transfer can only be refunded after it's COMPLETED. 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.

Link to section
ACH disputes

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.

Link to section
Testing ACH payments in the Square Sandbox

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

On this page