> 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/payout-requests
#### 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 | No | Payout channel type. Enum: `DOMESTIC_PAYMENT` \| `OVERSEA_PAYMENT` \| `WITHDRAW` \| `DOMESTIC_PAYMENT_FX`. |
| 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. |
| beneficiaryId | string | No | Registered beneficiary ID returned by the Create Beneficiary API. Provide either this field or `beneficiaryAccountName` + `beneficiaryAccountNumber`. |
| 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. |
| notifyUrl | string | No | Callback URL to receive the `PAYOUT` webhook notification 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 %}
payoutCurrency (string(8), required)
* 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).
amount (string(18), required)
* 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.
payoutType (string(32), conditionally required)
* 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 |
receiveCurrency (string(8), optional)
* 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.
detailPath (string(256), conditionally required)
* 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.
useCode (string(32), conditionally required)
* 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 |
remitType (string(32), conditionally required)
* 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`
clearingType (string(8), conditionally required)
* 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 |
tradeSide (string(15), conditionally required)
* 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 |
pobo (string(8), optional)
* 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. |
beneficiaryAccountName (string(256), conditionally required)
* Meaning: Beneficiary bank account holder name.
* Required condition: required when `payoutType=OVERSEA_PAYMENT` or `payoutType=WITHDRAW`.
beneficiaryAccountNumber (string(256), conditionally required)
* Meaning: Beneficiary bank account number.
* Required condition: required when `payoutType` is `OVERSEA_PAYMENT`, `WITHDRAW`, or `DOMESTIC_PAYMENT_FX`.
beneficiaryId (string(64), conditionally required)
* Meaning: Beneficiary identifier.
* Required condition: when `payoutType=OVERSEA_PAYMENT`, or when `payoutType=WITHDRAW` and `payoutCurrency!=CNY`, provide either:
* `beneficiaryId`, or
* `beneficiaryAccountName` + `beneficiaryAccountNumber` + `clearingType`.
swiftCode (string(256), conditionally required)
* Meaning: SWIFT code of beneficiary account bank.
* Required condition: required when `payoutType=OVERSEA_PAYMENT`.
feeBear (string(4), conditionally required)
* 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).
feeChargeMode (string(4), optional)
* 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.
remitPurpose (string(32), conditionally required)
* Meaning: Payout purpose for overseas remittance.
* Required condition: required when `payoutType=OVERSEA_PAYMENT`.
| Enum value | Meaning |
| -------------- | ------------- |
| `GOODSTRADE` | Goods trade |
| `SERVICETRADE` | Service trade |
| `OTHERS` | Others |
clearingNetwork (string(16), conditionally required)
* Meaning: Clearing network.
* Required condition: required when `connectionMode=DISCONNECT`.
* Example: `UNIONPAY`
| Enum value | Meaning |
| ---------- | ------------------- |
| `UNIONPAY` | UnionPay network |
| `NCPS` | Netcom/NCPS network |
#### Request sample
```json
{
"requestId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
"amount": "5000.00",
"payoutCurrency": "USD",
"payoutType": "OVERSEA_PAYMENT",
"beneficiaryId": "SUP-20240801-00098765",
"clearingType": "SWIFT",
"swiftCode": "HSBCHKHH",
"feeBear": "SHA",
"remitType": "NORMAL",
"remitPurpose": "GOODSTRADE",
"token": "INQ-TOKEN-7f3a9c2b-ee41-4d8e-91fa-0012ab34cd56",
"notifyUrl": "https://merchant.example.com/webhooks/payout",
"remark": "Invoice INV-2024-08001"
}
```
### Response
#### Response Field Descriptions
| Field Name | Type | Description |
| ------------- | ------ | --------------------------------- |
| code | number | Response code. |
| state | number | State of the response. |
| data | object | Payout request submission result. |
| message | string | Response message. |
| neoResponseId | string | Unique NeoX response identifier. |
#### `data` object fields:
| Field Name | Type | Description |
| --------------- | ------ | ---------------------------------------------------------------------- |
| payoutRequestId | string | NeoX identifier for this payout request. Use this to track the payout. |
| 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 of the payout request (e.g. `PROCESSING`). |
#### Response sample
```json
{
"code": 1,
"state": 2,
"data": {
"payoutRequestId": "PO-20240815-00112233",
"requestId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
"serialNum": "SN2024081500112233",
"status": "PROCESSING"
},
"message": "Successful",
"neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69"
}
```
## Example cURL
```bash
curl -X POST "https://{base_url_openapi}/v2/gc/payout-requests" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "Accept-Language: en" \
-d '{
"requestId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
"amount": "5000.00",
"payoutCurrency": "USD",
"payoutType": "OVERSEA_PAYMENT",
"beneficiaryId": "SUP-20240801-00098765",
"clearingType": "SWIFT",
"swiftCode": "HSBCHKHH",
"feeBear": "SHA",
"remitType": "NORMAL",
"remitPurpose": "GOODSTRADE",
"token": "INQ-TOKEN-7f3a9c2b-ee41-4d8e-91fa-0012ab34cd56",
"notifyUrl": "https://merchant.example.com/webhooks/payout",
"remark": "Invoice INV-2024-08001"
}'
```
### 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 `PAYOUT` webhook to the `notifyUrl` supplied in the request. Poll the result using the Get Detail Payout Request API (`GET /v2/gc/payout-requests/{requestId}`).
* The `detailPath` field must reference a `path` value returned by the File Upload API (`POST /v2/gc/files/upload`).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.neox.vn/docs/global/global-collections/integration/payout-requests/api-create-payout-request.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.