> 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/payment-gateway/transaction-management/ipn.md).

# 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>