SDK Integration Overview

Overview

Use Web SDK integration when you need a merchant-hosted checkout UI on your own site while delegating sensitive payment data handling and 3D Secure/SCA flows to Onerway.

Compared with Hosted Checkout, Web SDK gives you stronger UX and flow control, but requires frontend-backend orchestration. Compared with Direct API integration, Web SDK preserves customization while reducing PCI DSS scope (typically SAQ A) and implementation complexity.

Integration profile

Integration complexity
Checkout form: Embedded components (UI Elements) + merchant-owned checkout flow
Technical requirements: Front-end/back-end collaboration and baseline payment state management

Core strengths and ideal scenarios

Deeply customize checkout pages while preserving brand consistency
Let Onerway handle sensitive card data (PAN) to reduce local PCI DSS scope
Support advanced transaction models including card tokenization, recurring subscription charges, and authorization

SDK capabilities

Initialize checkout instances with session identifiers such as transactionId
Seamlessly integrate card payments and payment methods such as Apple Pay and Google Pay (APMs)
Natively support multidimensional scenarios including DIRECT, TOKEN, and SUBSCRIBE
Provide rich CSS variables and theme customization interfaces to match merchant UI standards

Web SDK payment interaction sequence

Use the following implementation sequence:

Collect checkout context: The merchant frontend collects base business parameters such as amount, currency, merchant order ID, and user context.

Request transaction creation: The frontend securely sends the checkout request to the merchant backend.

Initialize a payment intent: The merchant backend calls the Onerway order API and retrieves the unique transaction credentials: transactionId and redirectUrl.

Return session identifiers: The merchant backend returns required parameters such as transactionId and redirectUrl to the frontend.

Load the component library: The merchant frontend loads the official Onerway JavaScript SDK.

Mount the checkout component: The frontend initializes the SDK with transactionId and redirectUrl, then mounts it to the target DOM container.

Collect payment inputs and authenticate: The customer enters payment details in SDK-rendered fields. The SDK handles encrypted transmission and triggers Strong Customer Authentication (SCA), including 3D Secure challenge flows, when required by risk strategy.

Handle frontend status feedback: Use synchronous SDK events only for customer-facing states such as processing, success, or failure.

Finalize payment state on the backend: Treat verified webhook notifications as the authoritative transaction result. Use query/polling only as a complementary recovery mechanism to support fulfillment, accounting, and shipping workflows.

Supported scenario capabilities

Web SDK basic integration and UI customization

Learn how to load the SDK, initialize instances, manage component lifecycles, and deeply customize form styles through CSS properties.

Integration guideUI customization

One-time payments (DIRECT / AUTH)

Designed for common one-time charge scenarios (Sale/Auth). Use SDK components to securely collect card data and complete authorization and capture.

One-time paymentAuthorization and capture

Secure card binding and tokenization (TOKEN)

Generate and store payment tokens during or outside checkout to reduce repeat-purchase friction and improve conversion.

TokenizationFaster repeat checkout

Subscription (SUBSCRIBE)

Support flexible recurring billing plans for subscription payments.

Auto-renewalAdvanced scenario

Integration boundary comparison

Dimension	Hosted Checkout	Web SDK	Direct API
Page control	Low (rendered and hosted by Onerway)	Medium to high (merchant controls layout; core payment form is component-based)	Very high (full-stack merchant-built flow)
Engineering effort	Very low (backend redirect integration only)	Medium (frontend-backend coordination for state and event handling)	High (requires low-level payment routing and exception handling)
PCI DSS scope	SAQ A	Typically SAQ A (subject to implementation scope and compliance assessment)	At least SAQ D or higher (high compliance cost)
Recommended team profile	Limited engineering resources, fast go-live validation	Teams prioritizing branded native UX with solid engineering capabilities	Teams with professional payment gateway engineering and high compliance maturity
Typical business scenarios	Standard DTC e-commerce, outsourced business lines	Brand flagship checkout and unified cross-channel checkout UI	Platform-level payment routing (Payment Orchestration)