# IPN

### Instant Payment Notification

Merchant can get payment result via IPN (Instant Payment Notification).

Merchant needs to build a RESTful API to receive data from NeoX after the transaction is completed. This API must be registered to NeoX before the payment is made

Method: POST

Data refer to [NeoX's IPN data](#neoxs-ipn-data).

Merchant has to respond to NeoX  following the structure [merchant response](#merchant-response) when receiving IPN.

#### Process Flow

### How to verify the IPN

<figure><img src="/files/Nz84OmYukmei3IpD9CQL" alt=""><figcaption></figcaption></figure>

**How to validate neo\_SecureHash**

* Format: hex string, 64 characters, uppercase
* Using cryptographic hash function SHA256

#### How to build

* Input is all parameters on *PaymentURL* or *ReturnURL*.
* Only use parameters that start with prefix neo\_.
* String must be sorted in alphabetical order base on parameter name.
* NeoX will provide a Secret Key to merchant to hash.

#### IPN verification

Merchant needs to build a hashed string follow above guide and compare to received *neo\_SecureHash* parameter

### NeoX's IPN data

<table><thead><tr><th width="200">Parameter</th><th width="117">Data type</th><th>Description</th></tr></thead><tbody><tr><td>neo_MerchantCode</td><td>String</td><td>The merchant code is  provided by NeoX.</td></tr><tr><td>neo_Currency</td><td>String</td><td>Refer to <a href="/pages/kU24dUIxUPVgYJPLKotj">table of error code</a></td></tr><tr><td>neo_Locale</td><td>String</td><td>The language will use on payment page, support: “vi”, “en".</td></tr><tr><td>neo_Version</td><td>String</td><td>Payment gateway version, “1” as default</td></tr><tr><td>neo_Command</td><td>String</td><td>"PAY" as default.</td></tr><tr><td>neo_Amount</td><td>Number</td><td>Order amount.</td></tr><tr><td>neo_MerchantTxnID</td><td>String</td><td>Transaction ID is provided by merchant, it must be unique on merchant’s system and on each request, accept only characters, numerics and list of symbols: “-”, “_”.</td></tr><tr><td>neo_OrderID</td><td>String</td><td>Order ID of the transaction, only accept  characters, numerics and list of symbols: “-”, “_”.</td></tr><tr><td>neo_OrderInfo</td><td>String</td><td>Order information, max length 256</td></tr><tr><td>neo_TransactionID</td><td>String</td><td>Unique - Transaction ID is generated by NeoX.</td></tr><tr><td>neo_PayToken</td><td>String</td><td>Using for <a href="/pages/0vzAzweaFEOa7Fm9XuIU">Tokenization</a> service</td></tr><tr><td>neo_ResponseCode</td><td>Number</td><td>Result of transaction: <br> 0: transaction success <br> != 0: transaction failed, refer to <a href="/pages/kU24dUIxUPVgYJPLKotj#table-of-error-code">table of error code</a></td></tr><tr><td>neo_ResponseMsg</td><td>String</td><td>Error description.</td></tr><tr><td>neo_SecureHash</td><td>String</td><td>Use <strong>SHA256</strong> to hash the above parameters (sort the key by Alphabet order) + Secret Key (is provided by NeoX after actual integrating).</td></tr></tbody></table>

#### Some fields in IPN data but not using to create neo\_SecureHash

<table><thead><tr><th width="195">Parameter</th><th width="123">Data type</th><th>Description</th></tr></thead><tbody><tr><td>neo_TransAmount</td><td>number</td><td>Transaction amount (partial payment).</td></tr><tr><td>neo_ExtData</td><td>Object</td><td>Extra data of transaction.</td></tr></tbody></table>

### Merchant response

<table><thead><tr><th width="158.33333333333331">Parameter</th><th width="162">Data type</th><th>Description</th></tr></thead><tbody><tr><td>respcode</td><td>Number</td><td><ul><li>0: Successful, merchant received IPN.</li><li>1: Failed, NeoX will retry the IPN. </li></ul></td></tr><tr><td>respmsg</td><td>String</td><td>Error message. Default is “<em>received</em>”</td></tr></tbody></table>


---

# 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/v2/payment-gateway/transaction-management/ipn.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.