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 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.
state	number	State of the response.
data	object	Endpoint-specific payload.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

A successful response uses code = 1, state = 2, 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). Each webhook payload includes a secureHash field that the Merchant must verify with the Secret Key configured on the Merchant Portal before trusting the payload.