> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/payout-requests/api-create-payout-request.md).

# Create Payout Request

#### Endpoint: POST /v2/gc/payment-requests

{% hint style="info" %}
This doc section is titled "Payout Request" for consistency with the rest of this doc set, but every URL is under the `payment-requests` path.
{% endhint %}

#### Description: Initiate a payout or remittance to a registered beneficiary, optionally using a locked FX rate token from the Payout Inquiry API.

{% hint style="info" %}
**Prerequisite:** You must [register a beneficiary](/docs/global/global-collections/integration/beneficiaries/api-register-beneficiary.md) before creating a payout request. Either provide a `beneficiaryId` from a previously registered beneficiary, or supply `beneficiaryAccountName` and `beneficiaryAccountNumber` for inline beneficiary details.
{% endhint %}

## Request

#### Request Body Field Descriptions (JSON)

| Field Name               | Type   | Required | Description                                                                                                                                                            |
| ------------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId                | string | Yes      | Unique request ID (*UUID recommended*) used for idempotency.                                                                                                           |
| amount                   | string | Yes      | Payout amount in `payoutCurrency` (decimal string, e.g. `"23.57"`).                                                                                                    |
| payoutCurrency           | string | Yes      | ISO 4217 currency code of the payout (e.g. `USD`, `EUR`).                                                                                                              |
| payoutType               | string | Yes      | Payout channel type. Enum: `DOMESTIC_PAYMENT` \| `OVERSEA_PAYMENT` \| `WITHDRAW` \| `DOMESTIC_PAYMENT_FX`.                                                             |
| subMerchantId            | string | Yes      | Sub-merchant identifier. Provide when submitting the payout on behalf of a sub-merchant.                                                                               |
| beneficiaryId            | string | Yes      | Registered beneficiary ID returned by the Create Beneficiary API. Provide either this field or `beneficiaryAccountName` + `beneficiaryAccountNumber`.                  |
| beneficiaryAccountName   | string | No       | Full name of the beneficiary's bank account. Provide either `beneficiaryAccountName` + `beneficiaryAccountNumber`, or `beneficiaryId` — not both.                      |
| beneficiaryAccountNumber | string | No       | Beneficiary's bank account number. Required together with `beneficiaryAccountName` when `beneficiaryId` is not provided.                                               |
| receiveCurrency          | string | No       | ISO 4217 currency code that the beneficiary will receive (for cross-currency payouts).                                                                                 |
| clearingType             | string | No       | Clearing method. Enum: `AUTO` \| `SWIFT` \| `LOCAL`.                                                                                                                   |
| swiftCode                | string | No       | SWIFT/BIC code of the beneficiary's bank (required for SWIFT clearing).                                                                                                |
| feeBear                  | string | No       | Fee-bearing arrangement. Enum: `SHA` (shared) \| `OUR` (sender) \| `BEN` (beneficiary).                                                                                |
| feeChargeMode            | string | No       | Remittance fee (system handling fee) collection method. Enum: `OUT` (external deduction from account balance) \| `IN` (internal deduction from payment amount).        |
| useCode                  | string | No       | Remittance purpose code (e.g. `GOODSTRADE`, `SOFTWARE`, `ADVERTISEMENT`).                                                                                              |
| remitType                | string | No       | Remittance speed. Enum: `SPEED` \| `NORMAL` \| `FAST`.                                                                                                                 |
| tradeSide                | string | No       | Trade direction used with FX token. Enum: `CUSTOMER_SELL` \| `CUSTOMER_BUY`.                                                                                           |
| pobo                     | string | No       | Pay-on-behalf-of flag. Enum: `N` (default) \| `Y`.                                                                                                                     |
| payerId                  | string | No       | Identifier of the payer when `pobo=Y`.                                                                                                                                 |
| remark                   | string | No       | Free-text remark or payment reference attached to the payout.                                                                                                          |
| webhookUrl               | string | No       | Callback URL to receive the `PAYMENT_INITIAL`/`PAYMENT_RESULT` webhook notifications when the payout outcome is available.                                             |
| remitPurpose             | string | No       | High-level remittance purpose. Enum: `GOODSTRADE` \| `SERVICETRADE` \| `OTHERS`.                                                                                       |
| token                    | string | No       | FX rate lock token obtained from the Payout Inquiry API. Required for cross-currency payouts where a rate has been pre-locked.                                         |
| originalRequestId        | string | No       | The `requestId` of a previous payout request; used for supplementary or correction submissions.                                                                        |
| clearingNetwork          | string | No       | Clearing network override. Enum: `UNIONPAY` \| `NCPS`.                                                                                                                 |
| connectionMode           | string | No       | Connection mode for specific payment rails.                                                                                                                            |
| detailPath               | string | No       | File reference path (from the File Upload API, `POST /v2/gc/files/upload`) pointing to a batch transaction detail file. Required for `DOMESTIC_PAYMENT` batch payouts. |

#### Field details and conditional rules

{% hint style="info" %}
The fields below have scenario-based rules. Validate `payoutType`, `payoutCurrency`, and settlement path fields together before submitting.
{% endhint %}

<details>

<summary><strong><code>payoutCurrency</code> (string(8), required)</strong></summary>

* Meaning: Currency used for merchant payout.
* Example: `CNH`

Rules by `payoutType`:

1. `payoutType=OVERSEA_PAYMENT`: supported currencies are non-`CNY` currencies.
2. `payoutType=DOMESTIC_PAYMENT_FX`: supported currencies are `CNY`, `REFUND` (refund-only CNY user), and other foreign currencies.
3. `payoutType=DOMESTIC_PAYMENT`: supported currencies are `CNH`, `CNY`, `REFUND` (refund-only CNY user).

</details>

<details>

<summary><strong><code>amount</code> (string(18), required)</strong></summary>

* Meaning: Payout or receive amount, depending on scenario.
* Example: `23.57`

Scenario interpretation:

1. `payoutType=OVERSEA_PAYMENT` and `tradeSide=CUSTOMER_SELL`: `amount` is payout amount.
2. `payoutType=OVERSEA_PAYMENT` and `tradeSide=CUSTOMER_BUY`: `amount` is receive amount.
3. `payoutType=DOMESTIC_PAYMENT_FX`: `amount` is payout amount.
4. `payoutType=DOMESTIC_PAYMENT`: `amount` is the total of payout amounts in the detail file.

</details>

<details>

<summary><strong><code>payoutType</code> (string(32), conditionally required)</strong></summary>

* Meaning: Payout type; domestic and overseas types can be used for withdrawal capabilities.
* Required condition: required when `payoutType` is not `DOMESTIC_PAYMENT` (default).

| Enum value            | Meaning                          |
| --------------------- | -------------------------------- |
| `DOMESTIC_PAYMENT`    | Domestic payment (default)       |
| `OVERSEA_PAYMENT`     | Overseas payment                 |
| `DOMESTIC_PAYMENT_FX` | Trade settlement conversion mode |
| `WITHDRAW`            | Withdrawal                       |

</details>

<details>

<summary><strong><code>receiveCurrency</code> (string(8), optional)</strong></summary>

* Meaning: Currency received by the beneficiary.
* Example: `CNY`

Rules by `payoutType`:

1. `payoutType=DOMESTIC_PAYMENT` or `payoutType=DOMESTIC_PAYMENT_FX`: do not provide this field.
2. `payoutType=OVERSEA_PAYMENT` or `payoutType=WITHDRAW`: pass the value from `accountCurrency` in the beneficiary registration data.

</details>

<details>

<summary><strong><code>detailPath</code> (string(256), conditionally required)</strong></summary>

* Meaning: Path returned by the File Upload API for payout detail file.
* Required condition: required when `payoutType=DOMESTIC_PAYMENT`.
* Source: upload file via `POST /v2/gc/files/upload`, then pass returned `path` as `detailPath`.
* File templates: domestic payment template and salary/family-support payment template.

</details>

<details>

<summary><strong><code>useCode</code> (string(32), conditionally required)</strong></summary>

* Meaning: Payout purpose code.
* Required condition: required when `payoutType=DOMESTIC_PAYMENT`.

| Enum value           | Meaning                                   |
| -------------------- | ----------------------------------------- |
| `GOODSTRADE`         | Goods trade                               |
| `GENERALTRADE`       | General trade (goods-arrived)             |
| `SOFTWARE`           | Software service                          |
| `ADVERTISEMENT`      | Advertising service                       |
| `TRANSPORT2`         | International transport (export sea)      |
| `TRANSPORT3`         | International transport (export air)      |
| `TRANSPORT5`         | International transport (export land)     |
| `TRANSPORT7`         | International transport (postal delivery) |
| `TRAVEL`             | Personal travel                           |
| `TRAVEL2`            | Business travel                           |
| `SALARY`             | Salary                                    |
| `FAMILYALLOWANCE`    | Family support                            |
| `PLANETICKET`        | Flight ticket                             |
| `HOTELACCOMMODATION` | Hotel accommodation                       |

</details>

<details>

<summary><strong><code>remitType</code> (string(32), conditionally required)</strong></summary>

* Meaning: Distribution speed/type.

Required conditions:

1. Required when `payoutType=DOMESTIC_PAYMENT`.
2. Required when `payoutType=DOMESTIC_PAYMENT_FX`.

Enum support by `payoutType`:

* `DOMESTIC_PAYMENT`: `SPEED`, `NORMAL` (default), `FAST`
* `DOMESTIC_PAYMENT_FX`: `SPEED`, `NORMAL`

</details>

<details>

<summary><strong><code>clearingType</code> (string(8), conditionally required)</strong></summary>

* Meaning: Clearing path type.
* Note: not required in `DOMESTIC_PAYMENT_FX` mode.
* Required condition: required when `payoutType=OVERSEA_PAYMENT` or `payoutType=WITHDRAW`.

| Enum value | Meaning              |
| ---------- | -------------------- |
| `AUTO`     | Auto route (default) |
| `SWIFT`    | SWIFT remittance     |
| `LOCAL`    | Local distribution   |

</details>

<details>

<summary><strong><code>tradeSide</code> (string(15), conditionally required)</strong></summary>

* Meaning: Trade direction for overseas cross-currency conversion logic.
* Default: `CUSTOMER_SELL`.
* Required condition: provide when `payoutType=OVERSEA_PAYMENT` and payout is based on receive-amount conversion.

| Enum value      | Meaning                         |
| --------------- | ------------------------------- |
| `CUSTOMER_SELL` | Convert based on payout amount  |
| `CUSTOMER_BUY`  | Convert based on receive amount |

</details>

<details>

<summary><strong><code>pobo</code> (string(8), optional)</strong></summary>

* Meaning: Same-name payout flag.
* Usage: For overseas payouts, provide this when you need to use a designated payer name.

| Enum value | Meaning                                    |
| ---------- | ------------------------------------------ |
| `N`        | Use NeoPay/Globebill payer name (default). |
| `Y`        | Use merchant name as payer.                |

</details>

<details>

<summary><strong><code>beneficiaryAccountName</code> (string(256), conditionally required)</strong></summary>

* Meaning: Beneficiary bank account holder name.
* Required condition: required when `payoutType=OVERSEA_PAYMENT` or `payoutType=WITHDRAW`.

</details>

<details>

<summary><strong><code>beneficiaryAccountNumber</code> (string(256), conditionally required)</strong></summary>

* Meaning: Beneficiary bank account number.
* Required condition: required when `payoutType` is `OVERSEA_PAYMENT`, `WITHDRAW`, or `DOMESTIC_PAYMENT_FX`.

</details>

<details>

<summary><strong><code>beneficiaryId</code> (string(64), conditionally required)</strong></summary>

* Meaning: Beneficiary identifier.
* Required condition: when `payoutType=OVERSEA_PAYMENT`, or when `payoutType=WITHDRAW` and `payoutCurrency!=CNY`, provide either:
  * `beneficiaryId`, or
  * `beneficiaryAccountName` + `beneficiaryAccountNumber` + `clearingType`.

</details>

<details>

<summary><strong><code>swiftCode</code> (string(256), conditionally required)</strong></summary>

* Meaning: SWIFT code of beneficiary account bank.
* Required condition: required when `payoutType=OVERSEA_PAYMENT`.

</details>

<details>

<summary><strong><code>feeBear</code> (string(4), conditionally required)</strong></summary>

* Meaning: Remittance fee-bearing method.
* Required condition: required when `clearingType=SWIFT`.

Supported values:

* For `clearingType=SWIFT`: `SHA` (shared), `OUR` (sender).
* For `payoutType=DOMESTIC_PAYMENT_FX`: `OUR` (outer deduction, default), `BEN` (inner deduction).

</details>

<details>

<summary><strong><code>feeChargeMode</code> (string(4), optional)</strong></summary>

* Meaning: Remittance fee (system handling fee) collection method.
* Example: `OUT`

Supported values:

| Enum value | Description                                                                                                                                              |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OUT`      | **External deduction** — Fees are deducted from the account balance separately from the payout amount.                                                   |
| `IN`       | **Internal deduction** — Fees are deducted from the payment amount itself. **Note:** Fixed-amount arrival payouts do not support internal fee deduction. |

**Important:** When using `IN` (internal deduction), the beneficiary receives the payout amount minus the system handling fee. This mode is **not supported** for fixed-amount-to-arrive scenarios.

</details>

<details>

<summary><strong><code>remitPurpose</code> (string(32), conditionally required)</strong></summary>

* Meaning: Payout purpose for overseas remittance.
* Required condition: required when `payoutType=OVERSEA_PAYMENT`.

| Enum value     | Meaning       |
| -------------- | ------------- |
| `GOODSTRADE`   | Goods trade   |
| `SERVICETRADE` | Service trade |
| `OTHERS`       | Others        |

</details>

<details>

<summary><strong><code>clearingNetwork</code> (string(16), conditionally required)</strong></summary>

* Meaning: Clearing network.
* Required condition: required when `connectionMode=DISCONNECT`.
* Example: `UNIONPAY`

| Enum value | Meaning             |
| ---------- | ------------------- |
| `UNIONPAY` | UnionPay network    |
| `NCPS`     | Netcom/NCPS network |

</details>

#### Request sample

```json
{
  "requestId": "{{$guid}}",
  "payoutCurrency": "USD",
  "amount": "20",
  "payoutType": "OVERSEA_PAYMENT",
  "subMerchantId": "10000002",
  "beneficiaryId": "785561080533000005",
  "tradeSide": "CUSTOMER_SELL",
  "feeBear": "SHA",
  "remitPurpose": "GOODSTRADE",
  "remark": "note",
  "token": "785740956796000019",
  "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76"
}
```

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| code          | number | Response code.                    |
| data          | object | Payout request submission result. |
| message       | string | Response message.                 |
| neoResponseId | string | Unique NeoX response identifier.  |

{% hint style="info" %}
The identifier field in `data` is `id`.
{% endhint %}

#### `data` object fields:

| Field Name | Type   | Description                                                                                          |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| id         | string | NeoX identifier for this payout request. Use this to track the payout via Get Detail Payout Request. |
| requestId  | string | Echo of the `requestId` submitted in the request.                                                    |
| serialNum  | string | Platform serial number assigned to this payout transaction.                                          |
| status     | string | Initial processing status. Fixed value on create: `PROCESSING`.                                      |

#### Response sample

```json
{
  "code": 1,
  "data": {
    "id": "943dc605e0f24b86a3ccd447b4208e63",
    "requestId": "1785740964957",
    "serialNum": "785740956796000019",
    "status": "PROCESSING"
  },
  "message": "Successful",
  "neoResponseId": "96dd2a31-1a17-42fc-9ed2-7682a2edc6af"
}
```

{% hint style="danger" %}
**FX-lock gotcha**: for a cross-currency payout (`payoutCurrency` different from the beneficiary's `accountCurrency`), this call fails with `INVALID TOKEN` unless you first call [Payout Inquiry](/docs/global/global-collections/integration/payout-requests/api-payout-inquiry.md) to lock a rate and pass its `token` here (or one is still cached server-side from a recent inquiry for the same sub-merchant/beneficiary/amount). Same-currency payouts don't need this step.
{% endhint %}

### Notes

* Requires Bearer token in the Authorization header.
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* Use a unique `requestId` for each request to avoid duplicate payout submissions.
* Provide either `beneficiaryId` (preferred), or `beneficiaryAccountName` together with `beneficiaryAccountNumber` — not both simultaneously.
* For cross-currency payouts where a rate has been pre-locked, pass the `token` returned by the Payout Inquiry API before it expires.
* The payout outcome is delivered asynchronously via the `PAYMENT_INITIAL`/`PAYMENT_RESULT` webhooks to the `webhookUrl` supplied in the request. Poll the result using [Get Detail Payout Request](/docs/global/global-collections/integration/payout-requests/get-detail-payout-request.md) (`GET /v2/gc/payment-requests`).
* The `detailPath` field must reference a `path` value returned by the File Upload API (`POST /v2/gc/files/upload`).