Direct API integration

With the Direct API integration you build your own payment page and call Create direct transaction from your server: card data or tokens are submitted by your backend, 3DS redirects are handled by you, and the final result is confirmed through webhooks. Unlike Checkout and the Web SDK, card data passes through your systems, so this integration requires PCI DSS compliance. In return you get a fully custom payment experience and direct server-side control over tokenization, token payments, subscription billing, and pre-authorization. Setup and method-specific flows for Apple Pay, Google Pay, and each local payment method on the Direct API are covered in Payment methods.

Before you begin

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.

The Direct API integration additionally requires PCI DSS compliance: to collect card numbers, expiry dates, and CVC on your own page and submit them to Onerway, you must hold a valid PCI DSS certification, transmit cardholder data over TLS, and never store sensitive authentication data such as CVC. If you are not certified, use Checkout integration or Web SDK integration instead — card data never reaches your server. Subscription renewals and pre-authorization captures do not submit card data and are not subject to this requirement; a card token payment still submits cardInfo.cvv and therefore remains within scope.

Integration flow

Tokenization and token payments

The Direct API flow for saving a payment method is: submit card data from your server to create a token, then pay with the tokenId, and list or delete saved records as needed. Choosing between customer opt-in and server-side tokenization, and the distinction between the three kinds of tokens, are covered in Saved payment methods.

1. Create a card token: call Create card token with the card data and a stable merchantCustId field, together with notifyUrl and returnUrl. When the response status field is R, redirect the cardholder to redirectUrl to complete 3DS authentication.
2. Confirm the saved result: the saved payment method result webhook (txnType=BIND_CARD) is the final source of truth — store the tokenId only when status=S. Neither the return to returnUrl nor the synchronous response means the payment method was saved. You can also verify with List saved tokens.
3. Make a token payment: call Create direct transaction with subProductType=TOKEN and the tokenInfo field (tokenId set to the card token returned earlier, provider omitted), submitting the CVC the customer enters for this purchase in cardInfo.cvv and the same merchantCustId used when the token was created. A token payment may also return status=R and require 3DS authentication; handle it as described in the integration flow.
4. 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.

Additional considerations for the Direct API integration: both creating a card token and making a token payment handle card data (a token payment must submit cardInfo.cvv), so both steps require PCI DSS. If you are not certified, keep both saving the card and repeat purchases on the Checkout or Web SDK page.

Subscriptions

Choosing between managed and self-managed subscriptions, contract credentials, and lifecycle notifications are covered in Subscription payments. This section explains how to make the calls on the Direct API once you have chosen. All three request types use Create direct transaction with subProductType=SUBSCRIBE and the subscription field, distinguished by subscription.requestType:

After the initial subscription succeeds, store the contractId and tokenId from the subscription payment webhook. The initial subscription can also be completed through Checkout or the Web SDK — later billing and updates still go through the Direct API.

Self-managed subscription renewal (requestType=1) submits contractId, tokenId, merchantCustId, and the amount for this cycle, with no card data, so renewals carry no PCI DSS requirement.

Managed subscription plan updates (requestType=2) use the stored contractId and tokenId; when the change takes effect is controlled by the subscription.changeMode field, and prorationMode controls whether the prorated amount is calculated by remaining days or submitted by you in proration.

Additional considerations for the Direct API integration: when a managed card subscription also submits subscription.bindCard=true, you receive a saved payment method result webhook and a subscription payment webhook with different transactionId values; handle each idempotently.

Pre-authorization

A pre-authorization holds the order amount on the cardholder's card without charging it immediately. On the Direct API, 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.

Call Create direct transaction with txnType=AUTH; the remaining parameters are the same as a direct card or token payment. When 3DS is required, handle the status=R redirect as usual. Store the transactionId and paymentId from the response; capture or void later through Capture or void authorization.

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

Local payments

A local payment method shares the create direct transaction API with card payment; only the parameter combination and flow shape differ. Set the productType field to the local payment method scope value and submit the lpmsInfo field (lpmsType selects the payment method; the remaining child fields are conditionally required per method), submitting DIRECT in subProductType for one-off payments and SUBSCRIBE for subscriptions. A local payment method does not support txnType=AUTH. Finding the supported methods and checking availability, handling the redirect and delayed settlement, method-specific parameters, and subscription behavior are covered in Local payment methods.

Additional considerations for the Direct API integration: productType=ALL is an aggregated Checkout display concept and is not supported by the Direct API, so you build the method list yourself and handle the customer action returned under status=R as well as the return to your page.

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 remaining parameters are the same as an ordinary transaction. 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 Direct API integration is determined by webhooks; the payload for each scenario is documented in the payment result webhook, the saved payment method result webhook, the subscription payment webhook, and the authorization, capture, and void webhook. Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in Webhooks.

Additional considerations for the Direct API integration: this integration uses all four notification types, so your webhook endpoint must accept every notification type involved in the scenarios you use. Tokenization, subscription-with-binding, and pre-authorization flows with a later capture or void produce several related notifications with different transactionId values — associate them through paymentId and contractId. The synchronous response may already return the terminal status=S; still wait for the webhook before completing the order. If the customer has returned but no webhook has arrived, fall back to Query transactions.

Go-live checklist

• You hold a valid PCI DSS certification; the payment page uses TLS and never stores CVC.
• status=R redirects and returnUrl returns are handled, and your server queries the transaction after the return instead of trusting URL parameters.
• Your webhook endpoint passes the Webhooks go-live checklist and accepts every notification type used by your scenarios, including tokenization, subscription, and pre-authorization.
• Stored tokenId, contractId, and paymentId values are kept as strings and associated with the customer or order.
• The sandbox run covers the 3DS Challenge flow, the 3DS Frictionless flow, and every tokenization, subscription, pre-authorization, and local payment scenario you use.