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

How It Works

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 What it Does .

A deeper look at Transactions API.

Transactions API

Transactions API process flow Permalink Get a link to this section

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

    • If the transaction should be voided, the client server calls VoidTransaction with the pending transaction ID.

    • If the transaction should be captured, the client server calls CaptureTransaction with the pending transaction ID.

    • The Square server finalizes the transaction by voiding the transaction or capturing payment and 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.

Important

While Charge returns results immediately, there is a slight delay between processing the transaction and the information being available in RetreiveTransaction or ListTransactions.

Processing multiparty transactions Permalink Get a link to this section

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 Permalink Get a link to this section

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 the Square 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 Permalink Get a link to this section

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