SDK Integration Flow

Overview

This page explains how to integrate Onerway Web SDK in the order merchants typically implement it. Unlike Hosted Checkout, the SDK flow requires the merchant to handle frontend mounting, backend transaction creation, callback URL configuration, webhook verification, and end-to-end testing together.

The integration includes the following stages:

1. The merchant backend creates the transaction and obtains transactionId plus redirectUrl
2. The merchant frontend loads the SDK and mounts the checkout component into the merchant page
3. The SDK handles payment data collection, encrypted transmission, and 3D Secure / SCA flows
4. The merchant backend treats verified webhooks as the final transaction result and drives fulfillment, accounting, and shipping

Prepare prerequisites

Before starting the integration, confirm the following preparation is complete:

1. Activate your Onerway merchant account — Obtain your merchantNo
2. Retrieve signing credentials — You need them for backend request signing and webhook verification
3. Prepare a backend order endpoint — The backend calls Onerway APIs; the frontend does not create transactions directly
4. Prepare the frontend checkout page — Reserve a DOM container for the SDK and a UI area for payment status messages
5. Prepare callback URLs — Define the roles of returnUrl and notifyUrl, and make sure your backend can receive notifications

Prepare the transaction request and key fields

SDK integration starts with transaction creation on the merchant backend. For a basic payment flow, the minimal request usually includes the following fields:

A basic request example:

{
  "merchantNo": "800209",
  "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "txnType": "SALE",
  "txnOrderMsg": "{\"appId\":\"YOUR_APP_ID\",\"returnUrl\":\"https://your-domain.com/checkout/result?merchantTxnId=YOUR_TXN_ID\",\"notifyUrl\":\"https://your-domain.com/webhook\"}"
}

Tokenization, subscription billing, and authorization use different request parameters and include additional required fields from the corresponding capability documents.

Create the transaction and return the payment session

After the merchant backend successfully calls the Onerway API, it returns the payment session to the frontend. In SDK integration, the following two values are used for frontend initialization and transaction correlation:

The frontend usually needs only the current session parameters. Signing secrets and other sensitive configuration stay on the backend.

Load and mount the SDK on the frontend

The frontend mounting order is:

1. Load the official Onerway JavaScript SDK on the merchant checkout page
2. Prepare a dedicated DOM container for the payment component
3. Initialize the SDK with the transactionId and redirectUrl returned by the backend
4. Mount the SDK component into the checkout container
5. Reserve UI space for processing, success, and failure states

At this stage, the merchant frontend owns the customer experience layer, while the SDK owns payment data collection, encryption, and payment-specific flows.

Handle payment submission and 3D Secure / SCA

After the customer enters payment details into the SDK-rendered fields, the SDK handles submission and triggers authentication when required.

The payment submission flow is:

1. The SDK reads the initialized transactionId and redirectUrl
2. The customer submits payment details
3. If 3D Secure / SCA is required, the SDK continues the authentication flow
4. After authentication is complete, the customer returns to returnUrl
5. The frontend may update the customer-facing status based on synchronous SDK events

SDK synchronous callbacks are for frontend status display. They are not the business success signal for settlement, accounting, or fulfillment.

Configure returnUrl and notifyUrl

Both returnUrl and notifyUrl should be included in the transaction request, but they serve different purposes:

returnUrl is used for page navigation and customer display. It is not the final transaction source of truth. Final transaction status comes from verified webhooks, or from a verified order query when used as a recovery mechanism.

returnUrl may include merchantTxnId or a similar business identifier for order lookup and status display on the landing page.

Receive and process webhooks

Webhook handling is a backend responsibility in SDK integration. At minimum, the merchant backend processes the following:

1. Verify signatures first — Notifications that fail verification must not enter business processing
2. Enforce idempotency — Use transactionId or a merchant-defined idempotency key to prevent duplicate fulfillment
3. Update final state — Only verified notifications can update order status, accounting status, shipping status, or service activation
4. Return the required acknowledgment — After successful processing, return transactionId as required by the interface

A common processing order is: signature verification -> idempotency check -> business handling -> return transactionId.

If the scenario generates multiple notification types, such as BIND_CARD plus SALE in a tokenization flow, out-of-order arrival and coexistence of multiple event types can occur under the same transaction.

Test the integration

Integration testing includes local webhook testing and full payment flow testing.

Local webhook testing

The local webhook testing steps are:

1. Start your local service, for example at localhost:3000
2. Use a tunneling tool to generate a public HTTPS URL, for example ngrok http 3000
3. Set the generated public URL as notifyUrl
4. Save and verify the webhook signing secret currently in use

Full payment flow test

The full payment flow testing steps are:

1. Create an SDK transaction with sandbox credentials
2. Confirm the frontend receives transactionId and redirectUrl
3. Confirm the SDK component mounts and submits payment successfully
4. If 3D Secure / SCA is triggered, confirm the authentication path works and returns correctly to returnUrl
5. Check that the backend receives the webhook
6. Confirm signature verification passes and the order state is updated as expected

Verify fulfillment results

After the payment test completes, validate the following:

1. The backend logs show the webhook request was received
2. Webhook signature verification passed
3. Final order state was persisted from the webhook result
4. Fulfillment, accounting, shipping, or service activation logic was triggered correctly
5. Replaying the same notification does not create duplicate side effects

If the returnUrl landing page performs an order query, confirm that the customer-facing status remains consistent with the backend final order state.

Production deployment checks

Before production rollout, confirm the following:

1. notifyUrl points to a production-accessible endpoint
2. returnUrl points to the production result page
3. Production signing credentials are not mixed with sandbox credentials
4. Webhook verification, idempotency, and final-state persistence have been validated in the production configuration
5. The landing page can display the correct status by using merchantTxnId or an equivalent business identifier

Related documentation:

• API ReferencePayments API — View Web SDK initialization and payment parameter details
• Card Binding and Tokenization — Learn how to obtain and reuse tokenId with SDK
• Subscription Billing — Learn how to build recurring payment flows with SDK
• Appearance Customization — Learn how to align SDK components with your site's visual design