API Reference
Integration Guide
View Transfer endpoints, webhooks, response codes, and common enum references.
Environment Description
- The request URLs for the production and sandbox environments differ only in their domain names. We recommend testing the Onerway API in the sandbox environment first. Once testing is complete, you can switch to the production environment by updating the request domain and configuration parameters.
- To create a sandbox merchant account for testing, please provide your registration email and intended domain name. After receiving the activation email, log in to the merchant portal using the provided link to obtain your merchantNo and secret key. Then, select the appropriate integration method to begin.
- The submitted email will be used to create your sandbox account. We will add your provided domain to our whitelist. Only whitelisted domains are permitted to access the Onerway API.
- When logging in to the merchant backend for the first time, you will be required to reset your password. After resetting, you can obtain your merchantNo and secret key.
Environment Configuration
Environment Domains
| Environment | Domain |
|---|---|
| Sandbox Environment | https://sandbox-api.onerway.com/payout |
| Production Environment | https://api.onerway.com/payout |
Field Description
Required Field Rules
| Identifier | Description |
|---|---|
M | Required field |
C | Conditionally required field |
N | Optional field |
Payment Process (Four Phases)
1️⃣ Initialization & Pre-Setup Phase
Node: Start → Pre-Setup
Beneficiary Field Retrieval:
- Method 1: Retrieve mandatory fields via API
POST /api/v1/acct/queryPaymentFeild - Method 2: Contact your account manager to obtain the mandatory field template according to country, currency, payment method, and entity type.
Beneficiary Information Preparation:
- Collect and complete beneficiary information in accordance with the required template.
2️⃣ Payment Initiation Phase
Branch Decision: Real-Time Payment Enabled?
| Condition | Route |
|---|---|
| ✅ Real-time payment channel enabled (contact Onerway to activate) | Real-Time Payment Route |
| ❌ Real-time payment channel not enabled | Default Payment Route |
🅰️ Default Payment Route
(1) Create beneficiary ID
- Enter or import beneficiary details.
- Call the API:
POST /api/v1/beneficiary/add - Response: returns a
beneficiaryId.
(2) Beneficiary Reuse Logic
- Check whether the
beneficiaryIdalready exists:- ✅ Reusable: use the existing
beneficiaryId. - ❌ Information mismatch: call
POST /api/v1/beneficiary/editto update, then reuse the existingbeneficiaryId.
- ✅ Reusable: use the existing
(3) Initiate Payment Request
- Call the API:
POST /api/v1/txn/remittance - The system proceeds to transaction processing.
3️⃣ Transaction Result Retrieval Phase
Result Retrieval Methods
Result Retrieval Methods:
- Active Query Call the API:
POST /api/v1/txn/query - Asynchronous Callback The system sends a Webhook notification with transaction results.
Webhook Payload Includes:
- Transaction status (Success / Failure / Processing)
- Error code and description (if applicable)
4️⃣ Transaction Completion Phase
Determine Transaction Status:
- ✅ Success
- Retrieve electronic receipt:
POST /api/v1/txn/queryVoucher
- Retrieve electronic receipt:
- ❌ Not Successful
- Query the failure reason;
- Handle manually or reinitiate the payment.