Supplement Payer Information

Endpoint: POST /v2/gc/collection-orders/{collectionOrderId}/payer-information

Description: Provide payer details for an incoming collection order that arrived without identifiable payer information.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
payerAccountName	string	Yes	Full name of the account holder who sent the funds.
payerAccountNum	string	Yes	Account number of the party who sent the funds (e.g. IBAN or SWIFT account number).
paymentProofList	array	Yes	List of payment proof document file paths. Each element is a path returned by the File Upload API (POST /v2/gc/files/upload).
subMerchantId	string	No	Sub-merchant identifier. Required when the collection order belongs to a sub-merchant account.
swiftCode	string	No	SWIFT/BIC code of the payer's bank.
remark	string	No	Free-text remark or additional context about the payer or the payment.

Request sample

{
  "requestId": "e8f9a0b1-2345-4cde-f678-901234567890",
  "payerAccountName": "Global Retail GmbH",
  "payerAccountNum": "DE89370400440532013000",
  "paymentProofList": [
    "gpt/PAYEEINFO/20240302/proof_e8f9a0b1.pdf"
  ],
  "swiftCode": "DEUTDEDBXXX",
  "remark": "Wire transfer reference PI-2024-00182"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	Updated collection order payer details.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

data object fields:

Field Name	Type	Description
merchantId	string	NeoX merchant identifier for the account that received the funds.
vaNumber	string	Virtual account number that received the incoming funds.
payeeAccountName	string	Name of the payee (merchant) account that received the funds.
payeeAccountNum	string	Account number of the payee (merchant) account.
amount	number	Amount of the incoming collection order.
payerAccountName	string	Payer account name as recorded after this supplement submission.
payerAccountNum	string	Payer account number as recorded after this supplement submission.
swiftCode	string	SWIFT/BIC code of the payer's bank as recorded after this supplement submission.
paymentProofList	array	List of payment proof file paths submitted with this supplement.

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "merchantId": "MC-00012345",
    "vaNumber": "HK82000000012345678901",
    "payeeAccountName": "Acme Trading Limited",
    "payeeAccountNum": "HK82000000012345678901",
    "amount": 15800.00,
    "payerAccountName": "Global Retail GmbH",
    "payerAccountNum": "DE89370400440532013000",
    "swiftCode": "DEUTDEDBXXX",
    "paymentProofList": [
      "gpt/PAYEEINFO/20240302/proof_e8f9a0b1.pdf"
    ]
  },
  "message": "Successful",
  "neoResponseId": "c3d4e5f6-7890-4abc-1234-567890abcdef"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/collection-orders/{collectionOrderId}/payer-information" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "e8f9a0b1-2345-4cde-f678-901234567890",
    "payerAccountName": "Global Retail GmbH",
    "payerAccountNum": "DE89370400440532013000",
    "paymentProofList": [
      "gpt/PAYEEINFO/20240302/proof_e8f9a0b1.pdf"
    ],
    "swiftCode": "DEUTDEDBXXX",
    "remark": "Wire transfer reference PI-2024-00182"
  }'

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

• The request body must be in JSON format.

• Replace {collectionOrderId} with the actual NeoX collection order identifier. This value is delivered via the COLLECTION webhook.

• Call this endpoint when the COLLECTION webhook indicates that payer information is missing for an incoming payment.

• All paymentProofList entries must be path values returned by the File Upload API (POST /v2/gc/files/upload). Upload proof documents using bizType=PAYEEINFO before calling this endpoint.

• The result of this supplement is delivered via the COLLECTION webhook and can also be polled using the Get Detail Collection Order API (GET /v2/gc/collection-orders/{collectionOrderId}).