Checkout integration

Create every Checkout payment on your server: call the create checkout payment API to obtain a redirectUrl, then redirect the customer's browser to the Onerway-hosted checkout page to complete the payment. Onerway handles the payment page, 3DS authentication, and PCI compliance. Browser, device, and cardholder IP data are collected by the hosted checkout page — do not collect or submit them from your server.

Before you begin, follow Setup to obtain your API credentials and add your server's public outbound IP addresses to the allowlist for the target environment. Generate sign for each request according to Request signing. Before going live, follow Sandbox testing to verify all scenarios used by your integration in the sandbox.

Checkout uses Onerway's Google Pay integration, so no Google Pay website registration is needed; that applies only to Direct API integrations.

Integration flow

Payment method display scope

Which payment methods the checkout page displays is controlled by the productType field; the actual processing model is further determined by subProductType and txnType.

How each payment method is supported on the checkout page and what to prepare is covered in Payment methods.

Saved card option

When you submit a stable merchantCustId field, the checkout page offers the customer the option to save their card information. The option is not selected by default; the card is saved only after the customer opts in and completes the payment. Submit the subProductType field according to the scenario — DIRECT, SUBSCRIBE, or INSTALLMENT; no dedicated value is needed for saving cards. Keep submitting the same merchantCustId on later payments, and the checkout page presents the customer's available saved cards.

Additional considerations for the Checkout integration: for subscription checkout, submit the customer identifier in the top-level merchantCustId; the subscription.merchantCustId field is optional, and when it is also submitted the two values must match. The requirements for merchantCustId, the saved payment method result webhook, and listing and deleting saved tokens are covered in Saved payment methods.

Subscriptions

Initial subscriptions are completed on the checkout page: submit the subProductType field =SUBSCRIBE together with the subscription field (requestType=0); the billing model is determined by the subscription.selfExecute field. Renewals and plan changes are initiated by your server through the Direct API; the checkout page is not involved.

Choosing between managed and self-managed subscriptions, contract credentials, lifecycle notifications, and plan change rules are covered in Subscription payments.

Pre-authorization

When the txnType field is AUTH, the checkout page performs a pre-authorization: the order amount is held on the customer's card without an immediate charge, and any 3DS authentication is guided by the checkout page. After the pre-authorization succeeds, store the transactionId and paymentId from the response; your server later captures or voids through Capture or void authorization.

Scope, the lifecycle from authorization to capture or void, notifications, boundaries, and status handling are covered in Pre-authorization and capture.

Profit sharing

Profit sharing applies to the platform model: the platform merchant creates the payment with the receiving sub-merchant's merchantNo, and the payment is eligible for profit sharing only when you submit the paymentMethodOptions field with profitShare=true in its share object; the checkout payment flow is the same as an ordinary payment. When you also set profitShareRate, Onerway allocates funds automatically after a successful SALE or CAPTURE; without it, your server initiates profit sharing through the API. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Submit paymentMethodOptions as a JSON string as required by the API.

Choosing between automatic and API-initiated profit sharing, result notifications, queries, and reversals are covered in Profit sharing.

Confirm the payment result

The final result of a Checkout payment is determined by webhooks: the payment result webhook for ordinary payments, the subscription payment webhook for subscriptions, and the authorization, capture, and void webhook for pre-authorizations. When the customer opts in to saving a card, the tokenization result arrives separately in the saved payment method result webhook. Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in Webhooks.

Additional considerations for the Checkout integration: the returnUrl return is not guaranteed to carry transaction parameters, so do not use any parameter on the return URL to drive order processing; if the customer has returned but no webhook has arrived, fall back to Query transactions. Transaction status is determined by the status response field and the same field in webhooks; see the API Reference for all values.