Create Payout Request

Endpoint: POST /v2/gc/payment-requests

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.

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(32)	Yes	Unique request ID (UUID recommended) used for idempotency.
amount	string(18)	Yes	Payout amount in payoutCurrency (decimal string, e.g. "23.57").
payoutCurrency	string(8)	Yes	ISO 4217 currency code of the payout (e.g. USD, EUR).
payoutType	string	No	Payout channel type. Enum: ``OVERSEA_PAYMENT|WITHDRAW`.
subMerchantId	string(32)	Conditional	Sub-merchant identifier. Provide when submitting the payout on behalf of a sub-merchant. Optional in general; required when the merchant operates in PSP mode.
beneficiaryId	string(64)	No	Registered beneficiary ID returned by the Create Beneficiary API. Provide either this field or beneficiaryAccountName + beneficiaryAccountNumber.
beneficiaryAccountName	string(256)	No	Full name of the beneficiary's bank account. Provide either beneficiaryAccountName + beneficiaryAccountNumber, or beneficiaryId — not both.
beneficiaryAccountNumber	string(256)	No	Beneficiary's bank account number. Required together with beneficiaryAccountName when beneficiaryId is not provided.
receiveCurrency	string(8)	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(256)	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. Default NORMAL.
tradeSide	string	No	Trade direction used with FX token. Enum: CUSTOMER_SELL | CUSTOMER_BUY. Default CUSTOMER_SELL.
pobo	string	No	Pay-on-behalf-of flag. Enum: N (default) | Y.
payerId	string(128)	No	Identifier of the payer when pobo=Y.
remark	string(105)	No	Free-text remark or payment reference attached to the payout.
webhookUrl	string(256)	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(32)	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(32)	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(256)	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.
purchaseCategory	string	No	Purchase category of the goods being paid for. Enum: CLOTHES_SHOES | DAILY_SUPPLIES_AND_COSMETICS | ELECTRONICS_AND_HOME_APPLIANCES | TOYS_KIDS_BABIES. Required when payoutType=OVERSEA_PAYMENT and the beneficiary account is an Alipay wallet.
notifyUrl	string(256)	No	Async notification callback URL (must be a valid http/https URL).
sourceType	string	No	Request source channel. Enum: PORTAL | API.

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

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

The identifier field in data is id.

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

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

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

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 (GET /v2/gc/payment-requests).

• The detailPath field must reference a path value returned by the File Upload API (POST /v2/gc/files/upload).