Mobile Money Disbursements

Send money directly to mobile money accounts across all major Tanzanian networks.

Supported Networks

Network	Provider Code
Airtel Money	TZ-AIRTEL-B2C
M-Pesa / Vodacom	TZ-VODACOM-B2C
Tigo Pesa	TZ-TIGO-B2C
HaloPesa	TZ-HALOTEL-B2C

Create Payout (Saved Credential)

Send money to a previously saved and verified credential.

POST https://api.snippe.sh/v1/payouts
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: unique-request-id-123

Request

{
  "amount": 50000,
  "narration": "Salary payment for January",
  "channel": "mobile",
  "credential_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "employee_id": "EMP-001",
    "payroll_id": "PAY-2026-01"
  }
}

Response

{
  "status": 201,
  "data": {
    "object": "payout",
    "api_version": "2026-01-25",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "reference": "po_a1b2c3d4e5f6",
    "external_reference": null,
    "status": "pending",
    "source": "api",
    "channel": {
      "type": "mobile_money",
      "provider": "airtel"
    },
    "recipient": {
      "name": "John Doe",
      "phone": "255712345678",
      "bank": null,
      "account": null
    },
    "amount": {
      "value": 50000,
      "currency": "TZS"
    },
    "fees": {
      "value": 1500,
      "currency": "TZS"
    },
    "total": {
      "value": 51500,
      "currency": "TZS"
    },
    "narration": "Salary payment for January",
    "failure_reason": null,
    "metadata": {
      "employee_id": "EMP-001",
      "payroll_id": "PAY-2026-01"
    },
    "completed_at": null,
    "created_at": "2026-01-24T10:00:00Z"
  }
}

Create Payout (Any Recipient)

Send money to any mobile money recipient without a saved credential.

POST https://api.snippe.sh/v1/payouts/send
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: unique-request-id-456

Request

{
  "amount": 100000,
  "channel": "mobile",
  "recipient_name": "Jane Smith",
  "recipient_phone": "255754321098",
  "narration": "Contract payment",
  "metadata": {
    "contract_id": "CTR-2026-001"
  }
}

Response

{
  "status": 201,
  "data": {
    "object": "payout",
    "api_version": "2026-01-25",
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "reference": "po_x9y8z7w6v5u4",
    "status": "pending",
    "source": "api",
    "channel": {
      "type": "mobile_money",
      "provider": "vodacom"
    },
    "recipient": {
      "name": "Jane Smith",
      "phone": "255754321098",
      "bank": null,
      "account": null
    },
    "amount": {
      "value": 100000,
      "currency": "TZS"
    },
    "fees": {
      "value": 1500,
      "currency": "TZS"
    },
    "total": {
      "value": 101500,
      "currency": "TZS"
    },
    "narration": "Contract payment",
    "metadata": {
      "contract_id": "CTR-2026-001"
    },
    "created_at": "2026-01-24T10:00:00Z"
  }
}

Request Parameters

Required Fields

Field	Type	Description
`amount`	integer	Amount in smallest currency unit (TZS)
`channel`	string	Must be `mobile`
`narration`	string	Description/reason for payout

For Saved Credential Payouts

Field	Type	Description
`credential_id`	string	UUID of saved credential (optional, uses default if not provided)

For Direct Payouts

Field	Type	Description
`recipient_name`	string	Full name of recipient
`recipient_phone`	string	Phone number (format: 255XXXXXXXXX)

Optional Fields

Field	Type	Description
`metadata`	object	Custom key-value data

Get Payout Status

GET https://api.snippe.sh/v1/payouts/{reference}
Authorization: Bearer <api_key>

Response

{
  "status": 200,
  "data": {
    "object": "payout",
    "api_version": "2026-01-25",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "reference": "po_a1b2c3d4e5f6",
    "external_reference": "TBP-123456789",
    "status": "completed",
    "source": "api",
    "channel": {
      "type": "mobile_money",
      "provider": "airtel"
    },
    "recipient": {
      "name": "John Doe",
      "phone": "255712345678"
    },
    "amount": {
      "value": 50000,
      "currency": "TZS"
    },
    "fees": {
      "value": 1500,
      "currency": "TZS"
    },
    "total": {
      "value": 51500,
      "currency": "TZS"
    },
    "narration": "Salary payment for January",
    "failure_reason": null,
    "completed_at": "2026-01-24T10:05:00Z",
    "created_at": "2026-01-24T10:00:00Z"
  }
}

List Payouts

GET https://api.snippe.sh/v1/payouts?channel=mobile&limit=20
Authorization: Bearer <api_key>

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (max 100)
`offset`	integer	0	Pagination offset
`status`	string	-	Filter by status
`channel`	string	-	Filter by channel (`mobile`)
`start`	string	-	Start date (YYYY-MM-DD)
`end`	string	-	End date (YYYY-MM-DD)

Calculate Fee

GET https://api.snippe.sh/v1/payouts/fee?amount=50000
Authorization: Bearer <api_key>

Response

{
  "status": 200,
  "data": {
    "amount": 50000,
    "fee_amount": 1500,
    "total_amount": 51500,
    "currency": "TZS"
  }
}

Error Handling

Insufficient Balance

{
  "status": 400,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance to process payout"
  }
}

Invalid Phone Number

{
  "status": 400,
  "error": {
    "code": "validation_error",
    "message": "Invalid phone number format"
  }
}

Credential Not Found

{
  "status": 404,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

Webhook Events

Event	Description
`payout.completed`	Payout successful
`payout.failed`	Payout failed
`payout.reversed`	Payout reversed

Mobile Money Disbursements

On this page