API Integration Overview

Overview

Use Direct API when you need full control of checkout UX, risk signal collection, and payment orchestration in a server-to-server integration. Merchants call Onerway gateway endpoints directly, host a merchant-hosted payment page, and orchestrate the end-to-end payment flow.

Direct API is designed for teams that need highly customized payment journeys and tight integration with internal systems.

Compliance Impact

Direct API expands your PCI scope. Since merchants handle sensitive cardholder data directly (for example PAN and CVV), they typically need to meet PCI DSS (Payment Card Industry Data Security Standard) SAQ D or a higher compliance level.

Core Capabilities

Comparison with Other Integration Methods

Applicable Scenarios

Use Direct API if you need:

• Deep Checkout Customization — Full control over payment UI, state machine, and failure recovery paths
• Data-driven Risk Operations — Feed payment behavior signals into anti-fraud models and improve auth approval rates
• Cross-platform Consistency — Deliver a unified payment experience across Web, App, and mini-programs
• Complex Transaction Orchestration — Integrate payments deeply with order, inventory, risk, and fulfillment systems
• Established PCI Program — Operate a cardholder data environment (CDE) with mature compliance controls

Integration Requirements

Before you start, make sure you have:

• PCI DSS Readiness — Typically SAQ D (or higher) is required to collect, process, and transmit card data
• Security Infrastructure — Implement TLS 1.2+, key management, access control, and auditable logging
• Backend Payment Engineering — Implement signing and verification, idempotency control, retries, and rollback handling
• Frontend Integration Capability — Build payment pages and handle 3DS challenge, return flows, and state synchronization

How It Works

1. Create order — The customer places an order and enters the payment stage
2. Collect payment inputs — The merchant payment page captures required payment data and performs frontend validation
3. Submit payment request — The merchant server sends an authorization/capture request to Onerway gateway
4. Redirect for 3DS challenge (if required) — If 3DS is triggered, redirect the customer to the issuer ACS challenge flow
5. Update temporary UI status from synchronous response — Use the sync response to show immediate customer feedback
6. Finalize order state from verified webhook — Verify webhook signatures and update final accounting and fulfillment state

Important: Use signature-verified webhook events as the source of truth for fulfillment and accounting. Use synchronous responses only for immediate customer feedback.

Payment Capabilities

Supported Payment Methods

Authorization (AUTH) Capability Notes

• Transaction semantics: AUTH places an authorization hold and does not immediately capture funds
• Subsequent capture: perform CAPTURE by referencing the original authorization transactionId (commonly as originTransactionId)
• 3DS handling: when the sync response returns status=R with redirectUrl, redirect the customer to complete issuer-side 3DS
• Final state source: use signature-verified webhook events as the source of truth for final authorization outcome

Supported Card Brands

Note: American Express and JCB require separate application to enable. Please contact your account manager.

Security and Compliance

PCI DSS Compliance

Under Direct API, merchants process cardholder data directly and must satisfy PCI DSS controls across system, network, process, and organizational layers (typically SAQ D scope).

3D Secure Authentication

API supports 3D Secure 2.x authentication. Merchants must implement 3DS redirect/challenge handling, callback processing, and failure fallback logic, and provide returnUrl for post-authentication redirects.

Data Encryption

All API traffic must use TLS 1.2+. Requests should be signed to ensure integrity and non-repudiation, and Webhook processing should include signature verification and replay protection.