Deprecated
This API is deprecated, see below for guidance on what to use instead.
Transactions API

What It Does

Note

Transactions API is deprecated. The API functionality is split into the new Payments API and a more robust Orders API. For more information, Payments and Refunds Overview and Orders: What it Does.

Use the Transactions API to authorize and capture online payments, link payments with orders for itemized transactions, and tie transactions to customer profiles for recurring payments.

Backend
Transactions API

Transactions API supports online payments, refunds, and multiparty transactions (splitting the net profit among multiple recipients). Payments and refunds processed with the Transactions API show up in the Square dashboard next to in-person payments processed with a Square reader. The Transactions API accepts the same credit cards as Square Readers and digital wallets such as Apple Pay on the Web and Masterpass.

Requirements and limitations
Permalink Get a link to this section

  • All payment recipients must provide a valid Square location ID. To receive payment, that account must also be associated with a verified bank account.

  • Receiving bank accounts must settle in the same currency as the transaction. For example, USD payments may only be deposited in a US-based bank account.

  • Charge requests collect explicit shipping information to mitigate fraud risk, but that information is not currently reportable.

  • Multiparty transaction support is limited to:

    • 1 additional recipient.

    • CAD, GBP, and USD transactions.

    • Flat amounts (no percentages).

    • Applications using OAuth with PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS.

  • An individual multiparty payment may not exceed 90% of the total transaction amount minus Square fees.

  • Sandbox support for Transactions API does not include support for multiparty transactions.

  • Square Gift Card redemption with Transactions API is not currently supported.

Product components
Permalink Get a link to this section

The Transactions API is a collection of payment processing endpoints (Charge, CaptureTransaction, CreateRefund, and VoidTransaction) and reporting endpoints (ListRefunds, ListTransactions, RetrieveTransaction).

Charge is the primary payment endpoint in the Transactions API and transactions processed with Charge typically include some (or all) of the following information:

  • Customer information — data related to the person making the purchase.

  • Payment information — data related to the exchange of money and an optional Square Order ID to link payment information with itemized order information.

  • Additional recipients — data related to entities other than the merchant (and Square) that will receive a portion of the transaction amount in a multiparty transaction. Additional recipients are optional and only used with multiparty transactions.

  • Reference information — notes or metadata typically used to link Square transactions with transaction information from other, non-Square systems (e.g., a non-Square order confirmation number).

  • Refunds — a list of refund objects associated with the transaction. Refund information only exists if at least one refund was processed through the Square Dashboard or the CreateRefund endpoint.

Multiparty transactions
Permalink Get a link to this section

When capturing payment, the Charge endpoint can split the net profit of a transaction with Square locations from other Square accounts. Multiparty transactions are typically used to monetize applications on a per-transaction basis (e.g., merchants pay an "application fee" when taking a payment on an eCommerce platform), share a portion of the transaction with partner companies or charities, or pay for a franchise license.

Important

Recipients listed under additional recipients will receive their portion of the payment 7 business days after the transaction is completed.

Multiparty transaction deposits are visible to both the originating merchant and additional recipients in the Square Dashboard. However, additional recipients do not receive deposit reports. For more detailed reports on incoming multiparty transaction payments,additional recipients must call the ListAdditionalRecipientReceivables and ListAdditionalRecipientReceivableRefunds endpoints.

Delayed-capture transactions
Permalink Get a link to this section

The default behavior for Charge is immediate capture, but this behavior can be overwritten. Online payments are authorized by the issuing bank at the moment of purchase. An authorized transaction means that the bank has put a hold on the funds but the merchant has not received payment. Customers see this as a "pending" transaction on their credit card statement. At some later point, transactions are reconciled by capturing the transaction. A captured transaction means that the merchant receives the funds previously put on hold by the issuing bank.

Refunds and voids
Permalink Get a link to this section

The Charge endpoint supports immediate capture and delayed capture for payment processing. Refunds can only be issued for captured transactions. Voids can only be issued for authorized transactions* and delayed-capture transactions are automatically voided after 6 days.

Get started

Use the build guides below to integrate with Transactions API