# Payment Callback

After a payment request is made and the user navigates to the Paymento gateway to complete the payment, the user is redirected back to the merchant's Return URL (Given in Payment Request) with a specific status. This allows the merchant to update the order status in their interface. However, it is crucial for merchants to use the [Set Payment Settings API](/api-documention/additional-apis/manage-payment-settings.md) to define the IPN URL for receiving payment statuses and to verify the payment using the Verify Payment API.

### Redirect and Callback Data

Paymento returns the following variables in the Callback (to Return URL and IPN URL):

#### HTTP Headers

<table><thead><tr><th>Name</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>X-HMAC-SHA256-SIGNATURE</strong></td><td>“Signature hash…”</td><td></td></tr></tbody></table>

#### Body Patameters&#x20;

| Name               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| **Token**          | Token of the payment order.                              |
| **PaymentId**      | The order ID in Paymento (Payment ID, as a long number). |
| **OrderId**        | The order ID from the online store (as a string).        |
| **OrderStatus**    | The order status (explained in next paragraph)           |
| **AdditionalData** | The payment request's additional data.                   |

### Order Statuses

When the user completes or cancels the payment, Paymento redirects them to the specified callback URL with one of the following statuses:

* **Initialize (0)**: Payment request accepted by the API.
* **Pending (1)**: User has chosen a coin to pay.
* **PartialPaid (2)**: User paid less than the order amount.
* **WaitingToConfirm (3)**: User's transaction received in the blockchain network (in mempool or block).
* **Timeout (4)**: Payment deadline expired.
* **UserCanceled (5)**: User clicked on the cancel button at the gateway.
* **Paid (7)**: User's transaction confirmed in the blockchain network.
* **Approve (8)**: Payment verified by the store.
* **Reject (9)**: Address assigned for the user's payment is no longer monitored, or payment not verified by the store.

### HMAC Signature Verification

To ensure the integrity and authenticity of callbacks from Paymento, we use HMAC-SHA256 signatures. For each callback, Paymento includes a signature in the `X-Hmac-Sha256-Signature` header. To verify this signature:

1. Obtain the raw payload of the callback (the entire body of the POST request).
2. Use your secret key (Provided in your Paymento dashboard).
3. Calculate the HMAC-SHA256 hash of the payload using your secret key.
4. Convert the resulting hash to uppercase hexadecimal format.
5. Compare this calculated signature with the one received in the `X-Hmac-Sha256-Signature` header.

```
// The signatures should match exactly. Here's a pseudo-code example:

receivedSignature = headers['X-HMAC-SHA256-SIGNATURE']
payload = request.rawBody
secretKey = "Your-Secret-Key-From-Paymento-Dashboard"
calculatedSignature = uppercase(hmac_sha256(payload, secretKey))
isValid = (calculatedSignature == receivedSignature)

```

### Important notes

**Do Not Rely Solely on Redirect to Return URL**: Merchants must use the IPN URL set in the "Set Payment Settings API" to receive real-time payment status updates.

**Always Verify Payments**: Even after receiving a "Paid" status, always verify the payment [using the Verify Payment API](/api-documention/payment-verify.md) to ensure the transaction is confirmed on the blockchain and status update came from Paymento.

#### Call Back Example

```
curl 
-X POST https://yoursite.com/shop/payment-result 
-H 'Accept: application/json' 
-H 'HMAC_SHA256_SIGNATURE: 42FBF2A14FEF5E9D89B92731F4F12B9153438C8F06F60D62AA8A8D0ADD551E7B' 
-H 'Content-Type: application/json' 
-d '{"Token":"d1179e54e58d4e51a285a5c659a2b7ef","PaymentId":20016,"OrderId":"etp-3900","OrderStatus":3,"AdditionalData":[]}'  
```


---

# 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.paymento.io/api-documention/payment-callback.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.