# 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="../direct-api/tokenization">tokenization</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="../../transaction-management/error-codes">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"
    }
}
```