Product Information API: GET /{reference} Endpoint

The GET endpoint partners must expose for VTPE to retrieve payment details by reference, including response fields and implementation examples.

The Product Information API is the first endpoint you must implement. When a customer initiates a payment through VTPE, the platform calls your server to retrieve the payment details for a specific reference.

Endpoint

GET {API_URL}/{reference}

Authentication

VTPE authenticates each request with the following headers:

Header	Value
Authorization	Bearer YOUR_API_SECRET
X-Timestamp	Unix timestamp (seconds)

Your handler must validate the Authorization header before returning any data.

Path Parameters

reference · string · required

The unique payment reference generated by your system.

Response Fields

reference · string · required

The unique payment reference.

total_amount · number · required

The total amount to be paid.

currency · string · required

The currency code (for example, DZD).

amount_detail · array

Breakdown of the total amount. Each item contains:

• label_ar: Arabic label
• label_en: English label
• label_fr: French label
• value: Amount value

details · array

Additional payment details. Each item contains:

• label_ar: Arabic label
• label_en: English label
• label_fr: French label
• value: Detail value

Implementation Examples

Node.js

import express from "express";
const app = express();
app.use(express.json());

app.get("/payments/:reference", (req, res) => {
  const auth = req.headers["authorization"];
  if (auth !== `Bearer ${process.env.VTPE_API_SECRET}`) {
    return res.status(401).json({ error: "UNAUTHORIZED", errorMessage: "Invalid or missing API Secret" });
  }

  const { reference } = req.params;

  // Look up reference in your database
  const order = db.findOrder(reference);

  if (!order) {
    return res.status(404).json({ error: "NOT_FOUND", errorMessage: "Reference not found" });
  }
  if (order.isPaid) {
    return res.status(409).json({ error: "ALREADY_PAID", errorMessage: "Payment already completed" });
  }

  return res.json({
    reference: order.reference,
    total_amount: order.totalAmount,
    currency: order.currency,
    amount_detail: order.amountDetail ?? [],
    details: order.details ?? []
  });
});

Response Example

{
  "reference": "ORD-2024-001",
  "total_amount": 5000.00,
  "currency": "DZD",
  "amount_detail": [
    {
      "label_ar": "المبلغ الأساسي",
      "label_en": "Base Amount",
      "label_fr": "Montant de base",
      "value": 4500.00
    },
    {
      "label_ar": "رسوم التوصيل",
      "label_en": "Delivery Fee",
      "label_fr": "Frais de livraison",
      "value": 500.00
    }
  ],
  "details": [
    {
      "label_ar": "اسم العميل",
      "label_en": "Customer Name",
      "label_fr": "Nom du client",
      "value": "Ahmed Benali"
    }
  ]
}

Error Responses

HTTP Status	Error Code	Example Response
404	NOT_FOUND	{"error": "NOT_FOUND", "errorMessage": "Reference not found"}
409	ALREADY_PAID	{"error": "ALREADY_PAID", "errorMessage": "Payment already completed"}
503	SERVICE_UNAVAILABLE	{"error": "SERVICE_UNAVAILABLE", "errorMessage": "Service temporarily unavailable"}

For more details on error handling, see the Errors guide.