> For the complete documentation index, see [llms.txt](https://docs.paymento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paymento.io/api-documentation/payment-callback.md).

# Payment Callback

Paymento tells your store about a payment in two ways:

* **IPN callback (server to server):** a signed HTTP request to the IPN URL you set once with the [Set Payment Settings API](https://docs.paymento.io/api-documentation/additional-apis/manage-payment-settings.md). This is the notification to rely on.
* **Return URL redirect (browser):** when the customer leaves the gateway, their browser is sent back to the `returnUrl` you gave in the [Payment Request](https://docs.paymento.io/api-documentation/payment-request.md). It is not signed, so use it only to show the customer a page.

In both cases, confirm the payment with the [Verify Payment API](https://docs.paymento.io/api-documentation/payment-verify.md) before you fulfil the order.

### IPN callback

Paymento sends the callback as JSON (`Content-Type: application/json`). The HTTP method comes from your payment settings: `1` = POST, `2` = PUT. **Any other value, including `0`, is sent as PUT** — set `ipN_Method` to `1`, or accept both methods.

#### HTTP Headers

| Name                        | Value                                                  |
| --------------------------- | ------------------------------------------------------ |
| **X-HMAC-SHA256-Signature** | Uppercase hex HMAC-SHA256 of the raw body (see below). |

#### Body Parameters

The callback body uses **PascalCase** keys (API responses use camelCase).

| Name               | Type    | Description                                                       |
| ------------------ | ------- | ----------------------------------------------------------------- |
| **Token**          | string  | Token of the payment order.                                       |
| **PaymentId**      | string  | The payment ID in Paymento.                                       |
| **OrderId**        | string  | The order ID from your online store.                              |
| **OrderStatus**    | integer | The order status (see [Order Statuses](#order-statuses)).         |
| **AdditionalData** | array   | The payment request's additional data, as `[{ "Key", "Value" }]`. |

### Return URL redirect

When the customer leaves the gateway, the browser is redirected with a `GET` request:

```
https://yoursite.com/shop/payment-result?token=3256e147c6fe4d36a9341a5112ed2214&orderId=etp-3900&status=3
```

| Parameter | Description                                 |
| --------- | ------------------------------------------- |
| `token`   | Token of the payment order.                 |
| `orderId` | The order ID from your online store.        |
| `status`  | The order status as an integer (see below). |

Anyone can build this URL, and a customer who returns early sees a status that is still in progress. Never change an order from it. Show the status stored on your order instead.

Do not call Verify directly from the return page. If the paid callback was lost, that Verify moves the order from `Paid` to `Approve` and ends Paymento's retries, with nothing stored on your side to fulfil it. To refresh the status, do it only for a token your store created, and run it through the same stored, locked processing as a callback (see [Retries and processing](#retries-and-processing)).

### Order 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.
* **Refunded (10)**: The payment was fully refunded to the payer.

Value 6 (`Revert`) is reserved and not currently produced. See [Payment States and Confirmations](https://docs.paymento.io/api-documentation/payment-states-and-confirmations.md) for how the states move.

### 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 exact bytes of the request body, before any JSON parsing).
2. Use your secret key (provided in your Paymento dashboard) as UTF-8 text.
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, using a constant-time comparison. Reject the callback (`401`) if the header is missing or does not match.

```
// 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(hex(hmac_sha256(key = secretKey, message = payload)))
isValid = constantTimeEquals(calculatedSignature, receivedSignature)

```

### Retries and processing

* Answer with a `2xx` status once you have stored the callback.
* Paymento retries a failed callback **only while the order is still `Paid`**: after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours (7 attempts in total). Callbacks for other statuses are not retried.
* Your first successful Verify moves the order from `Paid` to `Approve`, which ends those retries. If your server fails after calling Verify but before updating your order, Paymento will not call again.
* So **call Verify only from your callback processing** (not from a return page, an admin button or a cron job), **store each authenticated callback durably before calling Verify**, answer `2xx` once it is stored, and retry unprocessed callbacks from your own job (Verify → update your order → mark the callback processed).
* Process one callback per token at a time (a lock shared by all your servers), so an older Verify result cannot overwrite a newer one.
* Never move a paid order back to an unpaid status. One store order can have several tokens (a customer who retries checkout), and an abandoned token still reports `Timeout` or `UserCanceled` later.

### 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](https://docs.paymento.io/api-documentation/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/api/paymento/ipn 
-H 'Accept: application/json' 
-H 'X-HMAC-SHA256-Signature: 42FBF2A14FEF5E9D89B92731F4F12B9153438C8F06F60D62AA8A8D0ADD551E7B' 
-H 'Content-Type: application/json' 
-d '{"Token":"d1179e54e58d4e51a285a5c659a2b7ef","PaymentId":"20016","OrderId":"etp-3900","OrderStatus":3,"AdditionalData":[]}'  
```

The signature above is illustrative; compute your own over the exact body you receive.
