TNSPay BYOA API Overview

The Terminal API supports the following payment transaction messages

Sale (Purchase)

A purchase transaction is a single-step process where the card is authorized and the funds are captured immediately in the same flow. This means the merchant gets paid without any additional steps. It’s typically used in retail or e-commerce scenarios where the final amount is known at the time of sale.

Pre-Authorization

Pre-authorisation is the first step in a two-step transaction process used when the final amount is not yet confirmed. In this step, the merchant requests an authorisation for an estimated amount, and the issuer places a temporary hold on the cardholder’s funds. No money is transferred at this stage; it simply ensures that the funds are available and reduces the risk of non-payment. This method is commonly used in industries like hospitality, car rentals, and fuel stations where the final bill may vary.

Capture / Completion

Completion, also referred to as the capture of completion, is the second step after a successful pre-authorisation. Once the actual amount is confirmed, the merchant sends a capture request to convert the pre-authorised hold into a settled transaction. This process moves the funds from the cardholder’s account to the merchant’s account. If the capture of completion is not performed within the allowed timeframe (usually a few days), the hold expires, and the merchant will not receive payment.

Void

A Void occurs when a previously authorised transaction—whether a purchase or a pre-authorisation—is cancelled before settlement. In this process, the merchant sends a Void request to the acquirer, which informs the issuer to release the hold on the cardholder’s funds. No money is moved because the transaction never reaches the capture stage. Void are typically used when the merchant decides not to proceed with the transaction (e.g., order cancellation or service not rendered). This ensures the cardholder’s available credit or funds are restored promptly.

Reversal

A refund transaction is initiated when a customer requests reimbursement for a previously completed payment at the point of sale. This transaction type ensures that the original charge is reversed in a secure and traceable manner. Upon initiating the refund, the terminal communicates with the Payment Orchestration layer, which coordinates the necessary steps across payment processors and financial institutions to return the funds to the customer’s account. The orchestration system processes the request, updates the transaction record, and ensures the funds are released appropriately.

Incremental Auth

Incremental Authorization allows the authorized amount on an existing Pre-Auth to be increased so that it matches a higher final amount at completion. When a transaction completes for a value greater than the original Pre-Auth, an additional Authorization is used to raise the held amount up to the completion value — equalizing the authorized and completion amounts before the transaction is captured. This ensures the funds held against the card fully cover the final amount being charged.