Mizaniya Pay VTPE API: Reference Overview - mizaniya-api-beta

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 for the full schema.
Webhook handler (POST /webhooks/vtpe): Return HTTP 200 with the following JSON body to acknowledge receipt:

{
  "success": true
}

Error Format

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

{
  "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 — GET {API_URL}/{reference}: Returns payment details for a given reference.
Webhook Handler — POST {API_URL}/webhooks/vtpe: Receives payment lifecycle events from VTPE.

⌘I