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

​
Body

FieldRequiredNotes
amount, currency, type, customer, phoneyestype must be "card". Currencies: TZS, USD, KES, UGX
customeryesfirstname, lastname, email, address, city, state, postcode, country
redirect_url, cancel_urlyesHosted checkout return URLs
networknoValidated against the supported operator list when provided; not needed for card
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 but is not strictly validated to Tanzanian format (unlike mobile payments).

​
What the customer sees

  1. You receive payment_url in the response (the link is also sent to the customer’s email and phone).
  2. Redirect the customer’s browser to that URL.
  3. They enter card details on the hosted checkout page (PCI scope stays with PayGrid).
  4. They are redirected to your redirect_url (success) or cancel_url (cancelled).
  5. PayGrid sends a webhook with the final status.
Trust the webhook over the redirect — the redirect is a UX cue; the webhook is the source of truth. Unfinished payments expire roughly 30 minutes after creation.

​
Error semantics

HTTPerror_codeMeaning
400IDEMPOTENCY_KEY_REQUIREDMissing Idempotency-Key header
400VALIDATION_ERRORMissing/invalid amount, currency, type, customer, or phone
400PAYMENT_FAILEDMissing redirect_url, cancel_url, or a billing address field (customer.address, city, state, postcode, country)
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 · Dynamic QR

API reference

Create Card 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":"card","phone":"255712345678","customer":{"firstname":"John","lastname":"Doe","email":"[email protected]","address":"123 Samora Ave","city":"Dar es Salaam","state":"Dar es Salaam","postcode":"11101","country":"TZ"},"redirect_url":"https://shop.example.com/payment/success","cancel_url":"https://shop.example.com/payment/cancel","reference":"ORDER_123","webhook_url":"https://api.example.com/paygrid/webhooks"}'