Scenarios

Pre-authorization and capture

Hold funds first and capture on fulfillment — scope of pre-authorization, the lifecycle and notifications from authorization to capture or void, boundaries and status handling, and the parameter differences across integration methods.

A pre-authorization holds the order amount on the cardholder's card without charging it immediately. Use it for hotel and car rental deposits, reservations, or securing funds before shipping — any business that needs to secure funds first and charge based on fulfillment later. The pre-authorization can be created through any integration method; capture or void is initiated by your server through the API.

Concepts and choices

Scope: txnType=AUTH applies to direct card payment and token payment (subProductType=DIRECT or TOKEN); it does not apply to local payment method, subscription, or installment transactions.
Full capture only: to charge less, void first and create a new transaction, or capture and then refund the difference through Create or cancel refund.
Capture or void, not both: only one of the two can be performed on a pre-authorization.

Lifecycle and notifications

Create the pre-authorization

Create the transaction through the method you use with txnType=AUTH; the remaining parameters are the same as an ordinary payment. When 3DS is required, handle the redirect as described in that method's integration flow.

Confirm the authorization

Confirm authorization success when you receive an authorization, capture, and void webhook with txnType=AUTH, status=S, and paymentStatus=A. Store both transactionId and paymentId from the response or notification: the former becomes originTransactionId when you capture or void, and the latter associates the authorization and its later capture or void with the same payment intent.

Capture or void

Call Capture or void authorization with originTransactionId set to the pre-authorization's transactionId. txnType=CAPTURE charges the full held amount; txnType=VOID releases the hold without charging.

Confirm the final result

A successful capture produces a webhook with txnType=CAPTURE, status=S, and paymentStatus=S; a successful void produces a webhook with txnType=VOID, status=S, and paymentStatus=N. The transactionId belongs to the capture or void operation and differs from the original authorization. Handle each operation idempotently by its own transactionId, and associate them with the same payment intent through paymentId.

Boundaries and status handling:

VOID applies only to an uncaptured pre-authorization: it releases the held amount and moves no funds. Money from a captured transaction can only be returned through a refund.
Different merchantTxnId values in capture or void requests are treated as different transactions; guard against repeated captures of the same originTransactionId on your side.
Decide whether the funds are held, captured, or released from paymentId plus paymentStatus (A after a successful AUTH, S after a successful CAPTURE, and N after a successful VOID), not by combining the status values of several notifications; see Webhooks for the distinction between status and paymentStatus.

Parameters by integration method

Integration method	Endpoint	Key parameters	Differences	Integration guide
Checkout	Create checkout payment	`txnType=AUTH`	3DS is guided by the checkout page	Checkout integration
Web SDK	Create SDK transaction	`txnType=AUTH`, `subProductType=DIRECT`	The SDK integration flow is the same as an ordinary payment	Web SDK integration
Direct API	Create direct transaction	`txnType=AUTH`, `subProductType=DIRECT` or `TOKEN`	Handle the `status=R` redirect yourself when 3DS is required	Direct API integration

Subscription payments

Choosing between managed and self-managed subscriptions, contract credentials and lifecycle notifications, renewals and plan changes, and the parameter differences across integration methods.

Profit sharing

Choose automatic or API-initiated profit sharing, configure result notifications, and associate profit shares and reversals with the original payment.