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.

Prerequisite: You must register a beneficiary before creating a payout request. Either provide a beneficiaryId from a previously registered beneficiary, or supply beneficiaryAccountName and beneficiaryAccountNumber for inline beneficiary details.

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

The fields below have scenario-based rules. Validate payoutType, payoutCurrency, and settlement path fields together before submitting.

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

{
  "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

{
  "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

curl -X POST "https://{base_url_openapi}/v2/gc/payout-requests" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -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).