ONERWAY provides two payment modes. The payment flow consists of four phases:
Step 1: Environment Preparation
All integrations must be tested in the sandbox environment first. Switch to production only after confirming functionality is correct.
| Environment | Domain |
|---|---|
| Sandbox | https://sandbox-api.onerway.com/payout |
| Production | https://api.onerway.com/payout |
Step 2: Integration Signature
Before calling any API, you must generate a signature (sign) and use the private key (privateKey) to ensure request security.
For complete signature documentation, refer to: Integration Signature DocumentationTransfer API
Step 3: Confirm Payment Method
Select the appropriate payment method based on business requirements:
Available payment methods depend on the target country and currency.
Step 4: Confirm Beneficiary Required Fields
Get required field information based on the following parameters: country, currency, entity type, payment method.
API: Query Beneficiary Required FieldsTransfer API POST /api/v1/acct/queryPaymentFeild
First create a beneficiary to get beneficiaryId, then reference this ID to initiate payment.
Beneficiary Reuse Logic:
| Scenario | Handling |
|---|---|
| Beneficiary exists | Query and reuse existing beneficiaryId |
| Beneficiary info mismatch | Call edit API to update, then reuse |
| New beneficiary | Call create API to get new beneficiaryId |
API: Initiate PaymentTransfer API POST /api/v1/txn/remittance
Pre-submission Checklist:
| Check Item | Requirement |
|---|---|
| Beneficiary status | Must be PASS |
| Account balance | Sufficient balance |
| Fee mode | chargeFlag correctly set |
Core Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| merchantNo | string | M | Merchant ID |
| beneficiaryId | long | M | Beneficiary ID |
| sourceAmount | number | M | Payment amount |
| sourceCurrency | string | M | Payment currency |
| targetAmount | number | M | Expected payout amount |
| targetCurrency | string | M | Payout currency |
| requestId | string | M | Merchant request unique identifier (prevents duplicate submission) |
| reference | string | N | Transaction reference (visible to beneficiary, 0-140 characters) |
| transactionPurpose | string | M | Payment purpose (enum value 0-5) |
| chargeFlag | string | M | Y=Full amount arrival / N=Non-full amount arrival |
| feeBearing | string | C | OUR / SHA (required for SWIFT) |
| sign | string | M | Request signature |
M=Mandatory, C=Conditional, N=Optional
Method 1: Payment Callback (Webhook)
When payment status changes (Processing → Success/Failed), the system proactively sends notifications to the callback URL provided by the merchant.
Callback content includes: transaction status (success/failed/processing), error code and description (if applicable).
API: Payment Callback NotificationTransfer API
Method 2: Active Query
| Method | API | Path | Use Case |
|---|---|---|---|
| Single Query | Single Payment QueryTransfer API | POST /api/v1/txn/query | Callback lost, user inquiry, amount verification |
| Batch Query | Batch Payment QueryTransfer API | POST /api/v1/txn/queryList | Financial reconciliation (recommended daily), risk monitoring |
Success: Download electronic payment receipt
API: Query Payment ReceiptTransfer API POST /api/v1/txn/queryVoucher
Failed: Query failure reason, manually process or re-initiate payment.
| Status | Description |
|---|---|
| Created | Payment transaction has been created |
| Pending Approval | Merchant has enabled approval workflow, transaction awaiting approver review |
| Rejected | Approver rejected the transaction |
| Pending Execution | Approved but execution time not reached, waiting for execution |
| Cancelled | Cancelled while in pending execution status |
| Processing | Payment is being processed |
| Paid | Payment successful, funds have reached the beneficiary |
| Failed | Payment processing failed |
| Returned | Payment was returned after success (e.g., returned by receiving bank) |