Scenarios

Saved payment methods

Let customers save a card for repeat purchases — choosing between customer opt-in and server-side tokenization, the tokenization result webhook, listing and deleting saved tokens, and the parameter differences across integration methods.

Saving a payment method (tokenization) turns the customer's card into a reusable tokenId, so later payments no longer require card details. With Checkout and the Web SDK, the customer chooses whether to save the card on the Onerway-hosted page; with the Direct API, your server submits the card data to tokenize it.

Concepts and choices

Customer opt-in (Checkout, Web SDK): submit a stable merchantCustId when creating the payment, and the Onerway page offers the customer the option to save their card. The option is not selected by default; the card is saved only after the customer opts in and completes the payment. For later payments within the same environment, merchantNo, and appId scope, keep submitting the same merchantCustId, and the page presents the customer's saved cards and completes card selection and payment on its own. Card data never passes through your system, so there is no PCI DSS requirement.
Server-side tokenization (Direct API): your server calls Create card token with the card data, then uses the returned tokenId for token payments. Card data passes through your system, so you must hold a valid PCI DSS certification.

Both paths produce the same kind of tokenId, but a server-initiated token payment must submit the CVC the customer enters for this purchase in cardInfo.cvv, so it still handles card data and requires PCI DSS. If you are not certified, keep repeat purchases on the Checkout or Web SDK page as well: the page presents the saved cards and completes the payment itself. Your server can verify saved records through List saved tokens but cannot initiate token payments on its own.

Generate merchantCustId from a stable server-side customer record rather than an email address, phone number, or other mutable data; never reuse one identifier across customers, and omit it for guests without a durable customer record. Card tokens and subscription tokens belong to different systems; see Scenario overview.

Lifecycle and notifications

A successful payment does not mean the card was saved. The saved payment method result webhook (txnType=BIND_CARD) is the final source of truth: store the notified tokenId only when status=S. Neither the return to returnUrl nor the synchronous response means the payment method was saved. Your server can also verify with List saved tokens.
Manage saved tokens: List saved tokens returns the id and tokenId of each binding record. When a customer asks to remove a card, call Delete card token with the binding record id — not the tokenId.
Token payments may still require 3DS: a server-initiated payment with a saved tokenId can also return status=R; handle the redirect as described in the Direct API integration flow.
Subscriptions that also save the card: when a managed card subscription submits subscription.bindCard=true, the tokenization result arrives in a separate saved payment method result webhook whose transactionId differs from the subscription payment webhook; handle each idempotently. See Subscriptions.

Parameters by integration method

Integration method	Endpoint	Key parameters	Differences	Integration guide
Checkout	Create checkout payment	`merchantCustId`	The checkout page presents the save option and saved cards; submit `subProductType` as `DIRECT`, `SUBSCRIBE`, or `INSTALLMENT` per scenario, with no dedicated value for saving cards	Checkout integration
Web SDK	Create SDK transaction	`merchantCustId`, `subProductType=DIRECT`	The SDK completes card selection and payment internally; the client needs no `tokenId`	Web SDK integration
Direct API	Create card token, Create direct transaction	Tokenization: card data, `merchantCustId`; card token payment: `subProductType=TOKEN`, `tokenInfo.tokenId`, `cardInfo.cvv`, `merchantCustId`	Tokenization and card token payment are two separate calls, both requiring PCI DSS	Direct API integration

Scenario overview

Saved payment methods, subscriptions, pre-authorization, profit sharing, and refunds explained by business scenario — concepts, lifecycle, and notifications — with the parameter differences across Checkout, Web SDK, and Direct API.

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.