Payment Status API: GET /partner/payments/v1/{reference}/status

The Payment Status API lets you query, at any time, whether Mizaniya Pay holds a lock on a product reference and whether it was paid. Call it when a webhook never arrived, before selling a product on-premise, or during reconciliation. It is read-only and never changes the state of a payment.

Endpoint

GET /partner/payments/v1/{reference}/status

Authentication

This endpoint uses your Mizaniya Pay API key, passed as a header:

x-api-key: YOUR_API_KEY

Your API key identifies your merchant account. Results are scoped to it. A reference belonging to another merchant is returned as not_found.

Path Parameters

string

required

The product reference you returned from your Product Information API. Non-empty, maximum 255 characters. URL-encode it if it contains reserved characters.

Rate Limit

60 requests per minute.

How to Decide at a Glance

Branch on locked first. If you need to distinguish “sold” from “never paid”, also read paid.

`stage`	`locked`	`paid`	What it means	What to do
`locked`	`true`	`false`	A payment attempt is in progress.	Keep the product reserved.
`paid`	`false`	`true`	A payment succeeded.	Mark the product sold. Never release or resell.
`released`	`false`	`false`	Attempts exist but none succeeded and none holds a lock.	Safe to release the product.
`refunded`	`false`	`false`	A payment was refunded.	Safe to release the product.
`not_found`	`false`	`false`	No record of this reference under your account.	Safe to release the product.

Only released, refunded, and not_found mean nothing is held. Treat any other stage as still held. On any error response, do not release the lock.

Response Envelope

Every successful call returns HTTP 200 with this envelope:

{
  "message": "success",
  "statusCode": 200,
  "data": { ... }
}

Response Fields

The fields below are the contents of data. All timestamps are UTC ISO-8601.

string

The product reference you queried, echoed back.

enum

One of locked, paid, released, refunded, not_found. Branch on this field for business logic.

boolean

true only while Mizaniya Pay is actively holding this reference. The single field to check for a one-shot branch.

boolean

true once a payment for this reference has succeeded.

string | null

UTC ISO-8601 timestamp at which the lock expires. null when nothing is locked, and also null when the locking attempt carries no expiry (the lock is still considered held).

string | null

Identifier of the attempt that decided the stage. Matches the paymentId on VTPE webhooks. null only when stage is not_found.

string

Always AGENCY, matching the channel field on the payment.success webhook.

string

Currency of the deciding attempt. Defaults to DZD when stage is not_found.

number | null

Amount of the deciding attempt. null only when stage is not_found.

object | null

Detail of the deciding attempt. null only when stage is not_found.

Show payment fields

enum

Internal payment status: pending, processing, success, failed, refunded. Prefer stage for branching; this field is for diagnostics only.

string | null

UTC ISO-8601 timestamp of completion. null unless the attempt was paid.

string | null

SATIM order identifier, present once the attempt reaches a final state.

string | null

Delivery state of the outcome webhook sent to you: success, fail, pending, or null if none was due yet. If fail or pending, you likely never received the confirmation — this endpoint is the recovery path.

string

UTC ISO-8601 timestamp when the attempt was created.

string

UTC ISO-8601 timestamp when the attempt was last updated.

Response Examples

locked
paid
released
refunded
not_found

A payment attempt is in progress. Keep the product reserved. Do not sell or release it until the lock expires or you receive a final webhook.Variant 1: Lock with a recorded expiry

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "locked",
    "locked": true,
    "paid": false,
    "lockReleaseTime": "2026-07-26T18:07:41.057Z",
    "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "channel": "AGENCY",
    "amount": 4500,
    "currency": "DZD",
    "payment": {
      "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "processing",
      "amount": 4500,
      "currency": "DZD",
      "paidAt": null,
      "orderId": null,
      "webhookDelivery": "pending",
      "createdAt": "2026-07-26T17:54:41.057Z",
      "updatedAt": "2026-07-26T17:54:41.057Z"
    }
  }
}

Variant 2: Lock with no recorded expiryA payment attempt is in progress but carries no expiry timestamp. Because the lock expiry cannot be proved, it is still reported as held. Treat this exactly like variant 1.

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "locked",
    "locked": true,
    "paid": false,
    "lockReleaseTime": null,
    "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "channel": "AGENCY",
    "amount": 4500,
    "currency": "DZD",
    "payment": {
      "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "processing",
      "amount": 4500,
      "currency": "DZD",
      "paidAt": null,
      "orderId": null,
      "webhookDelivery": null,
      "createdAt": "2026-07-26T17:54:41.057Z",
      "updatedAt": "2026-07-26T17:54:41.057Z"
    }
  }
}

The customer paid. Mark the product sold. Authoritative even if payment.webhookDelivery is fail.

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "paid",
    "locked": false,
    "paid": true,
    "lockReleaseTime": null,
    "paymentId": "3d9f1e77-2b64-4c8a-9f0d-7a1e5c2b8f43",
    "channel": "AGENCY",
    "amount": 4500,
    "currency": "DZD",
    "payment": {
      "paymentId": "3d9f1e77-2b64-4c8a-9f0d-7a1e5c2b8f43",
      "status": "success",
      "amount": 4500,
      "currency": "DZD",
      "paidAt": "2026-07-26T17:57:41.057Z",
      "orderId": "SATIM-ORD-88213",
      "webhookDelivery": "fail",
      "createdAt": "2026-07-26T17:54:41.057Z",
      "updatedAt": "2026-07-26T17:57:41.057Z"
    }
  }
}

Attempts exist but none succeeded and the lock is gone. Safe to release the product.

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "released",
    "locked": false,
    "paid": false,
    "lockReleaseTime": null,
    "paymentId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
    "channel": "AGENCY",
    "amount": 4500,
    "currency": "DZD",
    "payment": {
      "paymentId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
      "status": "failed",
      "amount": 4500,
      "currency": "DZD",
      "paidAt": null,
      "orderId": null,
      "webhookDelivery": null,
      "createdAt": "2026-07-26T17:54:41.057Z",
      "updatedAt": "2026-07-26T17:58:41.057Z"
    }
  }
}

A payment was refunded. Safe to release the product.

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "refunded",
    "locked": false,
    "paid": false,
    "lockReleaseTime": null,
    "paymentId": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "channel": "AGENCY",
    "amount": 4500,
    "currency": "DZD",
    "payment": {
      "paymentId": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "status": "refunded",
      "amount": 4500,
      "currency": "DZD",
      "paidAt": "2026-07-26T17:29:41.057Z",
      "orderId": "SATIM-ORD-77102",
      "webhookDelivery": null,
      "createdAt": "2026-07-26T17:54:41.057Z",
      "updatedAt": "2026-07-26T17:54:41.057Z"
    }
  }
}

No record of this reference under your account. Safe to release the product.

{
  "message": "success",
  "statusCode": 200,
  "data": {
    "reference": "YAL-000123",
    "stage": "not_found",
    "locked": false,
    "paid": false,
    "lockReleaseTime": null,
    "paymentId": null,
    "channel": "AGENCY",
    "amount": null,
    "currency": "DZD",
    "payment": null
  }
}

Error Responses

Errors carry a stable errorCode to branch on. The human-readable message may change. On any error, do not release the lock. Retry or fall back to your existing reconciliation process.

401 — Missing or unrecognized API key

The x-api-key header was absent, empty, sent more than once, or does not match any active key. Also returned when the merchant behind the key no longer exists.

{
  "statusCode": 401,
  "message": "Invalid or missing api-key",
  "errorCode": "PARTNER_API401_UNAUTHORIZED",
  "timestamp": "2026-07-26T17:59:41.058Z"
}

403 — Merchant account is not active

The key is valid but the merchant account is not in an active state. Contact Mizaniya Pay support.

{
  "statusCode": 403,
  "message": "Merchant account is not active",
  "errorCode": "PARTNER_API403_MERCHANT_INACTIVE",
  "timestamp": "2026-07-26T17:59:41.058Z",
  "details": {
    "merchantId": "9c1f8a52-1d3e-4b7a-9f10-2c4e6a8b0d11"
  }
}

400 — Invalid reference

The reference failed validation. It must be a non-empty string of at most 255 characters.

{
  "statusCode": 400,
  "message": "Dto validation error",
  "errorCode": "VALIDATION400",
  "timestamp": "2026-07-26T17:59:41.058Z",
  "details": {
    "errors": [
      {
        "field": "referenceId",
        "errors": ["referenceId must be shorter than or equal to 255 characters"]
      }
    ]
  }
}

429 — Rate limit exceeded

You exceeded 60 requests per minute. Back off and retry. This endpoint is safe to call again at any time.

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Code Examples

import fetch from "node-fetch";

const API_KEY = process.env.VTPE_API_KEY;
const BASE_URL = "https://api.mizaniyapay.dz";

async function getPaymentStatus(reference) {
  const encoded = encodeURIComponent(reference);
  const res = await fetch(
    `${BASE_URL}/partner/payments/v1/${encoded}/status`,
    {
      method: "GET",
      headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
      }
    }
  );

  if (!res.ok) {
    const error = await res.json();
    throw new Error(`${error.statusCode}: ${error.message}`);
  }

  const { data } = await res.json();
  return data;
}

// Usage
const status = await getPaymentStatus("ORDER-1001");

switch (status.stage) {
  case "paid":
    // Fulfill the order
    console.log("Payment confirmed at", status.payment.paidAt);
    break;
  case "locked":
    // Keep reserved; check back later
    console.log("Lock expires at", status.lockReleaseTime);
    break;
  case "released":
  case "refunded":
  case "not_found":
    // Safe to release
    console.log("No active lock — safe to release");
    break;
  default:
    // Treat unknown stages as held
    console.warn("Unknown stage:", status.stage);
}

import os
import httpx

API_KEY = os.environ["VTPE_API_KEY"]
BASE_URL = "https://api.mizaniyapay.dz"

def get_payment_status(reference: str) -> dict:
    from urllib.parse import quote
    encoded = quote(reference, safe="")
    response = httpx.get(
        f"{BASE_URL}/partner/payments/v1/{encoded}/status",
        headers={"x-api-key": API_KEY}
    )

    if response.status_code != 200:
        error = response.json()
        raise Exception(f"{error['statusCode']}: {error['message']}")

    return response.json()["data"]

# Usage
status = get_payment_status("ORDER-1001")

if status["stage"] == "paid":
    # Fulfill the order
    print("Payment confirmed at", status["payment"]["paidAt"])
elif status["stage"] == "locked":
    # Keep reserved; check back later
    print("Lock expires at", status["lockReleaseTime"])
elif status["stage"] in ("released", "refunded", "not_found"):
    # Safe to release
    print("No active lock — safe to release")
else:
    # Treat unknown stages as held
    print("Unknown stage:", status["stage"])

Integration Notes

This endpoint is a safety net, not a replacement for webhooks. Keep handling payment.success and payment.fail as your primary signal.

Branch on stage or locked, never on payment.status. The internal status set may grow; stage is the contract.
A single reference can have multiple payment attempts. Mizaniya Pay always resolves them and returns the one that decides the outcome.
A successful payment always wins over an in-flight attempt. If stage is paid, the product is sold even if another attempt is still processing.
not_found returns HTTP 200, not 404. It is a business answer, not an error.
Do not poll in a tight loop. Call when you need a decision, or at most once every few seconds for a given reference.

Overview

Payments

Webhooks

Static QR Codes

Payment Status API: GET /partner/payments/v1/{reference}/status

Endpoint

Authentication

Path Parameters

Rate Limit

How to Decide at a Glance

Response Envelope

Response Fields

Response Examples

Error Responses

Code Examples

Integration Notes

​Endpoint

​Authentication

​Path Parameters

​Rate Limit

​How to Decide at a Glance

​Response Envelope

​Response Fields

​Response Examples

​Error Responses

​Code Examples

​Integration Notes

Endpoint

Authentication

Path Parameters

Rate Limit

How to Decide at a Glance

Response Envelope

Response Fields

Response Examples

Error Responses

Code Examples

Integration Notes