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-dev.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-dev.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": "node",
      "args": ["/ABSOLUTE/PATH/TO/tunzaa_mcp/dist/index.js"]
    }
  }
}

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/api/v1/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/api/v1/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/api/v1/payments/check-status/:transactionID" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Response

{
  "transactionID": "TXN_12345",
  "status": "COMPLETED",
  "message": "Transaction successful"
}

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/api/v1/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/api/v1/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/api/v1/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/api/v1/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/api/v1/installments/:plan_id/cancel" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Response

{
  "plan_id": 1001,
  "message": "Plan deleted successfully",
  "status": "cancelled"
}