Welcome to PalmPesa cURL Documentation
This documentation provides all the information you need to integrate with the PalmPesa API using cURL.
Originally constructed by Eagle Star Technology.
Official Reference: For a comprehensive and live reference of all endpoints, visit the
PalmPesa API Reference on Apidog.
Getting Started: Your Essential Credentials
Before using the API, obtain:
- User ID — unique identifier for your developer account
- API Token — used in Authorization header
Register at https://palmpesa.drmlelwa.co.tz/ and submit the form to receive your credentials.
Important: Always use the production credentials and URLs provided after registration. The examples here are illustrative.
Important Notes:
- Use Tanzanian phone format (e.g., starts with 06 or 07, no + sign)
- The
callback_urlmust return HTTP 200 OK quickly and be publicly reachable (test with tools like webhook.site) - After initiation, rely on your callback_url (webhook) or poll the Get Order Status endpoint using the transaction_id (or returned order_id/reference) to confirm final status (COMPLETED, FAILED, PENDING, etc.)
- Test with small amounts first (e.g., 200–1000 TZS)
Always refer to the official PalmPesa API Reference on Apidog for the latest response format, error codes, and any additional optional fields.
Authentication
PalmPesa uses Bearer Token authentication.
Header
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json
Base URL
https://palmpesa.drmlelwa.co.tz
Append endpoint paths (e.g. /api/process-payment) to this base URL.
1. Initiate Pay by LINK
This endpoint allows you to initiate a payment transaction and generate a sharable payment link. The actual payment method presented to the user via the link might vary (mobile money, card, etc.).
POST https://palmpesa.drmlelwa.co.tz/api/process-payment
Headers
| Parameter | Required | Example Value |
|---|---|---|
| Authorization | Yes | Bearer YOUR_API_TOKEN |
| Content-Type | Yes | application/json |
| Accept | Yes | application/json |
Request Body Parameters
| Parameter | Type | Required | Description | Example Value |
|---|---|---|---|---|
| user_id | integer | Yes | Your PalmPesa User ID | 25 |
| vendor | string | Yes | Vendor identifier. Important: Use "TILL61103867" unless instructed otherwise. | "TILL61103867" |
| order_id | string | Yes | A unique ID for your order (should be unique per transaction) | "TEST-ORDER-200" |
| buyer_email | string | Yes | The email address of the buyer | "youremail@gmail.com" |
| buyer_name | string | Yes | The full name of the buyer | "Sephania Nathan" |
| buyer_phone | string | Yes | The phone number of the buyer (with country code, no + sign) | "255744000000" |
| amount | integer | Yes | The transaction amount in the smallest currency unit | 500 |
| currency | string | Yes | Currency code | "TZS" |
| redirect_url | string | Yes | URL to redirect after successful payment | "https://yourdomain.com/success" |
| cancel_url | string | Yes | URL to redirect if payment is cancelled | "https://yourdomain.com/cancel" |
| webhook | string | Yes | Your webhook URL for receiving payment status updates | "https://yourdomain.com/webhook" |
| buyer_remarks | string | Yes | Any remarks from the buyer | "Test order" |
| merchant_remarks | string | Yes | Description of items/service (e.g. "Web", "Maandazi", "Simu") | "Web" |
| no_of_items | integer | Yes | The number of items in the order | 2 |
Example Request Body
JSON
{
"user_id": 25,
"vendor": "TILL61103867",
"order_id": "TEST-ORDER-100",
"buyer_email": "Sephania@eaglestar.com",
"buyer_name": "Sephania Nathan",
"buyer_phone": "255744000000",
"amount": 500,
"currency": "TZS",
"redirect_url": "https://yourdomain.com/success",
"cancel_url": "https://yourdomain.com/cancel",
"webhook": "https://yourdomain.com/webhook",
"buyer_remarks": "Online Delivery",
"merchant_remarks": "Starlink Kit",
"no_of_items": 1
}
Response Information
Important: This endpoint returns a sharable payment link in the response. It does not provide immediate final status.
Use your webhook URL or the Get Order Status endpoint to track whether the payment was completed, failed, or cancelled.
Example Response
JSON
{
"error": "sharable payment link",
"raw": {
"payment_gateway_url": "https://tz.selcom.online/paymentgw/checkout/VVNKSzVQWFpmRDBacVFZaTRKTHlFSFlPV2pKeGxuZWNqWVA4bHB3b3VzY0RxNmpYR1E1ZWVvSnl0eXg3cFFnbTJZMko0a2dBYXJzSA=="
}
}
This is a Callback Response
JSON
{"reference":"0927530628",
"resultcode":"000",
"data":[{
"order_id":"SELCOM17454039012135",
"creation_date":"2025-04-23 13:26:54",
"amount":"500",
"payment_status":"COMPLETED",
"transid":"805613901007",
"channel":"AIRTELMONEY",
"reference":"0927530628",
"msisdn":"255693662424"
}]}
cURL Example
cURL
curl -X POST \
'https://palmpesa.drmlelwa.co.tz/api/process-payment' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"user_id": 25,
"vendor": "TILL61103867",
"order_id": "TEST-ORDER-100",
"buyer_email": "Sephania@eaglestar.com",
"buyer_name": "Sephania Nathan",
"buyer_phone": "255744000000",
"amount": 500,
"currency": "TZS",
"redirect_url": "https://yourdomain.com/success",
"cancel_url": "https://yourdomain.com/cancel",
"webhook": "https://yourdomain.com/webhook",
"buyer_remarks": "Online Delivery",
"merchant_remarks": "Starlink Kit",
"no_of_items": 1
}'
2. Pay Directly via Mobile Money/USSD
POST /api/pay-via-mobile
Request Body Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| user_id | string | Yes | Your PalmPesa User ID | "2" |
| name | string | Yes | Full name of the buyer | "Sephania Nathan" |
| string | Yes | Buyer's email | "Sephania@eaglestar.com" | |
| phone | string | Yes | Phone number (with country code) | "255744000000" |
| amount | integer | Yes | Amount in TZS | 500 |
| transaction_id | string | Yes | Unique transaction ID | "TXN1234567891" |
| address | string | Yes | Buyer's address | "Dar es Salaam" |
| postcode | string | Yes | Postcode | "53127" |
| buyer_uuid | integer | Yes | Unique buyer identifier in your system | 988776 |
This is a Response
JSON
{"message":
"Payment request sent to user\u2019s phone",
"order_id":"SELCOM17458294939723",
"response":{
"reference":"S19997158895",
"transid":"TXN1745829493",
"resultcode":"000",
"result":"SUCCESS",
"message":"Wallet push successful",
"data":[]
}
}
cURL Example
cURL
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/pay-via-mobile' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"user_id": "2",
"name": "Alune Kyusa",
"email": "Alune@example.com",
"phone": "255744000000",
"amount": 500,
"transaction_id": "TXN1234567891",
"address": "Mbeya",
"postcode": "53127",
"buyer_uuid": 988776
}'
Response typically includes
order_id or reference — use these with the Order Status endpoint to track payment.
3. Get Order Status
POST /api/order-status
Request Body Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| order_id | string | Yes | The order ID to check | "PALMPESA17458309277044" |
cURL Example
cURL
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/order-status' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"order_id": PALMPESA17458309277044"
}'
This is a Response
JSON
{"reference":"0927530628",
"resultcode":"000",
"result":"SUCCESS","message":"Order fetch successful",
"data":[{
"order_id":"SELCOM17454039012135",
"creation_date":"2025-04-23 13:26:54",
"amount":"500",
"payment_status":"COMPLETED",
"transid":"805613901007",
"channel":"AIRTELMONEY",
"reference":"0927530628",
"msisdn":"255693662424"
}]}
Look for
payment_status in the response data array (e.g. "COMPLETED", "PENDING", "FAILED").
Get Transaction List
GET /api/transactions?page=1&per_page=20
Query Parameters (optional)
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number |
| per_page | integer | Items per page |
cURL Example
cURL
curl -X GET 'https://palmpesa.drmlelwa.co.tz/api/transactions?page=1&per_page=20' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Webhook Payment using phone number
The Result May
This endpoint initiates a direct payment request to the user's mobile money wallet (typically via USSD push or prompt). The user will receive a payment prompt on their phone to approve the transaction.
Remember you can monitor the payment status via your callback_url (webhook) or by polling the Get Order Status endpoint using the provided transaction_id.
POST https://palmpesa.drmlelwa.co.tz/api/palmpesa/initiate
Headers
| Parameter | Required | Example Value |
|---|---|---|
| Authorization | Yes | Bearer YOUR_API_TOKEN |
| Content-Type | Yes | application/json |
| Accept | Yes (recommended) | application/json |
Request Body Parameters
| Parameter | Type | Required | Description | Example Value |
|---|---|---|---|---|
| name | string | Yes | Full name of the payer / buyer | "Sara John" |
| string | Yes | Email address of the payer | "john@example.com" | |
| phone | string | Yes | Phone number to receive the payment prompt (Tanzania format with country code, no +) | "0693662424" |
| amount | integer / number | Yes | Amount to charge in TZS | 200 |
| transaction_id | string | Yes | Your unique transaction / order identifier | "2775" |
| address | string | Yes | Address or location of the payer | "Dar es Salaam" |
| postcode | string | Yes | Postcode / postal code | "11111" |
| callback_url | string | Yes | Your server webhook / callback URL to receive payment status updates (must be publicly accessible) | "http://anord.site/your-test-url" |
Example Request Body
JSON
{
"name": "Sara John",
"email": "john@example.com",
"phone": "0693662424",
"amount": 200,
"transaction_id": "2775",
"address": "Dar es Salaam",
"postcode": "11111",
"callback_url": "http://anord.site/your-test-url"
}
cURL Example
cURL
curl --location --request POST 'https://palmpesa.drmlelwa.co.tz/api/palmpesa/initiate' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Sara John",
"email": "john@example.com",
"phone": "0693662424",
"amount": 200,
"transaction_id": "2775",
"address": "Dar es Salaam",
"postcode": "11111",
"callback_url": "http://anord.site/your-test-url"
}'
Response when Payment initiated
Store this order id for the safety of transaction tracking (Make sure you also store tihs order)
JSON
{"message":"Payment initiated. Processing will continue asynchronously.",
"order_id":"PALMPESA17682869972044"}
This is a Callback Response
JSON
{
"order_id": "PALMPESA17683440586334",
"payment_status": "PENDING"
}
Palm Card Operations
Create Palm Card
POST /api/cards
cURL – Create Card
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/cards' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"pin": "1234"}'
Deposit Money to Palm Card
POST /api/card/add-money
cURL – Add Money
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/card/add-money' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"phone": "0744000000",
"amount": "500"
}'
Toggle Card Status (Enable/Disable)
POST /api/cards/{card_id}/toggle-status
cURL – Toggle Status
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/cards/10/toggle-status' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Send Money (Card → Card)
POST /api/send-to-card
Request Body Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| card_number | string | Yes | Recipient Palm Card number | "3410020000" |
| amount | integer | Yes | Amount to send | 500 |
| pin | string | Yes | Sender's 4-digit PIN | "1234" |
cURL Example
cURL
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/send-to-card' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"card_number": "3410020000",
"amount": 500,
"pin": "1234"
}'
User Registration & Login
Register New User
POST /api/register
cURL – Register
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/register' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"name": "Sephania Nathan",
"phoneNumber": "0744000000",
"location": "Dar es Salaam",
"gender": "male",
"role": "Normal",
"nida_number": "123456789012341",
"email": "Sephania@eaglestar.com",
"password": "password",
"password_confirmation": "password"
}'
User Login
POST /api/login
cURL – Login
curl -X POST 'https://palmpesa.drmlelwa.co.tz/api/login' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"email": "Sephania@eaglestar.com",
"password": "password"
}'
Support & Resources
| Channel | Contact | Response Time |
|---|---|---|
| anoldmwinuka@gmail.com | 24-48 hours | |
| (255)0693662424 | Business hours (8AM–5PM EAT) | |
| Documentation | palmpesa-docs.netlify.app | 24/7 |
Integration Tip
- Test with small amounts (500–1000 TZS) first
- Implement both webhooks + status polling
- Use unique order IDs
- Log requests/responses