Payments

Collect Payment

Initiate a mobile money collection from a customer. A push prompt is sent to their phone and they approve the payment.

POST

https://api.auraxpay.net/v1/payments

Requires payments.create permission

⚠️Minimum amount: 1,000 TZS. Requests below this are rejected by the mobile money network with a 400 Not Acceptable error. There is no sandbox — real money moves on every transaction.

Request body

Parameter	Type	Required	Description
amount	integer	required	Amount in TZS. Minimum 1,000. Maximum 10,000,000.
channel	string	required	Payment channel: MPESA, AIRTEL_MONEY, TIGO_PESA, HALOPESA, CARD_VISA, CARD_MASTERCARD
buyerPhone	string	required	Customer phone in E.164 format. Must match the selected channel network. E.g. +255712345678
buyerName	string	required	Full name of the customer. 1–100 characters.
buyerEmail	string	optional	Customer email address. Used for receipts.
description	string	optional	Short description of what was purchased. Max 500 characters.
idempotencyKey	string	optional	Unique key to prevent duplicate charges. Max 64 chars. Recommended for retries.
metadata	object	optional	Key-value pairs (string → string) attached to the transaction object. Returned as-is.

Example request

curl -X POST https://api.auraxpay.net/v1/payments \
  -H "Content-Type: application/json" \
  -H "x-api-key: axp_live_YOUR_KEY" \
  -d '{
    "amount": 25000,
    "channel": "MPESA",
    "buyerPhone": "+255712345678",
    "buyerName": "Amina Hassan",
    "buyerEmail": "amina@example.com",
    "description": "Subscription - Pro Plan",
    "idempotencyKey": "order_9f2a1b3c",
    "metadata": {
      "orderId": "ORD-1042",
      "userId": "usr_abc123"
    }
  }'

Response

Returns 201 Created on success with the transaction object at PENDING status.

Response 201

{
  "success": true,
  "transaction": {
    "id": "txn_01j2k3m4n5p6q7r8s9t0",
    "reference": "AXP-SXSZF5H6",
    "type": "COLLECTION",
    "amount": 25000,
    "fee": 0,
    "netAmount": 25000,
    "channel": "MPESA",
    "status": "PENDING",
    "buyerPhone": "+255712345678",
    "buyerName": "Amina Hassan",
    "buyerEmail": "amina@example.com",
    "description": "Subscription - Pro Plan",
    "metadata": {
      "orderId": "ORD-1042",
      "userId": "usr_abc123"
    },
    "createdAt": "2025-06-09T14: 30: 00.000Z",
    "updatedAt": "2025-06-09T14: 30: 00.000Z"
  }
}

💡The transaction starts as PENDING. Listen for the payment.completed webhook to confirm funds received — do not fulfill orders based on PENDING status alone.

Idempotency

Pass idempotencyKey with a unique value per payment attempt. If you retry the same request with the same key within 24 hours, Aurax Pay returns the original transaction instead of creating a duplicate charge.

Use your own order ID or a UUID as the idempotency key.

Phone number format

All phone numbers must be in E.164 format with the Tanzania country code:

Network	Example	Channel value
Vodacom (M-Pesa)	+255712345678	MPESA
Tigo (Tigo Pesa)	+255652345678	TIGO_PESA
Airtel	+255682345678	AIRTEL_MONEY
Halotel	+255622345678	HALOPESA

Common errors

Status	Message	Fix
400	Not Acceptable	Amount is below 1,000 TZS minimum, or phone number does not match the channel network
400	Validation failed	Missing required field or invalid phone format — must be E.164 (+255XXXXXXXXX)
401	Invalid API key	Key not found or revoked — generate a new one from the dashboard
409	Conflict	idempotencyKey reused with different parameters