# APIs

Structure of Payment Request: *<mark style="color:blue;"><https://neox-> domain?\[key1=value]&\[key2=value]&...</mark>* (Table below is the description of key and value, no ordering required)

<table><thead><tr><th width="210">Key</th><th width="92" data-type="checkbox">Require</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>neo_MerchantCode</td><td>true</td><td>String</td><td>The merchant representative code that provided by NeoX</td></tr><tr><td>neo_Currency</td><td>true</td><td>String</td><td>Transaction currency, default is “VND”</td></tr><tr><td>neo_Locale</td><td>true</td><td>String</td><td>The language used on payment page, support: “vi”, “en”</td></tr><tr><td>neo_Version</td><td>true</td><td>String</td><td>Payment gateway version, default is “1”</td></tr><tr><td>neo_Command</td><td>true</td><td>String</td><td>Default is “PAY”</td></tr><tr><td>neo_Amount</td><td>true</td><td>Number</td><td>Order amount</td></tr><tr><td>neo_MerchantTxnID</td><td>true</td><td>String</td><td>Transaction id of merchant, unique on merchant’s system and on each request, accept only characters, numerics and list of symbols: “- ”, “_”. Max 36 characters</td></tr><tr><td>neo_OrderID</td><td>true</td><td>String</td><td>Order id of transaction, accept only characters, numerics and list of symbols: “-”, “_”. This field can be duplicate on requests. Max 36 characters</td></tr><tr><td>neo_OrderInfo</td><td>true</td><td>String</td><td>Order infomation, max length 256.</td></tr><tr><td>neo_ReturnURL</td><td>true</td><td>String</td><td>NeoX will redirect to this URL after transaction completed</td></tr><tr><td>neo_ExpiresIn</td><td>false</td><td>Number</td><td>Expiration time (in seconds) of Payment Request. Default is 86400 seconds.</td></tr><tr><td>neo_PaymentMethod</td><td>false</td><td>Array/<br>String</td><td><p>A list of below values:<br><strong>WALLET</strong>: pay with NeoX e-wallet<br><strong>ATM</strong>: pay with domestic card<br><strong>CC</strong>: pay with international card<br><strong>QR</strong>: pay with QR Code<br>This param allows merchants to display one or more payment methods on the payment page. If not set, all methods will be shown.</p><p><em>Incase GET(http method), this field separeted by the commas</em></p></td></tr><tr><td>neo_CustomerPhone</td><td>false</td><td>String</td><td>Customer phone</td></tr><tr><td>neo_CustomerEmail</td><td>false</td><td>String</td><td>Customer email</td></tr><tr><td>neo_CustomerID</td><td>false</td><td>String</td><td>Merchant’s customer id</td></tr><tr><td>neo_CustomerIpAddress</td><td>false</td><td>String</td><td>Customer IP address</td></tr><tr><td>neo_TokenCreate</td><td>false</td><td>Boolean</td><td>Returning payment token after international card payment.<a data-mention href="/pages/0vzAzweaFEOa7Fm9XuIU">/pages/0vzAzweaFEOa7Fm9XuIU</a></td></tr><tr><td>neo_IframeCreate</td><td>false</td><td>Boolean</td><td>Returning redirect payment link as a simple payment for HTML &#x3C;iFrame/> src</td></tr><tr><td>neo_SecureHash</td><td>true</td><td>String</td><td><p>A = all above parameters sorted in alphabetical order</p><p>B = merchant’s Secret Key(provided by NeoX)</p><p>This value = hashed string(using SHA256) of A + B</p></td></tr><tr><td>neo_ExtData</td><td>false</td><td>Object</td><td><p>Bill extra data, eg: sub order info, platform, webUrl..., with schema (view example for more details): </p><pre><code>{
    "orderData": {
        "payItems": [
            {
                "orderId": String,
                "desc": String,
                "price": Number,
                "extraInfo": Object
            }
        ]
    }
}
</code></pre></td></tr></tbody></table>

Incase of POST(http method), system will response below data:

<table><thead><tr><th width="209">Key</th><th width="98.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>neo_ResponseCode</td><td>Number</td><td><p>0: Successful.</p><p>&#x3C;>0: Failed, refer <a href="/pages/kU24dUIxUPVgYJPLKotj">Table of errors</a></p></td></tr><tr><td>neo_ResponseData</td><td>Object</td><td><p>{</p><p>    “redirect”: &#x3C;Payment link>,</p><p>    "qrData":  A string that used to generate QR code,</p><p>    "bankName": Beneficial bank name<br>    "bankAccount": Beneficial bank account,</p><p>    "bankAccountName": Account name,</p><p>    "amount":  Order amount,</p><p>    "remark: Payment description with format: </p><p>(50 characters of neo_OrderInfo removed vietnamese accent and special characters) + NEOxxx</p><p><em>*Return QR info if only <strong>QR</strong> method is chosen</em></p><p>}</p></td></tr></tbody></table>

## Example

URL for test: <https://sandbox-api.neopay.vn/pg/api/v1/paygate/neopay>

1. **Create payment link by GET method:**

**Request**:

{% code overflow="wrap" %}

```
https://sandbox-api.neopay.vn/pg/api/v1/paygate/neopay?neo_MerchantCode=XASUKU&neo_PaymentMethod=WALLET,ATM,CC,BANK_TRANSFER&neo_Currency=VND&neo_Locale=vi&neo_Version=1&neo_Command=PAY&neo_Amount=100000&neo_MerchantTxnID=T15959145&neo_OrderID=DH15959145&neo_OrderInfo=DH15959145&neo_Title=Thanh%20to%C3%A1n&neo_ReturnURL=https://sandbox-api.neopay.vn/pg/paygate/tryitnow&neo_AgainURL=https://google.com&neo_TokenCreate=false&neo_SecureHash=1E0D5C957C7CE67750ED82DD1336AC12AA2434A94FE4B707BA23027FEFA1A248
```

{% endcode %}

**Response**:

NeoX automatically redirects to payment page.

2. **Create payment link by POST method**

**Request**:

```
{
    "neo_MerchantCode": "XASUKU",
    "neo_Currency": "VND",
    "neo_Locale": "vi",
    "neo_Version": "1",
    "neo_Command": "PAY",
    "neo_Amount": 100000,
    "neo_MerchantTxnID": "123123123030",
    "neo_OrderID": "ORDER00001",
    "neo_OrderInfo": "IFtestpost",
    "neo_ReturnURL": "https://google.com",
    "neo_PaymentMethod": ["QR"],
    "neo_ExtData": {
        "orderData": {
            "payItems": [
                {
                    "orderId": "SUB_20231225_001",
                    "desc": "Description for sub order id 001",
                    "price": 37000,
                    "extraInfo": {"foo": "bar"}
                },
                {
                   "orderId": "SUB_20231225_002",
                    "desc": "Description for sub order id 002",
                    "price": 63000,
                    "extraInfo": {"foo": "bar"}
                }
            ]
        }
    }
    "neo_SecureHash": "08D507127FEF12C7719CB33221C708650F21EE3C4CA68B7E5E762B9FE648F916"
}
```

With the Secret Key "7EDB9708213543968555AD010C42C16C". *<mark style="color:blue;">neo\_SecureHash</mark>* is created by hashing the string below:

100000PAYVNDviXASUKU123123123030ORDER00001IFtestpostQRhttps\://google.com17EDB9708213543968555AD010C42C16C\
\
\*Note: If merchant use "neo\_ExtData.orderData.payItems" for additional sub order info, the total price of each payItems must equal to neo\_Amount.

**Response**:

```
{
    "neo_ResponseCode": 0,
    "neo_ResponseData": {
        "redirect": "https://sandbox-api.neopay.vn/pg/paygate/XASUKU?billId=231018075010VNBRZF",
        "qrData": "00020101021238560010A0000007270126000697045701129020008685300208QRIBFTTA530370454061000005802VN5915NEOX DIEN MAY H62110807NEO20706304051F",
        "bankName": "Wooribank",
        "bankAccount": "902000868530",
        "bankAccountName": "NEOX DIEN MAY H",
        "amount": 100000,
        "remark": "NEO2070"
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neox.vn/docs/global/payment-gateway/integrations/hosted-checkout/apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.