Create Dynamic QR Payment

curl --request POST \
  --url https://meet.briq.tz/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 5000,
  "currency": "TZS",
  "type": "mobile",
  "phone": "255712345678",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "reference": "ORDER_12345",
  "metadata": {
    "item_id": "PROD_001"
  }
}
'

{
  "status": "success",
  "code": 123,
  "message": "<string>",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reference": "<string>",
    "external_id": "<string>",
    "amount": 123,
    "margin_amount": 123,
    "total_amount": 123,
    "currency": "<string>",
    "phone": "<string>",
    "network": "<string>",
    "payment_url": "<string>",
    "qr_code": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "meta": {}
}

POST

api

payments

curl --request POST \
  --url https://meet.briq.tz/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 5000,
  "currency": "TZS",
  "type": "mobile",
  "phone": "255712345678",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "reference": "ORDER_12345",
  "metadata": {
    "item_id": "PROD_001"
  }
}
'

{
  "status": "success",
  "code": 123,
  "message": "<string>",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reference": "<string>",
    "external_id": "<string>",
    "amount": 123,
    "margin_amount": 123,
    "total_amount": 123,
    "currency": "<string>",
    "phone": "<string>",
    "network": "<string>",
    "payment_url": "<string>",
    "qr_code": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "meta": {}
}

POST /api/v1/payments with type: "dynamic-qr". Idempotency-Key is required — requests without it return 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.

Required fields

Field	Notes
`amount`, `currency`, `type`, `customer`, `phone`	`type` must be `"dynamic-qr"`. Currencies: `TZS`, `USD`, `KES`, `UGX`
`customer`	`firstname`, `lastname`, `email` only — billing address is not required

Optional fields

Field	Notes
`redirect_url`, `cancel_url`	Forwarded to the hosted checkout provider when set; not validated as required
`network`	Mobile network operator
`reference`, `metadata`	Duplicate live `reference` → `409 DUPLICATE_REFERENCE`
`webhook_url`, `callback_url`	Override merchant defaults

Phone is required for notifications and receipts but is not strictly validated to Tanzanian format (unlike mobile payments).

Response

Field	Value
`status`	`pending`
`qr_code`	QR data string — render in your UI for the customer to scan
`payment_url`	Hosted checkout fallback when scanning is not possible
`payment_token`	May be set by the provider

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.

Errors

HTTP	`error_code`	When
400	`VALIDATION_ERROR`	Missing required fields or unsupported currency

Full list: Errors.

In Try It, select the Dynamic QR request example.

Authorizations

Authorization

string

header

required

API key obtained from the merchant dashboard. When using the 'Try It' feature, enter only the key—the 'Bearer ' prefix is added automatically. For direct API calls, the 'Authorization: Bearer ' format is mandatory.

Headers

Idempotency-Key

string

required

Required. A unique value (max 255 characters) per payment attempt, scoped to your merchant account. Requests without it are rejected with 400 IDEMPOTENCY_KEY_REQUIRED. Reuse the same value when retrying — the retry returns 200 with the original payment instead of creating a duplicate. Safe under concurrent retries: the losing request replays the winner's payment.

Maximum string length: 255

Example:

"123e4567-e89b-12d3-a456-426614174000"

Body

application/json

Option 1
Option 2
Option 3

amount

number

required

Amount the customer is charged. Minimum 500 TZS when currency is TZS.

currency

enum<string>

default:TZS

required

Available options:

TZS,

USD,

KES,

UGX

type

string

required

Mobile money USSD push payment.

Allowed value: "mobile"

phone

string

required

Customer phone number. For TZS, accepted formats: 0712345678, 712345678, 255712345678, +255712345678 — normalized to 255XXXXXXXXX and must be a valid Tanzanian mobile number (2556/2557 prefix). Invalid numbers return 400 VALIDATION_ERROR.

customer

object

required

Show child attributes

network

enum<string>

Optional — the mobile network operator is auto-detected from the phone number. Aliases accepted: mpesa (vodacom), mixx (tigo). Invalid values return 400 VALIDATION_ERROR.

Available options:

vodacom,

tigo,

airtel,

halotel,

ttcl

reference

string

Your internal reference. A reference with an existing live (pending/processing/completed) payment is rejected with 409 DUPLICATE_REFERENCE.

webhook_url

string

Per-payment webhook URL. Overrides merchant webhook_url when set.

callback_url

string

Per-payment callback URL for terminal status. Overrides merchant callback_url when set.

metadata

object

Response

Idempotent replay — a payment already exists for this Idempotency-Key. The existing payment is returned and no new charge is created.

Standard success envelope wrapping all API responses.

status

enum<string>

Available options:

success

code

integer

HTTP status code echoed in the body

message

string

data

object

Payment record returned by GET /payments/{id}, GET /payments, POST /payments/{id}/refresh, and idempotent replays. reference is YOUR merchant reference; the upstream payment identifier is external_id.

Show child attributes

​Required fields

​Optional fields

​Response

​Errors

Authorizations

Headers

Body

Response

Required fields

Optional fields

Response

Errors