Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Payments API

ACH Bank Transfer Payment

Applications can take ACH bank transfer payments using the CreatePayment endpoint. When Square receives a CreatePayment request, it charges the specified bank and deposits the funds in the Square Balance of the account.

The processing of ACH payments is an asynchronous process. It can take up to three to five business days before the funds are available to the seller.

ACH payment support in the Square Payments API is a fully managed process. Square uses Plaid for bank account verification; however, you do not need to create the Plaid account. Square manages the entire process of bank account verification and processing of the payment.

Specify the payment source Permalink Get a link to this section

You do not specify bank information (such as the account number and routing number) directly in a CreatePayment request. Instead, you specify a payment token representing a bank account. This is a two-step process:

  1. Generate a payment token. Applications that integrate Square payments use Square-provided client-side libraries to take payment information from buyers and generate a secure payment token.

    Currently, only the client-side Square Web Payments SDK supports bank payments. This SDK can accept bank account information and generate a secure token. For more information, see Bank Transfer Payments.

  1. Charge the payment token. The application can then make a server-side Payments API call (CreatePayment endpoint) to charge 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.

    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: 2021-09-15' \
      -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}"
      }'

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

    {
      "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-FlS9Z5LyPjofrv9KWv11Kcf6mzqsc6z2hW1Qgk3LjHIF4OZX4LK3f3Pud8YioqOqAw",
          "country": "US",
          "ach_details": {
            "routing_number": "011401533",
            "account_number_suffix": "000",
            "account_type": "CHECKING"
          }
        }
      }
    }
    

    Some of the highlights in the response are:

    • The source_type is BANK_ACCOUNT and the transer_type is ACH, indicating that this is an ACH payment.

    • The payment status is PENDING.

    • total_money is the sum of amount_money and tip_money. Because the example does not specify a tip when taking the payment, total_money is the same as amount_money.

    • order_id is the order that the Payments API created. For compatibility with other products (for example, the Point of Sale application), all payments taken for a Square seller need an order. If you do not supply an order, the Payments API creates and maintains one automatically.

Square provides an end-to-end sample application on GitHub. For more information, see webpayments-quick-start.

Guidelines and limitations Permalink Get a link to this section

The following apply when using the Payments API for ACH payments:

  • Currently, the API supports ACH payments only in the United States. That is, in the CreatePayment request, the amount_money must specify USD as the currency.

  • Currently, only Square 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 is always true.

  • ACH payments cannot be canceled or completed using the API. The payment is created in a PENDING state and moves to COMPLETED or FAILED based on the success of the transfer. When a payment is completed, it can be refunded. The refund amount goes back to the buyer's bank account.

  • Unlike cards, currently bank account sources cannot be stored on file and charged later. Therefore, for each ACH payment, the buyer must provide the bank information.

  • You can apply ACH payments to an order. For more information, see Orders integration. However, applications can apply only one ACH payment to an order. For example, if you want to pay for a $100 order using an ACH payment, that payment must be for $100.

ACH disputes Permalink Get a link to this section

Disputes associated with ACH transactions differ from credit card disputes. Most notably, Square and its Originating Depository Financial Institution (ODFI) will honor a customer's return request if it is submitted to the Customer's bank within 60 days of the original transaction for customers with consumer accounts and within 2 days of the original transaction for customers with business accounts. When Square and its ODFI receive a return request from the customer's bank it will remove the funds from your Square account. Unlike credit card disputes, you cannot contest ACH reversals. In the event of an ACH reversal, you must contact and handle the dispute directly with your customer.

Testing ACH payments in the Square Sandbox Permalink Get a link to this section

To test ACH payments in the Square Sandbox, you can get a payment test token using one of the following methods:

  • Use a Square-provided ACH payment token. Square provides a set of fake ACH payment tokens for Sandbox testing. Using these payment tokens, you can test successful CreatePayment calls and test various error conditions (such as insufficient funds or an invalid account) relevant to taking an ACH payment.

    The Sandbox payment tokens are fake (they do not represent a real bank), but the CreatePayment endpoint returns a response as if the payment is processed. For a list of ACH payment tokens for Sandbox testing, see Sandbox Test Values.

  • Run a sample application with Web Payments SDK integrated to generate a payment token. This provides you with an end-to-end payment experience of taking an ACH payment. For step-by-step instructions, see Bank Transfer Payments.

    In Sandbox testing, the payment token that Web Payments SDK generates always results in a successful CreatePayment call. If you want to test payment errors, use Square-provided payment tokens.

    Although in production ACH payments can take three to five days to complete, the Sandbox is configured to complete payments with a one-minute delay. The CreatePayment endpoint first sets the payment status to PENDING. After a one-minute delay, it updates status to COMPLETED or FAILED (depending on the payment token used).