Take Payments

Transactions API Overview

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.

Square's 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's readers and digital wallets such as Apple Pay on the Web and Masterpass.

Server Side
Languages Supported
Additional Resources

Requirements and limitations

  • All Transactions API calls must include an authorization token in the header for the targeted merchant account. Anonymous API calls are not allowed.
  • 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.
  • Square Gift Card redemption is currently not supported.
  • Explicit shipping information is collected with transactions to mitigate fraud risk. This information is not currently reportable.
  • multiparty transaction amounts are packaged as Money objects. As a result, distribution values must be specified as flat amounts. Percentages are not supported at this time.
  • An individual multiparty payment may not exceed 90% of the total transaction amount minus Square's fees.
  • At this time, multiparty transaction support is limited to:
    • 1 additional recipient.
    • CAD, GBP, and USD transactions.
  • multiparty transactions must use OAuth tokens to authorize PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS calls to the Charge endpoint. multiparty Charge requests with personal access tokens are not supported.
  • multiparty transactions are not currently supported in the sandbox.

How to use it — the Transactions API data model

The Transactions API works with the following primary data types:

  • Money — represents the monetary value of the transaction. Money amounts are specified as integers in the base monetary unit for the specified currency. For example, in USD the base monetary unit is a cent so 5 USD is specified as 500 cents.
  • Tender — a collection of Money objects representing the payment method (or methods) used to complete the transaction. Currently, payments processed with the Transactions API will always only have one Tender object related to the nonce or customer card ID used for payment.
  • Address — represents a physical address and used to provide shipping and billing information.
  • Refund — represents the portion or amount of a refund that should be applied to a transaction. Refunds exist as standalone objects (accessible through the ListRefunds endpoint) in addition to being part of the Transaction object.
  • Transaction — represents the transaction being processed, including billing and shipping information, payment information, additional recipients, an order reference, refunds that were applied, and whether or not the transaction should be delayed.

It is important to note that a transaction request object is different from a fully populated Transaction object. The request object only includes information required by the Charge endpoint to process a payment. A fully populated Transaction object has a slightly different structure, includes information included in the request as well as meta information generated by Square's servers and related objects that may have been linked to the transaction at a later time (e.g., refunds).

A fully populated Transaction object is made up of the following logical sections: buyer information, payment information, additional recipients, reference information, and refunds.

Data grouping

Buyer information is anything related to the person making the purchase, including a customer id, email address, billing address, and shipping address.

Payment information is anything related to the exchange of money. A transaction cannot be successfully processed unless it includes an unique idempotency key, a payment nonce or customer card ID, and Money object representing the transaction amount. Transactions can also include Square Order IDs to link itemized order information to the processed transaction. Transactions can include a payment nonce generated by the SqPaymentForm or a customer card ID previously stored using the Customers API, but not both.

Additional recipients are entities other than the merchant (and Square) that will receive a portion of the transaction amount in a multiparty transaction. Recipients are defined using a Square location ID, a distribution amount (as a Money object), and a description that explains the reason for the distribution (e.g., "Franchise Royalty"). multiparty transaction payments may not exceed 90% of the total transaction amount minus Square's fees. Additional recipients are optional and only used with multiparty transactions. If the merchant (and Square) are the only recipients, this section is not used.

Reference information includes notes and metadata from other systems (e.g., a non-Square order confirmation number). Typically, the reference id is used to link Square transactions with transaction information from other, non-Square systems.

Refunds is 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, otherwise the field is not included in the Transactions object.

Delayed-capture transactions

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.

The default behavior for Charge is immediate capture, but this behavior can be overwritten using the delay_capture field in the Transaction request object.

How it works — the Transactions API process flow

Payment processing overview

The Transactions API serves three key functions: processing payments using a nonce, creating refunds, and reporting on transactions.

When processing payments and optionally creating refunds, a typical workflow can be very short (immediate capture transactions) or span multiple days (delayed capture transactions). In general processing a payment involves the following steps:

  1. The client server creates a Transaction request object using a customer card ID nonce stored previously or a payment nonce generated with SqPaymentForm and calls the Charge endpoint.
  2. The Charge endpoint processes the payment based on the delay_capture field:
    • If delay_capture is false, the payment is fully processed and credited to the associated Square account. Charge returns a transaction object with a status of CAPTURED, and the workflow is finished.
    • If delay_capture is true, the payment is authorized and Charge returns a pending transaction object with a status of AUTHORIZED.
  3. Within 6 days, the client server determines if the pending transaction should be voided or captured (otherwise it will be voided automatically):
    1. If the transaction should be voided, the client server calls VoidTransaction with the pending transaction ID.
    2. If the transaction should be captured, the client server calls CaptureTransaction with the pending transaction ID.
    3. The Square server finalizes the transaction by voiding the transaction or capturing payment.
    4. The client server calls RetreiveTransaction with the pending transaction ID to fetch the finalized transaction information.
  4. The client server can refund captured transactions within 120 days of the capture date by calling CreateRefund.
Process flow

For pending transactions, explicit calls to RetreiveTransactions are required to load the transaction details because VoidTransaction and RetreiveTransactions return an empty JavaScript body and 200 OK status response when transactions are successfully processed.

Transactions API reporting endpoints

The Transactions API also includes two reporting endpoints:

  • ListTransactions — returns a list of all transaction objects associated with a given location.
  • ListRefunds — returns a list of all refund objects associated with a given location.

These endpoints operate outside of the core payment processing workflow and can be called at any time.

Reversing payments

The Charge endpoint supports immediate capture (delay_capture: false) and delayed capture (delay_capture: true) for transaction processing. The process of reversing payment depends on the current state of the transaction:

  • Refunds can only be issued for captured transactions.
  • Voids can only be issued for authorized transactions.

Refunds on immediate captures must be issued through the Square Dashboard or the CreateRefund endpoint. Delayed capture transactions are automatically voided after 6 days.

Multiparty transactions

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.

Processing a multiparty transaction

Transaction splitting is handled after deducting Square's processing fees and the total amount of all partial payments may not exceed the net profit for the transaction.

For example, consider a transaction for 100 USD that includes an additional recipient payment of 10 USD. In this case, Square receives 3.20 USD (2.9% + 0.30 processing fee), which results in a net profit of 96.80 USD. The additional recipient receives 10 USD from the net profit and the merchant receives the remaining amount of 86.80 USD.

Mpt charge

Refunds on multiparty transactions

When a refund occurs for a multiparty transaction, the reimbursement is spread equally across all the parties (including Square) that received a portion of the original transaction.

For example, assume a 50% refund is issued on a multiparty transaction of 100 USD that included an additional recipient payment of 10 USD. A 50% refund means that the original payee should recover 50 USD. The refund amount is collected by recovering 50% of Square's fee (1.60 USD), 50% of the additional recipient payment (5 USD), and 50% of the deposit made to the merchant's bank account (43.40 USD).

Mpt refund

Chargebacks on multiparty transactions

Chargebacks on multiparty transactions are handled in line with Square's chargeback processes for standard transactions: the customer is reimbursed using funds from the merchant account that originated the transaction.

Reporting on multiparty transactions

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. For more information, please see the Reporting API Users Guide.

When querying transaction results through the ListTransactions and ReceiveTransaction endpoints, the additional_recipients object is only set for multiparty transactions. Standard transactions do not include the additional_recipients field.

Prev
< Payment Form Setup
Next
Transactions API Setup >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow