# Checkout integration

> Create a checkout payment on your server, redirect the customer to the Onerway-hosted page to pay, and confirm the result through webhooks.

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](/payments/get-started/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](/payments/get-started/request-signing). Before going live, follow [Sandbox testing](/payments/get-started/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](/payments/online-payments/payment-methods/google-pay#website-registration-before-going-live).

## Integration flow

<steps level="3">

### Create a payment on your server

Create the transaction through [Create checkout payment](/payments/api-reference/endpoints/create-checkout-payment). The [`txnOrderMsg` field](/payments/api-reference/endpoints/create-checkout-payment#request-txnOrderMsg) must include `returnUrl` (synchronous return address) and `notifyUrl` (webhook notification address). In the [`products` field](/payments/api-reference/endpoints/create-checkout-payment#request-txnOrderMsg-products), product amounts, discounts, and shipping fees must add up to `orderAmount`.

After creation the transaction status is `U` (unpaid), and the response returns the [`redirectUrl` field](/payments/api-reference/endpoints/create-checkout-payment#response-data-redirectUrl).

### Redirect to the checkout page

Redirect the customer's browser to `redirectUrl`. The customer selects a payment method and completes the payment on the hosted page; when 3DS authentication is required, the checkout page guides the customer through it — no merchant handling is needed.

### Handle the payment return

After payment the customer returns to your site through `returnUrl`. The synchronous return is for page flow only: add your order ID to `returnUrl`, show the customer a "processing" state when they return, and process the order once the webhook arrives. The final payment result is determined by [webhooks](#confirm-the-payment-result).

</steps>

## Payment method display scope

Which payment methods the checkout page displays is controlled by the [`productType` field](/payments/api-reference/endpoints/create-checkout-payment#request-productType); the actual processing model is further determined by `subProductType` and `txnType`.

| Goal | Server-side input |
| --- | --- |
| Display card payment methods only | `productType=CARD` |
| Display all available payment methods | `productType=ALL`; the customer chooses on the checkout page. |
| Lock to a single local payment method or wallet | `productType=ALL` together with the [`lpmsInfo.lpmsType` field](/payments/api-reference/endpoints/create-checkout-payment#request-lpmsInfo-lpmsType); the checkout page displays only that payment method, with `ApplePay` and `GooglePay` for the wallets. |

How each payment method is supported on the checkout page and what to prepare is covered in [Payment methods](/payments/online-payments/payment-methods).

## Saved card option

When you submit a stable [`merchantCustId` field](/payments/api-reference/endpoints/create-checkout-payment#request-merchantCustId), 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](/payments/api-reference/endpoints/create-checkout-payment#request-subProductType) 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](/payments/api-reference/endpoints/create-checkout-payment#request-subscription-merchantCustId) 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](/payments/online-payments/scenarios/saved-payment-methods).

## Subscriptions

Initial subscriptions are completed on the checkout page: submit the [`subProductType` field](/payments/api-reference/endpoints/create-checkout-payment#request-subProductType) `=SUBSCRIBE` together with the [`subscription` field](/payments/api-reference/endpoints/create-checkout-payment#request-subscription) (`requestType=0`); the billing model is determined by the [`subscription.selfExecute` field](/payments/api-reference/endpoints/create-checkout-payment#request-subscription-selfExecute). 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](/payments/online-payments/scenarios/subscriptions).

## Pre-authorization

When the [`txnType` field](/payments/api-reference/endpoints/create-checkout-payment#request-txnType) 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](/payments/api-reference/endpoints/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](/payments/online-payments/scenarios/pre-authorization).

## 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](/payments/api-reference/endpoints/create-checkout-payment#request-paymentMethodOptions) 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](/payments/online-payments/scenarios/profit-sharing).

## Confirm the payment result

The final result of a Checkout payment is determined by webhooks: the [payment result webhook](/payments/api-reference/webhooks/payment-result) for ordinary payments, the [subscription payment webhook](/payments/api-reference/webhooks/subscription-payment) for subscriptions, and the [authorization, capture, and void webhook](/payments/api-reference/webhooks/authorization-capture) for pre-authorizations. When the customer opts in to saving a card, the tokenization result arrives separately in the [saved payment method result webhook](/payments/api-reference/webhooks/payment-method-result). Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in [Webhooks](/payments/get-started/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](/payments/api-reference/endpoints/query-transactions). Transaction status is determined by the [`status` response field](/payments/api-reference/endpoints/create-checkout-payment#response-data-status) and the same field in webhooks; see the API Reference for all values.