> 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-supplement-payer-information.md).

# 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

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

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

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