Snippe Mobile Money and Disbursements
Collect mobile money through USSD prompts and send secure mobile or bank payouts.
Authentication
Secure your API requests with API key authentication.
API Key Authentication
All API requests require authentication using your unique API key. Include your API key in the request header for all API calls.
Security Warning
⚠ Never expose your API key publicly or commit it to version control.
Header Format
x-api-key: YOUR_API_KEY
Example Request
curl -X POST "https://makinisoftpay.com/api/v1/public/payments/initiate/" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"order_id": "13ff2edf-f777-471e-a314-596a7045ef3b",
"buyer_email": "[email protected]",
"buyer_name": "John Doe",
"buyer_phone": "0658989629",
"amount": 1000
}'
Getting Your API Key
- Sign up or log in to your Makinisoftpay dashboard
- Navigate to the settings section
- Rotate a new API key and copy your generated key
- Store the key securely in environment variables
Best Practices
- Store API keys in environment variables
- Use separate keys for dev and production
- Rotate keys regularly
- Monitor usage for unauthorized access
Quick Start Guide
Get started with MakinisoftPay in just a few simple steps.
Generate API Key
Log in to your dashboard and generate your API key from the settings section.
Initiate Payment
Use the API endpoint below to create a payment request.
POST /api/v1/public/payments/initiate/
Confirm Payment
The customer receives a USSD prompt to authorize the payment.
Overview
Accept payments from all major Tanzanian mobile money operators including M-Pesa, Airtel Money, M-Pesa, Mixx by Yas, and Halotel. Customers receive a USSD prompt on their mobile device to authorize payments.
Create Payment
POST /api/v1/public/payments/initiate/
Headers
{
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| order_id | string | Yes | Unique transaction ID |
| buyer_email | string | Yes | Payer's email |
| buyer_name | string | Yes | Full name |
| buyer_phone | string | Yes | Format: 07XXXXXXXX |
| amount | number | Yes | Amount in TZS |
| webhook_url | string | No | Callback URL |
Example Request
curl -X POST "https://makinisoftpay.com/api/v1/public/payments/initiate/" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"order_id": "13ff2edf-f777-471e-a314-596a7045ef3b",
"buyer_email": "[email protected]",
"buyer_name": "John Doe",
"buyer_phone": "0658989629",
"amount": 1000,
"webhook_url": "https://your-domain.com/webhook"
}'
Success Response
{
"success": true,
"order_id": "13ff2edf-f777-471e-a314-596a7045ef3b",
"reference": "039b18c9-7bc0-4313-b8d8-2e1f1aa9ac9f",
"status": "PENDING",
"amount": "1000.00",
"merchant_amount": "950.63",
"platform_fee": "24.37"
}
Error Response
{
"status": "error",
"message": "Invalid API Key or request payload"
}
Python Example
import requests
url = "https://makinisoftpay.com/api/v1/public/payments/initiate/"
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}
payload = {
"order_id": "13ff2edf-f777-471e-a314-596a7045ef3b",
"buyer_email": "[email protected]",
"buyer_name": "John Doe",
"buyer_phone": "0658989629",
"amount": 1000
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
JavaScript Example
const response = await fetch(
'https://makinisoftpay.com/api/v1/public/payments/initiate/',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
order_id: '13ff2edf-f777-471e-a314-596a7045ef3b',
buyer_email: '[email protected]',
buyer_name: 'John Doe',
buyer_phone: '0658989629',
amount: 1000
})
}
);
const data = await response.json();
console.log(data);
Mobile Money and Bank Disbursements
Send funds from a MakinisoftPay wallet through Snippe. The minimum payout is TZS 5,000. The payout amount plus the configured withdrawal fee is reserved before the provider request.
Merchant endpoint
POST /api/v1/merchant/disbursement/ GET /api/v1/merchant/disbursement/
Authenticate with x-api-key. Merchants can only debit and list their own wallet payouts.
Mobile money payout
curl -X POST "https://makinisoftpay.com/api/v1/merchant/disbursement/" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"order_id": "c5f42bc1-389e-4ad0-a5d6-78723c7eef36",
"channel": "mobile",
"recipient_name": "Jane Customer",
"phone_number": "0755123456",
"amount": 5000,
"narration": "Merchant withdrawal"
}'Bank transfer payout
curl -X POST "https://makinisoftpay.com/api/v1/merchant/disbursement/" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"order_id": "a8b85f44-5fa2-49a4-8b2d-c436d98b69b5",
"channel": "bank",
"recipient_name": "Jane Customer",
"recipient_bank": "NMB",
"recipient_account": "0200000000",
"amount": 5000,
"narration": "Supplier settlement"
}'Payout lifecycle and safety
- PROCESSING means Snippe accepted the payout and final confirmation is pending.
- SUCCESS means a completed response or signed completion webhook was processed.
- FAILED means the payout was definitively rejected; reserved wallet funds are refunded once.
- Reuse the same
order_idfor a safe retry. Never create a new order ID while the original payout is processing. - Bank codes must be one of the supported Tanzanian bank codes shown in the payout form.
Payment Links
Create hosted payment pages for subscriptions, donations, invoices, bills, events, services, and other payment purposes.
Merchant Procedure
- Log in to the merchant dashboard.
- Open Payment Links & Embeds from the sidebar.
- Click Payment Link and choose the purpose, billing type, amount, description, webhook URL, and success URL.
- Save and preview the payment page.
- Copy the generated URL or QR code and share it with anyone who needs to pay.
Share and QR Payment
Each payment link includes a public URL and QR code. Customers can open the link or scan the QR code, enter their name, email, phone number, and amount when enabled, then approve the mobile money payment prompt.
https://makinisoftpay.com/pay/YOUR_LINK_TOKEN/
Common Uses
Embedded Payments
Embedded payments let a 3PP, website, billing portal, school portal, donation page, or partner checkout collect payments without redirecting users away from the page.
Merchant Procedure
- Log in to the merchant dashboard.
- Open Payment Links & Embeds from the sidebar.
- Click Embedded Payment and configure the purpose, amount, billing type, description, webhook URL, and success URL.
- Save and preview the embedded checkout.
- Copy the iframe code and paste it into the 3PP website or app page.
- Use Analytics to review views, attempts, successful payments, failed payments, and total volume.
- Edit the embed any time or disable it to stop accepting payments.
Embed Code
The dashboard generates an iframe snippet for each embedded payment.
<iframe src="https://makinisoftpay.com/embed/pay/YOUR_EMBED_TOKEN/" width="100%" height="620" style="border:0;border-radius:8px;" loading="lazy"></iframe>
Payment Link and Embed Plans
Plans control the total number of payment links and embedded payments a merchant can create.
Free
Up to 5 links/embeds.
Growth
Up to 100 links/embeds. Merchants can buy this upgrade when they need more campaigns, billers, or partner pages.
Unlimited
Unlimited links/embeds for high-volume merchants and 3PP integrations.
Upgrade Flow
- Open Payment Links & Embeds in the dashboard.
- Check the current usage and plan limit shown above the list.
- Select View upgrade plans.
- Buy the Growth or Unlimited upgrade through the merchant support or billing process.
- After approval, the new limit applies to future links and embedded payments.
Verify Payment Status
Query payment transaction status and details.
Overview
Retrieve comprehensive payment status and transaction details. This endpoint provides payment status, reference numbers, timestamps, and channel information.
Verify a Payment
POST /api/v1/public/payments/verify/
x-api-key: YOUR_API_KEY
JSON field: reference (required UUID returned when the payment was initiated)
Example Request
curl -X POST "https://makinisoftpay.com/api/v1/public/payments/verify/" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"reference": "039b18c9-7bc0-4313-b8d8-2e1f1aa9ac9f"}'
Success Response
{
"order_id": "8a2573da-8fb1-4046-b404-5bff2e9a4855",
"reference": "039b18c9-7bc0-4313-b8d8-2e1f1aa9ac9f",
"status": "SUCCESS",
"amount": "2800.00",
"merchant_amount": "2661.75",
"platform_fee": "68.25"
}
Response Field Descriptions
| Field | Description |
|---|---|
| order_id | Your unique order identifier |
| amount | Payment amount in TZS |
| status | Payment status (SUCCESS, PENDING, FAILED) |
| reference | Payment reference number |
| merchant_amount | Amount received by merchant |
| platform_fee | Platform transaction fee |
Payment Status Values
- SUCCESS – Payment completed
- PENDING – Awaiting confirmation
- FAILED – Payment failed or cancelled
Python Example
import requests
url = "https://makinisoftpay.com/api/v1/public/payments/verify/"
headers = {
"x-api-key": "YOUR_API_KEY"
}
payload = {
"reference": "039b18c9-7bc0-4313-b8d8-2e1f1aa9ac9f"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
JavaScript Example
const reference = "039b18c9-7bc0-4313-b8d8-2e1f1aa9ac9f";
const response = await fetch(
"https://makinisoftpay.com/api/v1/public/payments/verify/",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
},
body: JSON.stringify({ reference })
}
);
const data = await response.json();
console.log(data);
Webhooks
Receive payment results from MakinisoftPay and reconcile them safely.
⚡ Real-time Notifications
MakinisoftPay queues a callback when a payment reaches SUCCESS or FAILED. Delivery is retried for temporary errors, so your handler must be idempotent.
🔗 Webhook Setup
Include a public HTTPS webhook_url
when initiating the payment:
{
"order_id": "4c41955b-7f15-4e95-af92-712c7848dd76",
"amount": 1000,
"webhook_url": "https://your-domain.com/payment-webhook"
}
🔐 Secure Verification
Store the stable delivery identifier to prevent duplicate processing, then confirm the final state through the authenticated payment verification endpoint:
X-Webhook-ID: DELIVERY_UUID
📦 Webhook Payload
{
"order_id": "4c41955b-7f15-4e95-af92-712c7848dd76",
"reference": "89e92bc9-dda9-4774-96d5-5715d2a503d4",
"payment_status": "SUCCESS",
"amount": 1000.0,
"merchant_amount": 950.63,
"platform_fee": 24.37,
"metadata": {}
}
🚀 Best Practices
- ✔️ Use a public HTTPS endpoint
- ✔️ Return an HTTP 2xx response promptly
- ✔️ Reconcile final status with the verify API
- ✔️ Deduplicate callbacks using X-Webhook-ID
- ✔️ Process business work asynchronously
- ✔️ Log delivery IDs and response outcomes