> ## Documentation Index
> Fetch the complete documentation index at: https://beta-developers.mizaniyapay.dz/llms.txt
> Use this file to discover all available pages before exploring further.

# Mizaniya Pay VTPE API: Reference Overview

> Partner-hosted API conventions, request headers, response formats, and error structure for Mizaniya Pay VTPE integrations.

Mizaniya Pay VTPE uses a partner-hosted model. You expose two endpoints on your own servers, and the VTPE platform calls them. This page covers the common request headers, response formats, and error conventions that apply across both endpoints.

## Request Headers

Every request that VTPE sends to your endpoints includes the following headers.

| Header          | Value                    | Description                                                                                                    |
| --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `Authorization` | `Bearer YOUR_API_SECRET` | Your API secret used for request authentication.                                                               |
| `X-Timestamp`   | Unix timestamp (seconds) | The time the request was generated, expressed as a Unix timestamp.                                             |
| `X-Signature`   | HMAC hex string          | HMAC-SHA256 signature of the raw request body concatenated with the timestamp (sent only on webhook requests). |

## Response Format

All responses must be valid JSON.

* **Product Information API** (`GET /{reference}`): Return a JSON object containing the payment details for the requested reference. See [Get Payment](/api-reference/payments/get-payment) for the full schema.
* **Webhook handler** (`POST /webhooks/vtpe`): Return HTTP 200 with the following JSON body to acknowledge receipt:

```json theme={null}
{
  "success": true
}
```

## Error Format

When your endpoint returns an error, use this JSON structure:

```json theme={null}
{
  "error": "CODE",
  "errorMessage": "Human readable description"
}
```

| Error Code            | HTTP Status | Meaning                                                    |
| --------------------- | ----------- | ---------------------------------------------------------- |
| `NOT_FOUND`           | 404         | The requested reference does not exist in your system.     |
| `ALREADY_PAID`        | 409         | The payment for this reference has already been completed. |
| `SERVICE_UNAVAILABLE` | 503         | Your service is temporarily unable to handle the request.  |

## Endpoints

Your integration must expose these two endpoints:

* [**Product Information API**](/api-reference/payments/get-payment) — `GET {API_URL}/{reference}`: Returns payment details for a given reference.
* [**Webhook Handler**](/api-reference/webhooks/events) — `POST {API_URL}/webhooks/vtpe`: Receives payment lifecycle events from VTPE.