> 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/security-method.md).

# Security Method

## 1. Protocol & authentication

* All APIs provided by NeoX are **RESTful**.
* Authentication mechanism: **OAuth 2.0 Bearer Token**.
* How to do it: call the [API authenPlatform](/docs/global/global-collections/integration/api-authenplatform.md) endpoint to obtain an `access_token`, then pass it in the `Authorization` header of every other call:

```
Authorization: Bearer <access_token>
```

## 2. Base URL

Every Global Collections endpoint is documented relative to a base URL placeholder:

```
https://{base_url_openapi}/v2/gc/<path>
```

`{base_url_openapi}` is provided by NeoX per environment (sandbox / production). All Global Collections endpoints live under the **`/v2/gc/`** namespace.

## 3. Standard request headers

| Header          | Required | Description                                                    |
| --------------- | -------- | -------------------------------------------------------------- |
| Authorization   | Yes      | `Bearer <access_token>` from the authenPlatform API.           |
| Content-Type    | Yes      | `application/json` (or `multipart/form-data` for file upload). |
| Accept-Language | No       | Response language. Supported values: `vi`, `en`. Default `en`. |

## 4. Standard response envelope

Every Global Collections API returns the same envelope. Endpoint-specific data is always carried inside `data`.

| Field         | Type   | Description                                                                                        |
| ------------- | ------ | -------------------------------------------------------------------------------------------------- |
| code          | number | Response code. Refer to [Error Codes](/docs/global/global-collections/integration/error-codes.md). |
| data          | object | Endpoint-specific payload.                                                                         |
| message       | string | Response message.                                                                                  |
| neoResponseId | string | Unique NeoX response identifier.                                                                   |

A successful response uses `code = 1`, `message = "Successful"`.

## 5. Idempotency

* Every create/initiate request carries a merchant-generated `requestId` (UUID recommended).
* NeoX de-duplicates on `requestId`: re-sending the same `requestId` returns the result of the original operation instead of creating a duplicate.
* Always generate a fresh `requestId` for a genuinely new operation, and reuse the same `requestId` when retrying or polling the same operation.

## 6. Webhook verification

Asynchronous events are delivered as webhooks (see [Event Notification](/docs/global/global-collections/integration/event-notification.md)). Each webhook payload includes a `secureHash` field that the Merchant must verify with the **Secret Key** issued for your merchant account before trusting the payload. See [Event Notification](/docs/global/global-collections/integration/event-notification.md#configuration) for how webhook delivery is configured — there is no Merchant Portal screen for this.