TeePayDocs
API ReferenceControl numbers

Create a Control Number

POST
/v1/control-numbers

Issues a Tanzanian Control Number (TZS) for a bill or a customer. 201 returns the number; 202 means issuance is still in progress, so retry with the same Idempotency-Key, never a new one. Requires control_number:create and approved Control Number access.

Authorization

BearerAuth
headerAuthorizationBearer <token>

Secret API key: tp_test_. or tp_live_.. Server-side only.

Header Parameters

Idempotency-Key*string
Match^[A-Za-z0-9_-]+$
Length8 <= length <= 128

Request Body

application/json
  1. body
kind*unknown
Value in"bill""customer"
customer*
description?string
Lengthlength <= 240
amount_minor?string
Match^[1-9][0-9]{0,18}$
maximum_minor?string
Match^[1-9][0-9]{0,18}$
payment_mode?unknown
Value in"EXACT""ALLOW_PARTIAL_AND_OVER_PAYMENT"

Response Body

Control Number issued

Example Request
curl -X POST 'https://api.teepay.me/v1/control-numbers' \  -H 'Idempotency-Key: order-1001' \  -H 'Content-Type: application/json' \  -d '{  "kind": "bill",  "customer": {    "name": "Asha Juma",    "phone": "0712345678"  },  "description": "School fees, term 1",  "amount_minor": "5000000"}'
Example Response
Empty

List checkout sessions GET

Checkout sessions created through the API, newest first. Requires checkout:read.

Get a Control Number GET

One Control Number and the payments received on it. Only payments with status verified are money received; pending_verification and under_review are not. Requires control_number:read.