Supply Platform Collection Info

Endpoint: POST /v2/gc/platform/collection-transactions/supplement

Description: Submit business-scenario and funds-nature compliance information (plus supporting documents) for a PLATFORM_COLLECTION-type collection transaction that is waiting on this supplement before it can be matched.

This page was generated from the backend Zod validation schema (src/global-collection/dto/supplyPlatformCollectionInfo.dto.ts and src/global-collection/dto/platform-collection-info/platform-collection-info.refinement.ts), cross-checked against a request example provided by the requester. It has not yet been reconciled against a captured real response or the Merchant Portal UI, unlike the other pages in this section — treat field-level details as a solid starting point that may still need a QA pass.

Two discrepancies between the example request below and the current backend validation code, worth confirming with the backend team before relying on this page:

• requestId is missing from the example, but the DTO declares it as a required field (string, max 32 chars, no default). Confirm whether it's actually optional in practice (e.g. auto-generated upstream) or whether the example simply omitted a field that should be supplied.

• The example's bizScenario/fundsNature pairing may not be valid: it uses bizScenario=ACQUIRING_INSTITUTION with fundsNature=GOODS_TRADE_PLATFORM, but platform-collection-info.refinement.ts maps GOODS_TRADE_PLATFORM (and SERVICE_TRADE) to the THIRD_PARTY_PAYMENT_RECEIVER group, not ACQUIRING_INSTITUTION — see the grouping table below. If the refinement code is current, this combination would be rejected with FUNDS_NATURE_CROSS_GROUP.

Request

The target collection transaction must already exist for the calling merchant, have orderType=PLATFORM_COLLECTION, and be in WAIT_MATCH status — otherwise the request fails with a 422 (COLLECTION_TRANSACTION_INVALID_STATUS_ERROR) or a not-found error.

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string(32)	Yes	Merchant-generated unique request ID. Used for idempotency. Not present in the example request below — see warning above.
orderId	string(32)	Yes	The target collection transaction's orderId (the PLATFORM_COLLECTION-type order awaiting this supplement).
bizScenario	string	Yes	Business scenario. Enum: ACQUIRING_INSTITUTION | THIRD_PARTY_PAYMENT_RECEIVER. Determines which fundsNature values are allowed — see below.
fundsNature	string	Yes	Nature of funds. Must belong to the group allowed for bizScenario (see table below) or the request fails with FUNDS_NATURE_CROSS_GROUP.
subMerchantId	string(32)	Conditional	Sub-merchant identifier, if operating on behalf of a sub-merchant. Optional in general; required when the merchant operates in PSP mode.
orderReferenceId	string(64)	No	Merchant-side reference number. Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
currency	string	No	ISO 4217 currency code. Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
amount	number	No	Transaction amount (must be positive). Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
buyerName	string(256)	No	Buyer's name. Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
buyerArea	string(3)	No	Buyer's country/region code — 3 uppercase letters, must be a supported ISO 3166-1 alpha-3 code. Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
buyerOfficialWebsite	string(256)	No	Buyer's official website (must be a valid http/https URL). Always optional — no conditional-required rule in the current validation.
attachmentsFiles	array (each string(256))	No	File paths of PI/CI/contract documents (from the File Upload API). Required when bizScenario=THIRD_PARTY_PAYMENT_RECEIVER.
website	string(256)	No	Independent-website URL (must be a valid http/https URL). Required when fundsNature is GOODS_TRADE_INDEPENDENT_WEBSITE or SERVICE_TRADE_INDEPENDENT_WEBSITE.
applicationName	string(512)	No	Application name. Required when fundsNature=APP_DEVELOPER.
applicationDownloadUrl	string(256)	No	Application download URL (must be a valid http/https URL). Required when fundsNature=APP_DEVELOPER.
withdrawalCertificateFiles	array (each string(256))	No	Withdrawal certificate file paths. Required when bizScenario=ACQUIRING_INSTITUTION.
accountOwnershipCertificateFiles	array (each string(256))	No	Account ownership certificate file paths. Required when bizScenario=ACQUIRING_INSTITUTION.
settlementDetailFiles	array (each string(256))	No	Settlement detail file paths. Required when bizScenario=ACQUIRING_INSTITUTION.
otherFiles	array (each string(256))	No	Other supplementary file paths. Always optional.
remark	string(512)	No	Free-text remark.

bizScenario / fundsNature grouping

fundsNature must be selected from the group that matches bizScenario, or the request fails with FUNDS_NATURE_CROSS_GROUP:

bizScenario	Allowed fundsNature values
ACQUIRING_INSTITUTION	GOODS_TRADE_INDEPENDENT_WEBSITE, SERVICE_TRADE_INDEPENDENT_WEBSITE, APP_DEVELOPER
THIRD_PARTY_PAYMENT_RECEIVER	GOODS_TRADE_PLATFORM, SERVICE_TRADE

Request sample

Example provided by the requester (see warning above — requestId is missing and the bizScenario/fundsNature pairing may not validate as-is):

curl --location 'https://{base_url_openapi}/v2/gc/platform/collection-transactions/supplement' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
  "orderId": "785980571014000073",
  "bizScenario": "ACQUIRING_INSTITUTION",
  "fundsNature": "GOODS_TRADE_PLATFORM",
  "subMerchantId": "10000002",
  "orderReferenceId": "2026-08-28T09:23:12.843Z",
  "currency": "USD",
  "amount": 1000,
  "buyerName": "John Buyer",
  "buyerArea": "USA",
  "buyerOfficialWebsite": "https://buyer.example.com",
  "attachmentsFiles": ["1785291230160-document.jpg"],
  "website": "https://merchant.example.com",
  "applicationName": "MyApp",
  "applicationDownloadUrl": "https://apps.example.com/app",
  "withdrawalCertificateFiles": ["1785291230160-document.jpg"],
  "accountOwnershipCertificateFiles": ["1785291230160-document.jpg"],
  "settlementDetailFiles": ["1785291230160-document.jpg"],
  "otherFiles": ["1785291230160-document.jpg"],
  "remark": "note"
}'

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
data	object	Persisted platform-collection supplement record.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier (not present on every response).

data object fields:

Field Name	Type	Description
id	string	Internal supplement record identifier.
merchantId	string	Merchant identifier.
subMerchantId	string	Echoes the submitted subMerchantId, if any.
requestId	string	Echoes the merchant-supplied requestId.
collectionTransactionId	string	Internal ID of the collection transaction this supplement was submitted for.
orderId	string	Echoes the submitted orderId.
bizScenario	string	Echoes the submitted bizScenario.
fundsNature	string	Echoes the submitted fundsNature.
response	object	Raw response payload from the upstream connector (shape varies); may include a data.supplyInfoId used internally to correlate the submission.
createdAt	date string	Record creation timestamp.

No real captured response sample is available yet for this endpoint. On success, the underlying collection transaction transitions to PROCESSING status. Poll Get Detail Collection Order to track the outcome.

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

• orderId must reference an existing PLATFORM_COLLECTION-type collection transaction in WAIT_MATCH status for the calling merchant.

• All file-path fields (attachmentsFiles, withdrawalCertificateFiles, accountOwnershipCertificateFiles, settlementDetailFiles, otherFiles) expect values returned by the File Upload API (POST /v2/gc/files/upload).