Payment Gateway

QR Codes

Accept in-person payments using QR codes. Mazad supports two modes: merchant-presented (customer scans) and customer-presented (merchant scans).

Two QR modes

Merchant-Presented QR

Merchant generates a QR code for a specific amount.

QR is displayed on a screen, printed receipt, or tablet.

Customer scans with the Mazad app and confirms payment.

Best for: Retail POS, restaurant table payments, market stalls

Customer-Presented QR

Customer opens their Mazad wallet and shows their personal QR code.

Merchant scans the customer QR using their POS or camera.

Merchant enters the amount and charges the customer wallet directly.

Best for: Fast-food counters, transit gates, vending machines

Generate a QR code

POST/embedded/qr/generate

Generate a merchant-presented QR code for a specific payment amount. Returns a QR code image URL and a payment session.

Request Body

Name	Type	Required	Description
amount	integer	required	Payment amount in smallest currency unit.
currency	string	required	ISO 4217 currency code (e.g., IQD, USD).
description	string	optional	Description shown when customer scans. Max 256 characters.
reference	string	optional	Your order/invoice ID for reconciliation.
format	string	optional	QR image format: "png" (default), "svg". PNG is 400x400px.
size	integer	optional	QR image size in pixels (PNG only). Min 200, max 1000. Default 400.
expires_in	integer	optional	QR code TTL in seconds. Min 60 (1 min), max 3600 (1 hour). Default 300 (5 min).
metadata	object	optional	Arbitrary key-value pairs passed through to webhooks.

curl -X POST https://wallet.e-mazad.store/api/v1/embedded/qr/generate \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "IQD",
    "description": "Coffee & pastry",
    "reference": "pos_order_789",
    "format": "png",
    "size": 400,
    "expires_in": 300,
    "metadata": {
      "register_id": "reg_01",
      "cashier": "Ali"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "qr_g7h8i9j0k1l2",
    "qr_image_url": "https://cdn.mazad.com/qr/qr_g7h8i9j0k1l2.png",
    "qr_data": "mazad://pay?s=qr_g7h8i9j0k1l2&a=15000&c=IQD",
    "payment_id": "pay_q1w2e3r4t5y6",
    "amount": 15000,
    "currency": "IQD",
    "description": "Coffee & pastry",
    "reference": "pos_order_789",
    "status": "pending",
    "expires_at": "2026-03-20T14:35:00Z",
    "created_at": "2026-03-20T14:30:00Z"
  }
}

QR code flow after generation

After generating the QR, display qr_image_url on your POS screen and poll GET /embedded/payments/{payment_id} for completion. The payment transitions to completed when the customer scans and confirms.

Customer-presented mode

In customer-presented mode, the customer shows their personal Mazad QR code. Your POS scans it to get a user token, then creates a payment directly.

Customer opens Mazad app

They navigate to "Pay" and show their personal QR code on screen.

Merchant scans the QR

Your POS camera scans the QR data which contains a one-time user token.

Parse the QR data

Extract the user_token from the QR payload. Format: mazad://id?t={user_token}

Create a charge

POST /embedded/qr/charge with the user_token and amount. Payment is authorized instantly.

Charge via customer QR

# After scanning customer's QR and extracting the user_token
curl -X POST https://wallet.e-mazad.store/api/v1/embedded/qr/charge \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "user_token": "ut_scanned_from_customer_qr",
    "amount": 8500,
    "currency": "IQD",
    "description": "Shawarma wrap + drink",
    "reference": "pos_order_790"
  }'

Charge response

{
  "success": true,
  "data": {
    "payment_id": "pay_u1i2o3p4a5s6",
    "status": "completed",
    "amount": 8500,
    "currency": "IQD",
    "user_id": "mzd_usr_9f8e7d6c5b4a",
    "description": "Shawarma wrap + drink",
    "reference": "pos_order_790",
    "created_at": "2026-03-20T14:30:00Z"
  }
}

User token expiry

Customer-presented QR tokens expire after 60 seconds. If the token is stale, the charge will fail with a token_expired error. Ask the customer to refresh their QR code.

Ready to integrate Mazad into your platform?

Our team will review your business and issue your production API keys within 2 business days.

Contact Sales Create Sandbox Account

Payment Links Subscriptions Overview