Mobile Money

Collect payments from customers using mobile money. The customer receives a USSD push notification to authorize the payment.

Supported Networks

Network	Country
Airtel Money	TZ
M-Pesa	TZ
Mixx by Yas	TZ
Halotel	TZ

Create Payment

POST /v1/payments
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <unique_key>

Request

{
  "payment_type": "mobile",
  "details": {
    "amount": 500,
    "currency": "TZS"
  },
  "phone_number": "255781000000",
  "customer": {
    "firstname": "FirstName",
    "lastname": "LastName",
    "email": "customer@email.com"
  },
  "webhook_url": "https://yoursite.com/webhooks/snippe",
  "metadata": {
    "order_id": "ORD-12345"
  }
}

Response

{
  "status": "success",
  "code": 201,
  "data": {
    "amount": {
      "currency": "TZS",
      "value": 500
    },
    "api_version": "2026-01-25",
    "expires_at": "2026-01-25T05:04:54.063993853Z",
    "object": "payment",
    "payment_type": "mobile",
    "reference": "9015c155-9e29-4e8e-8fe6-d5d81553c8e6",
    "status": "pending"
  }
}

Request Parameters

Required Fields

Field	Type	Description
`payment_type`	string	Must be `mobile`
`details.amount`	integer	Amount in smallest currency unit
`details.currency`	string	Currency code (`TZS`)
`phone_number`	string	Customer phone number (255XXXXXXXXX)
`customer.firstname`	string	Customer first name
`customer.lastname`	string	Customer last name
`customer.email`	string	Customer email

Optional Fields

Field	Type	Description
`webhook_url`	string	URL for webhook notifications
`metadata`	object	Custom key-value data

How It Works

Create a payment intent with the customer's phone number
Customer receives a USSD push on their phone
Customer enters their PIN to authorize
Snippe sends a webhook notification with the result
Payment expires after 4 hours if not completed

Error Responses

Validation Error (400)

{
  "status": "error",
  "code": 400,
  "error_code": "validation_error",
  "message": "amount is required"
}

Unauthorized (401)

{
  "status": "error",
  "code": 401,
  "error_code": "unauthorized",
  "message": "invalid or missing API key"
}

Mobile Money

On this page