How It Works
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:
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.
The Charge endpoint processes the payment based on the
delay_captureis 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.
delay_captureis true, the payment is authorized and Charge returns a pending transaction object with a status of
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.
The client server can refund captured transactions within 120 days of the capture date by calling CreateRefund.
While Charge returns results immediately, there is a slight delay between processing the transaction and the information being available in RetreiveTransaction or ListTransactions.
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.
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).
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.