Skip to main content
POST /api/v1/payments with type: "dynamic-qr". Idempotency-Key required — requests without it are rejected with 400 IDEMPOTENCY_KEY_REQUIRED. Idempotency. Returns 201 with status: "pending", a qr_code payload, and a payment_url fallback, or 200 when replaying an existing Idempotency-Key.

​
Body

FieldRequiredNotes
amount, currency, type, customer, phoneyestype must be "dynamic-qr". Currencies: TZS, USD, KES, UGX
customeryesfirstname, lastname, email only — billing address is not required
redirect_url, cancel_urlnoOptional; forwarded to the hosted checkout page when set
networknoValidated against the supported operator list when provided; not needed for QR
reference, metadatanoDuplicate live reference → 409 DUPLICATE_REFERENCE
webhook_urlnoRecommended — status events; overrides merchant default
callback_urlnoOptional — one-shot terminal notification; omit unless you need a separate callback endpoint
Phone is required for notifications and receipts but is not strictly validated to Tanzanian format (unlike mobile payments).

​
What the customer sees

  1. You receive qr_code and payment_url in the response (the payment link is also sent to the customer’s email and phone).
  2. Render the QR code in your UI (checkout, POS display, in-app screen).
  3. The customer scans with their mobile-money or bank app and confirms.
  4. If scanning is not possible, redirect them to payment_url instead.
  5. PayGrid sends a webhook when the payment reaches a terminal status.
If the provider does not return a separate QR string, qr_code falls back to payment_url. Unfinished payments expire roughly 30 minutes after creation.

​
Error semantics

HTTPerror_codeMeaning
400IDEMPOTENCY_KEY_REQUIREDMissing Idempotency-Key header
400VALIDATION_ERRORMissing required fields, invalid network, or unsupported currency
402PAYMENT_DECLINEDPayment declined immediately — no charge; details has transaction_id, status: "failed", and reference
409DUPLICATE_REFERENCEA live (pending/processing/completed) payment with this reference exists; failed, cancelled, or expired attempts do not block a retry
502PROVIDER_UNAVAILABLE / PROVIDER_ERRORTemporary upstream outage — retry with the same Idempotency-Key
Full list: Errors. Webhooks · Payment status · Mobile payment · Card payment

API reference

Create Dynamic QR Payment
curl -X POST "https://meet.briq.tz/api/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":5000,"currency":"TZS","type":"dynamic-qr","phone":"255712345678","customer":{"firstname":"John","lastname":"Doe","email":"[email protected]"},"reference":"ORDER_123","webhook_url":"https://api.example.com/paygrid/webhooks"}'