Mobile money push

Send a USSD payment prompt to a customer's phone and confirm the result from your server.

Requires approval

Mobile money push is the building block for your own checkout, app or payment gateway: you collect the customer's phone number, TeePay sends the payment prompt, the customer approves it with their PIN.

POST/v1/collectionscollection:create

Before you start

Your account must have mobile money push enabled. Check features.collection_create in capabilities.
Your key needs collection:create, and collection:read to read the result.
No payment profile or webhook URL is required to send a push.

Send the prompt

curl https://api.teepay.me/v1/collections \
  -H "Authorization: Bearer $TEEPAY_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "money": { "amount_minor": "500000", "currency": "TZS" },
    "customer": { "country": "TZ", "phone": "+255712345678", "name": "Asha Juma", "email": "asha@example.com" },
    "description": "Order 1001"
  }'

Request fields

Prop

Type

Name and email

The current Tanzanian route requires the payer's full name (first and last) and a valid email. If they are missing the request fails with invalid_request before any prompt is sent. A country and currency your key cannot use fails with unsupported_market; see Countries and currencies. Most integrations fill them from the signed-in user, so the customer only types their phone number.

Response

The API answers 202 Accepted as soon as the payment is recorded and the prompt is sent:

{
  "id": "pay_6b1f…",
  "public_reference": "TP8K2M4QZ1",
  "operation": "charge",
  "status": "pending",
  "money": { "amount_minor": 500000, "currency": "TZS" },
  "created_at": "2026-10-28T10:00:00Z",
  "updated_at": "2026-10-28T10:00:01Z"
}

Wait for the customer

Show a "check your phone" screen and wait for the result. Use either or both:

Webhook: payment.completed or payment.failed with data.reference equal to public_reference. See Webhooks.
Polling: read the payment until it is final. See Payment status.

curl https://api.teepay.me/v1/collections/TP8K2M4QZ1 \
  -H "Authorization: Bearer $TEEPAY_API_KEY"

Deliver the order only when status is succeeded. When it is failed, status_detail tells you if the customer cancelled or the prompt expired; offer to try again with a new order key.

Retries and duplicates

The Idempotency-Key is your protection against double charges. If your request times out or the customer taps "Pay" twice, send the same key and body again: TeePay returns the original payment instead of sending a second prompt. Reusing a key with a different body returns 409 idempotency_conflict.

If TeePay cannot tell whether the provider received the prompt, the payment is kept as processing and reconciled. It is never sent twice.

NextPayment statusPolling patterns and final states.

Before you startCopy Anchor Link

Send the promptCopy Anchor Link

Request fieldsCopy Anchor Link

ResponseCopy Anchor Link

Wait for the customerCopy Anchor Link