Create Mobile 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: "mobile". Idempotency-Key is required — requests without it return 400 IDEMPOTENCY_KEY_REQUIRED. Idempotency. Returns 201 with status: "pending" and a USSD push to the customer’s phone, or 200 when replaying an existing Idempotency-Key.

Required fields

Field	Notes
`amount`, `currency`, `type`, `customer`, `phone`	`type` must be `"mobile"`. Currencies: `TZS`, `USD`, `KES`, `UGX`
`customer`	`firstname`, `lastname`, `email`
`phone`	TZS numbers are normalized and validated — see below

Optional fields

Field	Notes
`network`	Auto-detected from phone; aliases `mpesa` → `vodacom`, `mixx` → `tigo`
`reference`, `metadata`	Duplicate live `reference` → `409 DUPLICATE_REFERENCE`
`webhook_url`, `callback_url`	Override merchant defaults

Phone formats (TZS)

These all normalize to 255712345678: 0712345678, 712345678, 255712345678, +255712345678. After normalization the number must be a valid Tanzanian mobile (255 + 6/7 + 8 digits) — anything else returns 400 VALIDATION_ERROR.

Minimum amount

500 TZS minimum when currency is TZS.

Response

Field	Value
`status`	`pending`
`payment_url`	Omitted
`qr_code`	Omitted

The customer receives a USSD prompt and authorizes with their wallet PIN. Unfinished payments expire roughly 30 minutes after creation.

Errors

HTTP	`error_code`	When
400	`VALIDATION_ERROR`	Invalid phone, network, or currency
400	`PAYMENT_FAILED`	Amount below the 500 TZS minimum
402	`PAYMENT_DECLINED`	Synchronous provider decline — `details.transaction_id` in response

Full list: Errors.

In Try It, select the Mobile Money or Mobile Money (explicit network) 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

​Phone formats (TZS)

​Minimum amount

​Response

​Errors

Authorizations

Headers

Body

Response

Required fields

Optional fields

Phone formats (TZS)

Minimum amount

Response

Errors