# Integration Guide

> View Transfer endpoints, webhooks, response codes, and common enum references.

<tip>

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.

</tip>

## Environment Configuration

<note>

Environment Domains

| Environment | Domain |
| --- | --- |
| Sandbox Environment | `https://sandbox-api.onerway.com/payout` |
| Production Environment | `https://api.onerway.com/payout` |

</note>

## Field Description

<note>

Required Field Rules

| Identifier | Description |
| --- | --- |
| `M` | Required field |
| `C` | Conditionally required field |
| `N` | Optional field |

</note>

## Payment Process (Four Phases)

### 1️⃣ Initialization & Pre-Setup Phase

<note>

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.

</note>

### 2️⃣ Payment Initiation Phase

<note>

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

</note>

### 3️⃣ Transaction Result Retrieval Phase

<note>

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)

</note>

### 4️⃣ Transaction Completion Phase

<note>

Determine Transaction Status:

- **✅ Success**
  - Retrieve electronic receipt: `POST /api/v1/txn/queryVoucher`
- **❌ Not Successful**
  - Query the failure reason;
  - Handle manually or reinitiate the payment.

</note>