Skip to main content
This page documents all notable changes to the VTPE Integration API. Breaking changes are marked with a Breaking badge. We recommend subscribing to release announcements through your partner account.

​
2026-07-01 — Static QR Code Amount Configuration API v1.0

New endpoints for managing payment amounts on static QR codes.
  • POST {api_base_url}/set-qr-config — attach one or more DZD amounts to a static QR code
  • POST {api_base_url}/un-set-qr-config — remove amount configuration from a static QR code
  • Supports permanent, time-limited (expiresAt), and single-use (singleUse: true) configurations
  • Multi-amount mode: customer selects from a list; single-amount mode: skips selection step
  • Authentication via x-api-key header; QR code token retrieved from Partner Platform
  • Error codes: AUTH401_UNAUTHORIZED_ACCESS, QR_CODE404_NOT_FOUND, QR_CODE400_CANNOT_BE_MODIFIED, QR_CODE400_INVALID_STATUS, VALIDATION400

​
2026-06-01 — Payment Status API v1

New read-only endpoint for reconciling payment state without relying solely on webhooks.
  • GET /partner/payments/v1/{reference}/status — query lock and payment state for a reference
  • Authentication via x-api-key header
  • Response includes stage (enum: locked, paid, released, refunded, not_found), locked, paid, lockReleaseTime, paymentId, channel, currency, amount, and nested payment object
  • payment.webhookDelivery field reports delivery state of the confirmation webhook
  • Rate limit: 60 requests per minute
  • Error codes: PARTNER_API401_UNAUTHORIZED, PARTNER_API403_MERCHANT_INACTIVE, VALIDATION400
  • Intended as a safety net when webhooks are not received; webhooks remain the primary signal

​
2026-05-01 — v1.0.0

Initial release of the VTPE Integration API.
  • GET {API_URL}/{reference} endpoint specification published
  • Response schema: reference, total_amount, amount_detail, currency, details
  • Multilingual label support: label_ar, label_en, label_fr on amount and detail items
  • Error codes defined: NOT_FOUND, ALREADY_PAID, SERVICE_UNAVAILABLE
  • payment.initialized event: fires when a payment session is created
  • payment.success event: fires on confirmed payment; includes channel (AGENCY, DELIVERY, MARKETPLACE), paidAt, and paymentId
  • payment.fail event: fires on failed or cancelled payment; includes reference and paymentId
  • Common envelope: { "event": "string", "data": {} }
  • Bearer API Secret via Authorization header on all requests
  • X-Timestamp header for replay attack prevention
  • HMAC-SHA256 webhook signature via X-Signature header
  • Signing input: payload + timestamp using your HMAC Secret
  • Partners provide two URLs: API URL and Webhook URL
  • Webhook acknowledgement: HTTP 200 with { "success": true }