Tunzaa Pay Onboarding

Introduction

Welcome to the Tunzaa Pay API documentation. We provide a simple yet powerful REST API to accept payments, manage subscriptions, and handle payouts across Africa.

Our API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://pay.tunzaa.co.tz/api/v1

Authentication

The Tunzaa API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Your API keys accept key-value pairs of api_key and secret_key. Ensure you keep your keys secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the basic auth username.

cURL Example

curl --location 'https://pay.tunzaa.co.tz/api/v1/checkout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "amount": 1000,
    "msisdn": "255700000000",
    "reference": "ORDER-123"
}'

AI Integration (MCP)

Tunzaa Pay supports the Model Context Protocol (MCP), allowing you to integrate directly with AI assistants like Claude Desktop, Cursor, and Windsurf.

Why use MCP?

By configuring the MCP server, you give your AI context about the Tunzaa API, enabling it to write integration code, debug errors, and answer questions specifically for your codebase.

Config Fileclaude_desktop_config.json

{
  "mcpServers": {
    "tunzaa": {
      "command": "npx",
      "args": ["-y", "github:Tunzaa/tunzaa_mcp"]
    }
  }
}

Authentication

Authenticate your requests using your API Key and Secret.

Get Access Token

Method: POST

POST

/accounts/request/token

Exchange your API credentials for a time-limited Bearer token.

Request

curl -X POST "https://pay.tunzaa.co.tz/accounts/request/token" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "secret_key": "YOUR_SECRET_KEY"
}'

Response

{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Payments

Initiate and track mobile money transactions.

Initiate Payment

Method: POST

POST

/payments/initiate-payment

Trigger a USSD push to the customer's mobile device.

Request

curl -X POST "https://pay.tunzaa.co.tz/payments/initiate-payment" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_msisdn": "255700000000",
  "amount": "1000",
  "reference": "ORDER-123"
}'

Response

{
  "statusCode": 202,
  "success": true,
  "message": "Payment request accepted",
  "transactionID": "TXN_12345"
}

Check Payment Status

Method: GET

GET

/payments/check-status/:transactionID

Verify the final status of a transaction.

Parameter	Type	Description
transactionIDRequired	string	The ID returned from initiation

Request

curl -X GET "https://pay.tunzaa.co.tz/payments/check-status/:transactionID" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Response

{
  "statusCode": 200,
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "transactionID": "TXN_12345",
    "status": "COMPLETED"
  }
}

Installment Plans

Manage Buy Now Pay Later (BNPL) plans.

Create Plan

Method: POST

POST

/installments/create

Create a new installment plan for a customer.

Request

curl -X POST "https://pay.tunzaa.co.tz/installments/create" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "255700000000",
    "address": "Dar es Salaam"
  },
  "name": "Samsung S20",
  "description": "Smartphone purchase",
  "total_amount": 500000,
  "payment_frequency": "monthly",
  "start_date": "2024-01-01",
  "end_date": "2024-06-01"
}'

Response

{
  "message": "Installment plan created",
  "plan_id": 1001,
  "status": "active"
}

List Plans

Method: POST

POST

/installments

Retrieve a paginated list of installment plans.

Request

curl -X POST "https://pay.tunzaa.co.tz/installments" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "from": 0,
  "limit": 20
}'

Response

[
  {
    "plan_id": 1001,
    "name": "Samsung S20",
    "status": "active"
  }
]

Get Plan Details

Method: GET

GET

/installments/:plan_id

Get detailed information about a specific plan.

Parameter	Type	Description
plan_idRequired	number	-

Request

curl -X GET "https://pay.tunzaa.co.tz/installments/:plan_id" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Response

{
  "plan_id": 1001,
  "name": "Samsung S20",
  "status": "active",
  "installments": []
}

Update Plan

Method: PUT

PUT

/installments/:plan_id/update

Modify an existing plan's details.

Parameter	Type	Description
plan_idRequired	number	-

Request

curl -X PUT "https://pay.tunzaa.co.tz/installments/:plan_id/update" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {
    "name": "Samsung S21"
  }
}'

Response

{
  "plan_id": 1001,
  "message": "Plan updated successfully"
}

Cancel Plan

Method: DELETE

DELETE

/installments/:plan_id/cancel

Terminate an installment plan.

Parameter	Type	Description
plan_idRequired	number	-

Request

curl -X DELETE "https://pay.tunzaa.co.tz/installments/:plan_id/cancel" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Response

{
  "message": "Plan and its installments have been cancelled successfully.",
  "plan_id": 353095,
  "plan_status": "cancelled",
  "installments_updated": 4
}

How Callbacks Work

Configure your callback URL in merchant settings to receive automatic transaction status updates.

Callback Process

Transaction Status Changes: When a payment completes or fails
Tunzaa Pay Sends POST: To your configured callback URL
Your System Processes: Handle the update and respond with 200 OK
Retry on Failure: Up to 5 attempts if response isn't 200 OK

Callbacks

Transaction status notifications sent from Tunzaa Pay to your system.

Transaction Status Callback

Method: POST

POST

https://your-domain.com/callback-url

Tunzaa Pay sends POST requests to your callback URL when transaction status changes occur.

Parameter	Type	Description
transaction_idRequired	string	Unique identifier for the transaction on Tunzaa Pay
reference_idRequired	string	Reference for the transaction on the merchant's system
statusRequired	string	Current status of the transaction (COMPLETED, FAILED)
amountRequired	string	Transaction amount
payment_date	string	Payment date (Format: YYYY-MM-DD HH:mm:ss)
timestampRequired	string	When the callback was sent (Format: YYYY-MM-DD HH:mm:ss)

Callback Payload

This is what you'll receive from Tunzaa Pay

{
  "transaction_id": "TXNVV3BHMU",
  "reference_id": "REF12345",
  "status": "COMPLETED",
  "amount": "1500.00",
  "payment_date": "2024-11-25 14:30:45",
  "timestamp": "2024-11-25 16:45:10"
}