Tutorial: How to Implement Auth/Capture (Two-Step Payments)

Introduction: Separating the “Ask” from the “Take”

The standard Tutorial: How to Implement a One-Step Purchase with Sola’s API is a blunt instrument: it combines the authorization and the debit into a single, atomic action. But what happens when fulfillment is not immediate? For physical goods, manual fraud reviews, or hotel security deposits, you need to separate the “ask” from the “take.” This is the function of the two-step payment API.

This workflow, known as payment authorization and capture, introduces a strategic delay between validating a customer’s ability to pay and actually moving the money. First, an Authorization places a temporary hold on the funds. Later, a Capture request finalizes the debit. This delayed settlement model is operationally superior for any business that ships physical goods, as it allows you to charge the customer at the moment of shipment, not the moment of order.

The primary financial benefit is the mitigation of refund fees. If an order is cancelled before it ships, you simply Void the authorization. This releases the hold instantly and incurs no transaction fees. Refunding a completed sale, by contrast, is a separate transaction with its own associated costs.

Step 1: The Authorization Request

The first step in the workflow is to secure the funds. The Authorization request is structurally similar to a Sale request, but its effect is fundamentally different. By sending a POST request to the /api/v1/payment/auth endpoint, you are asking the issuing bank to confirm the card is valid and has sufficient funds.

Upon a successful approved response, two things happen:

1. The funds are frozen on the customer’s card, reducing their available balance. This is known as placing a hold.
2. The Sola API returns a unique transaction_id. This ID is the critical link between the authorization and the future capture. You must store this ID in your database, associating it with the customer’s order.

Crucially, an authorization is not permanent. Issuing banks will automatically release the hold after a set period if the transaction is not captured. This auth expiry window is typically 7 days for most card schemes, though it can vary. Attempting to capture an expired authorization will fail. For a complete list of request parameters, consult the Official API Documentation.

Step 2: The Capture Request

The capture request is the action that finalizes the transaction and initiates the movement of funds. Unlike the authorization, this is almost always a server-to-server call, triggered by a backend business event—a shipping label being printed, an order passing a manual review, or a hotel guest checking out.

To perform the capture, you send a POST request to the /api/v1/payment/capture endpoint. The payload is simple, but it is critically dependent on the data you stored from Step 1:

• transaction_id: The unique ID returned from the successful authorization request. This tells the gateway which hold to convert into a debit.
• amount: The amount you wish to capture, specified in the currency’s smallest unit.

A powerful feature of the two-step payment API is the ability to perform a partial capture. If you authorized €100.00 but one item was out of stock, you can send a capture request for €80.00. The remaining €20.00 hold will be automatically released. It is a fundamental rule of card schemes that you cannot capture more than the originally authorized amount. An attempt to do so will result in an immediate decline.

Step 3: The Void (Releasing the Hold)

The Void operation is the primary financial advantage of the two-step flow. If a customer cancels an order before you have captured the funds, you should not issue a refund. Instead, you perform a void transaction. This action instructs the issuing bank to immediately cancel the authorization and release the hold on the customer’s card.

Sending a POST request to /api/v1/payment/void with the original transaction_id is an instruction to abandon the transaction. The key difference is cost. Releasing funds via a void is typically free, as no money has actually moved between banks. A Refund, conversely, is a separate, new transaction that reverses a completed sale and almost always incurs processing fees. Using voids for pre-shipment cancellations directly protects your profit margin.

Conclusion: Precision in Payments

The two-step payment API provides granular control over the transaction lifecycle, aligning the moment of debit with the moment of fulfillment. This adds a layer of state management to your application but offers significant financial and operational advantages.

A simplified logic flow looks like this:

// 1. At Customer Checkout

auth_response = Sola.authorize(order_details);

Database.save(order.id, auth_response.transaction_id);

// 2. On Order Shipment (Backend Process)

transaction_id = Database.find_by_order(order.id);

Sola.capture(transaction_id, order.final_amount);

This precision allows you to handle cancellations gracefully via voids and manage inventory changes with partial captures. Rigorous integration testing of this entire flow is essential. To ensure your backend logic is secure and fault-tolerant, review our complete A Developer’s Guide to Integrating a Secure Payment Gateway for production-ready best practices.