Integration Guide

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 merchant ID 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 merchant ID 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

Payee 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.

Payee Information Preparation:

• Collect and complete payee 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 Payee ID

• Enter or import payee details.
• Call the API: POST /api/v1/beneficiary/add
• Response: returns a beneficiaryId.

(2) Payee Reuse Logic

• Check whether the beneficiaryId already exists:
  • ✅ Reusable: use the existing beneficiaryId.
  • ❌ Information mismatch: call POST /api/v1/beneficiary/edit to update, then reuse the existing beneficiaryId.

(3) Initiate Payment Request

• Call the API: POST /api/v1/txn/remittance
• The system proceeds to transaction processing.

---

🅱️ Real-Time Payment Route

(1) Submit Dynamic Payee Information

• Call the API: POST /api/v2/txn/remittance
• Include real-time payee details in the request body (no need to pre-create a beneficiaryId).

(2) Initiate Payment Request

• The system proceeds directly to transaction processing.

3️⃣ Transaction Result Retrieval Phase

​ Result Retrieval Methods

Result Retrieval Methods:

1. Active Query Call the API: POST /api/v1/txn/query
2. 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

• ❌ Not Successful

  • Query the failure reason;
  • Handle manually or reinitiate the payment.