Integration Guide

Onerway issuing integration workflow covering preparation, business overview, environment setup, card creation, card transaction queries, and event notifications.

Preparation

The production and sandbox environments differ only in the request domain. You can first test the Onerway API in the sandbox environment. Once testing is complete, switch to production by changing the request domain and configuration parameters.

To create a sandbox merchant account, you need to provide an email, request source IP, and event receiving URL. After submission, check your email and click the link to log in to the merchant portal to obtain your merchant ID and secret key for signature verification. Then choose a suitable integration method to start the integration process.
We will whitelist the request source IP — only whitelisted IPs can call the Onerway API.
Obtain merchant information: Reset your password on first login to the merchant portal, then obtain your merchant ID and secret key.

Business Overview

After successful integration, contact your Onerway representative to obtain card products.
Create cardholders and cards. Onerway will push card change notifications to the merchant. Merchants can also actively query card information.
After card transactions, Onerway will push transaction information to the merchant. Merchants can also actively query transactions.

Environment

Onerway provides sandbox and production API environments for different stages of development, testing, and deployment. We recommend completing full integration testing in the sandbox environment before switching to production.

Endpoint	Environment
`https://sandbox-issuer.onerway.com/api/v1/merchant`	Sandbox
`https://issuer.onerway.com/api/v1/merchant`	Production

Card Creation

Complete the card creation workflow in the following order.

Step	Action	Endpoint / Source	Description
1	Get Card Product	Card Product List	Browse the card product list to select the card to issue. View BIN, issuing market, currency, card network, and usage details. Record the `cardProductId`. Please contact your integration representative to obtain this.
2	Create Cardholder	`POST /api/v1/merchant/cardholder/createCardholder`	Create a cardholder matching the card product. Submit required info (name, contact, billing address) to obtain `cardholderId`. If a suitable cardholder already exists, you can reuse it via the cardholder query API.
3	Create Card	`POST /api/v1/merchant/card/createCard`	Pass `cardProductId`, `cardholderId`, card amount, and other parameters to create a card (refer to API documentation for exact fields).
4	Query Card Info	See API - Cards - Queries	Query card-related information including: card creation and operation progress, basic card info and status, card balance or available limit, and sensitive info under compliance requirements.
5	Event Notification	See API - Webhooks - Card Operation Events	Onerway pushes event notifications to the merchant when card operations (creation, freeze, unfreeze, deposit, etc.) change status.

Card Transactions

After card spending, merchants can query card transaction records. Onerway will also push events to the merchant.

Step	Action	Endpoint	Description
1	Query Transactions	`POST /api/v1/merchant/queryTxnList`	Query transaction records covering all supported types (authorization, clearing, refund, etc.). Filtering, pagination, and response fields are defined in the API documentation.
2	Transaction Event Push	See API - Webhooks - Transaction Events	Onerway proactively pushes transaction event notifications to the merchant after card transactions occur.

Workflow Overview

Use Cases

Common ONERWAY Issuing use cases including advertising, SaaS subscriptions, e-commerce procurement, and more.

API Overview

Onerway Issuing Merchant API documentation covering card management, cardholder management, transaction queries, and event webhooks.