> 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/collections/api-supply-platform-collection-info.md).

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

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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`.
  {% endhint %}

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

<details>

<summary><strong>bizScenario / fundsNature grouping</strong></summary>

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

</details>

#### Request sample

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

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

{% hint style="info" %}
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](/docs/global/global-collections/integration/collections/get-detail-collection-order.md) to track the outcome.
{% endhint %}

### 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`).