PalmPesa API Documentation ^v1

Welcome to PalmPesa cURL Documentation

This documentation provides all the information you need to integrate with the PalmPesa API using cURL. This guide was originally constructed by Isaiah Nyalali.

Our API is designed to be straightforward, especially for common payment functionalities. For a comprehensive and live reference of all PalmPesa API endpoints, please visit the official PalmPesa API Reference on Apidog.

Getting Started: Your Essential Credentials

Before you can start using the PalmPesa API, you'll need the following details. You can typically find these in your PalmPesa developer account, often within a "Developer Options" or "API Credentials" menu:

User ID: This unique identifier is specific to your developer account and is sometimes required in the body of API requests.
API Token: This secure token is used to authenticate your requests to our API via the Authorization header.

To obtain these, you must register for an account at https://palmpesa.drmlelwa.co.tz/. After registering for an account then fill out this form and you will be provided with a unique User ID and an API Token. These credentials are essential for authenticating your requests.

Setting up cURL

To use the cURL examples in this documentation, you'll need:

cURL: Ensure you have cURL installed on your system. Most Linux/macOS systems have it pre-installed. For Windows, you can download it from curl.se.
Command Line Access: You'll need access to a terminal or command prompt to run the cURL commands.

Important: The API examples and specific details like exact Base URLs provided in this documentation are illustrative. Always refer to the official credentials and URLs provided by PalmPesa after your registration for production use.

Authentication

PalmPesa API uses Bearer Token authentication. You must include your API Token in the Authorization header for every request made to secure endpoints.

Setting Up Your API Request Header

To communicate with the PALM PESA API, you need to include an authorization header in your requests. This tells our system that you are authenticated. The header should be formatted as follows:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Replace YOUR_API_TOKEN with the actual API token you obtained from your developer account. Make sure there's a space between "Bearer" and your token. Ensure all requests are made over HTTPS.

Making API Requests: We Use POST!

For simplicity and ease of use, especially for beginners, many key API functions (particularly those highlighted in the "Core Payments" and "Transaction Management" sections below) use the POST method for sending data to our servers. However, for a full list of methods and endpoints, refer to the official PalmPesa API Reference.

Base URLs

The primary base URL for all PALM PESA API endpoints is:

https://palmpesa.drmlelwa.co.tz

The specific paths for each API function (e.g., /api/process-payment) will be appended to this base URL.

Note: The cURL examples below use the base URL https://palmpesa.drmlelwa.co.tz with paths like /api/order-status appended to it. Ensure this aligns with the production URL provided by PalmPesa.

POST 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.

Endpoint: 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

Parameter	Type	Required	Description	Example Value
`user_id`	integer	Yes	Your PalmPesa User ID.	`25`
`vendor`	string	Yes	Vendor identifier. Important: Use "TILL61103867"; do not change this number unless instructed.	`"TILL61103867"`
`order_id`	string	Yes	A unique ID for your order.	`"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.	`"Elon Musk"`
`buyer_phone`	string	Yes	The phone number of the buyer.	`"255744000000"`
`amount`	integer	Yes	The transaction amount.	`500`
`currency`	string	Yes	Currency code.	`"TZS"`
`redirect_url`	string	Yes	URL to redirect the buyer after successful payment. PUT YOUR LINK HERE.	`"https://yourdomain.com/success"`
`cancel_url`	string	Yes	URL to redirect the buyer if the payment is cancelled. PUT YOUR LINK HERE.	`"https://yourdomain.com/cancel"`
`webhook`	string	Yes	Your webhook URL for receiving payment status updates. PUT YOUR LINK HERE.	`"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", "Vifaa vya ndani").	`"Web"`
`no_of_items`	integer	Yes	The number of items in the order.	`2`

Example Request Body:

{
  "user_id": 25,
  "vendor": "TILL61103867",
  "order_id": "TEST-ORDER-100",
  "buyer_email": "musk@tesla.com",
  "buyer_name": "Elon Musk",
  "buyer_phone": "255744000000",
  "amount": 500,
  "currency": "TZS",
  "redirect_url": "PUT YOUR LINK HERE",
  "cancel_url": "PUT YOUR LINK HERE",
  "webhook": "PUT YOUR LINK HERE",
  "buyer_remarks": "Online Delivery",
  "merchant_remarks": "Starlink Kit",
  "no_of_items": 1
}

Processing the Response and Important Information

You will get a link that you can share with your customers or integrate into your application flow. The API primarily returns the payment link itself for this feature. It does not send any further direct response or status updates back to your system *immediately* through this specific API call. You should rely on your webhook and the "Get Order Status" endpoint to track final payment status.

Example Response:

{
  "error": "sharable payment link",
  "raw": {
    "payment_gateway_url": "https://tz.selcom.online/paymentgw/checkout/VVNKSzVQWFpmRDBacVFZaTRKTHlFSFlPV2pKeGxuZWNqWVA4bHB3b3VzY0RxNmpYR1E1ZWVvSnl0eXg3cFFnbTJZMko0a2dBYXJzSA=="
  }
}

cURL Example

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": "musk@tesla.com",
    "buyer_name": "Elon Musk",
    "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
  }'

POST 2. Pay Directly via Mobile Money/USSD

This endpoint allows you to initiate a direct payment from a user's mobile money account, typically via a USSD push.

Endpoint: POST https://palmpesa.drmlelwa.co.tz/api/pay-via-mobile

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description	Example Value
`user_id`	string	Yes	Your PalmPesa User ID from your dashboard.	`"2"`
`name`	string	Yes	Full name of the buyer.	`"Elon Musk"`
`email`	string	Yes	Email address of the buyer.	`"musk@tesla.com"`
`phone`	string	Yes	Phone number to receive the USSD push.	`"255744000000"`
`amount`	integer	Yes	Amount to be paid.	`500`
`transaction_id`	string	Yes	Your unique transaction identifier.	`"TXN1234567891"`
`address`	string	Yes	Address of the buyer.	`"Mbeya"`
`postcode`	string	Yes	Postcode of the buyer.	`"53127"`
`buyer_uuid`	integer	Yes	A unique identifier for the buyer on your system.	`988776`

Example Request Body:

{
  "user_id": "2",
  "name": "Elon Musk",
  "email": "musk@tesla.com",
  "phone": "255744000000",
  "amount": 500,
  "transaction_id": "TXN1234567891",
  "address": "Dar es Salaam",
  "postcode": "53127",
  "buyer_uuid": 988776
}

Processing the Response

The response from this endpoint will likely indicate the initial status of the payment (e.g., "Wallet push successful"). You might receive an order_id or a transactionReference that you can use to track the payment status using the /api/order-status endpoint.

Example Response:

{
  "message": "Payment request sent to user's phone",
  "order_id": "SELCOM17458294939723",
  "response": {
    "reference": "S19997158895",
    "transid": "TXN1745829493",
    "resultcode": "000",
    "result": "SUCCESS",
    "message": "Wallet push successful",
    "data": []
  }
}

cURL Example

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
  }'

POST 3. Get Order Status

This endpoint allows you to check the current status of a specific payment order using its order_id (which you might have received from endpoints like Pay by USSD Push or stored from your Pay by Link initiation).

Endpoint: POST https://palmpesa.drmlelwa.co.tz/api/order-status

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description	Example Value
`order_id`	string	Yes	The unique identifier of the order whose status you want to check (e.g., "SELCOM17454039012135").	`"SELCOM17458309277044"`

Example Request Body:

{
  "order_id": "SELCOM17458309277044" 
}

Responses

Example Response:

{
  "reference": "0929180109",
  "resultcode": "000",
  "result": "SUCCESS",
  "message": "Order fetch successful",
  "data": [
    {
      "order_id": "SELCOM17458309277044",
      "creation_date": "2025-04-28 12:04:00",
      "amount": "500",
      "payment_status": "COMPLETED",
      "transid": "805642413840",
      "channel": "AIRTELMONEY",
      "reference": "0929180109",
      "msisdn": "255744000000"
    }
  ]
}

cURL Example

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": "SELCOM17458309277044"
  }'

Additional API Capabilities

Beyond the core payment flows, PalmPesa offers other API functionalities. For complete details on these and other endpoints, including request/response schemas and potential GET methods, please consult the Official PalmPesa API Reference on Apidog. The examples below provide a brief overview.

POST Combined Full Payment Process

This endpoint initiates a complete payment process, typically used for direct mobile money debits or similar integrated flows where user interaction is minimal after initiation. (Consult Apidog for details).

Path: /api/process_payment/complete

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	Application/json

Request Body (Example from original spec)

Parameter	Type	Required	Description
`phone`	string	Yes	The phone number to be charged.
`amount`	integer	Yes	The amount to be charged.

Example Request:

{
  "phone": "0744000000",
  "amount": 500000
}

Responses (Example from original spec)

Example Pending Response (200 OK, but status indicates processing):

A 200 OK response from this endpoint typically means the request to process payment has been accepted and is pending. You should subsequently use the "Get Order Status" endpoint to confirm the final outcome.

{
  "status": "pending",
  "message": "Payment Pending or Failed. Please check again later.",
  "data": [
    {
      "order_id": "SELCOM17473414464923",
      "creation_date": "2025-05-15 23:39:18",
      "amount": "500000",
      "payment_status": "PENDING",
      "transid": null,
      "channel": null,
      "reference": null,
      "msisdn": null
    }
  ]
}

cURL Example

curl -X POST \
  'https://palmpesa.drmlelwa.co.tz/api/process_payment/complete' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: Application/json' \
  -d '{
    "phone": "0744000000",
    "amount": 500000
  }'

GET Get Transaction List

Retrieves a paginated list of all transactions associated with your account. (Consult Apidog for details).

Path: /api/transactions

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Query Parameters (Optional)

Parameter	Type	Description
`page`	integer	The page number for pagination.
`per_page`	integer	Number of transactions per page.

Responses (Example from original spec)

Example Success Response (200 OK):

{
"status": "success",
"message": "Transactions retrieved successfully.",
"data": {
"transactions": [
{
"id": 532,
"order_id": "SND-510000",
"amount": -510,
"channel": "Palm Pesa",
"msisdn": "0744000000",
"transid": "SNDID-41909274902633713-63d26d4719890000",
"payment_status": "completed",
"reference": "Transfer with 5% fee (Sent: TZS 500, Fee: TZS 10.00)",
"agent_id": null,
"agent_commission": "0",
"created_at": "2025-06-10 11:33:45"
},
{
"id": 522,
"order_id": "SELCOM17495353420000",
"amount": 500,
"channel": null,
"msisdn": null,
"transid": "59b50731-bda3-4a7e-99c8-861181260000",
"payment_status": null,
"reference": null,
"agent_id": null,
"agent_commission": null,
"created_at": "2025-06-10 09:02:24"
},
{
"id": 242,
"order_id": "SELCOM17474743410000",
"amount": 500,
"channel": "MPESA-TZ",
"msisdn": "255744000000",
"transid": "TXN1747470000",
"payment_status": "COMPLETED",
"reference": "0935630000",
"agent_id": null,
"agent_commission": null,
"created_at": "2025-05-17 12:32:25"
}
],
"pagination": {
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 3
}

cURL Example

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'

POST Create Palm Card

Creates a new Palm Card for the authenticated user. (Consult Apidog for details).

Path: /api/cards

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description
`pin`	string	Yes	A 4-digit PIN for the new Palm Card. Ensure it's securely handled.

Example Request:

{
  "pin": "1234"
}

Responses

Example Success Response (200 OK):

The OpenAPI spec indicates an empty object {} for success. A more practical response might include details of the created card. Clarify with PalmPesa if needed.

{}

cURL Example

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"
  }'

POST Deposit Money to Palm Card

Deposits money into the user's Palm Card. (Consult Apidog for details).

Path: /api/card/add-money

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description
`phone`	string	Yes	The mobile money phone number from which to pull funds (e.g., "0744000000").
`amount`	string	Yes	The amount to deposit. Note: Type is string in example.

Example Request:

{
  "phone": "0744000000",
  "amount": "500"
}

Responses

Example Pending Response (202 Accepted):

This response indicates the deposit request is processing. The user may need to approve the transaction on their phone. Subsequently check the transaction status or card balance.

{
  "status": "pending",
  "message": "Payment not yet completed. Please try again later.",
  "data": {
    "order_id": "SELCOM17495574740000",
    "creation_date": "2025-06-10 15:13:05",
    "amount": "500",
    "payment_status": "PENDING",
    "transid": null,
    "channel": null,
    "reference": null,
    "msisdn": null
  }
}

cURL Example

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"
  }'

POST Send Money (User to User)

Transfers money to another PalmPesa user's card. This version is based on an API specification that provides a detailed transaction response. (Consult Apidog for details).

Path: /api/send-to-card

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description
`card_number`	string	Yes	The recipient's PalmPesa card number.
`amount`	integer	Yes	The amount to send.
`pin`	string	Yes	The sender's PIN to authorize the transaction.

Example Request:

{
  "card_number": "3410020000",
  "amount": 500,
  "pin": "1234"
}

Responses

Example Success Response (200 OK):

{
  "success": true,
  "message": "Transfer completed successfully.",
  "transaction": {
    "id": 36,
    "receiver_card": "3410020000",
    "amount_sent": "500.00",
    "fee_charged": "10.00",
    "total_deducted": "510.00",
    "transaction_id": "SNDID-41909274902633713-63d26d4719894159",
    "sent_at": "10 Jun 2025, 11:33 AM"
  }
}

cURL Example

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"
  }'

POST Send Money (Card to Card)

Transfers money from the authenticated user's Palm Card to another Palm Card. This version is based on an API specification that returns a basic success response. (Consult Apidog for details).

Path: /api/send-to-card

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

Parameter	Type	Required	Description
`card_number`	string	Yes	The recipient's Palm Card number.
`amount`	integer	Yes	The amount to send.
`pin`	string	Yes	The sender's Palm Card PIN to authorize the transaction.

Example Request:

{
  "card_number": "3410020000",
  "amount": 500,
  "pin": "1234"
}

Responses

Example Success Response (200 OK from the related "send money to another palm pesa user"):

The "Send Money Palm Card To Palm Card" shares the same success response with "send money to another palm pesa user" (which also uses /api/send-to-card path).

{
  "success": true,
  "message": "Transfer completed successfully.",
  "transaction": {
    "id": 36,
    "receiver_card": "3410020000",
    "amount_sent": "500.00",
    "fee_charged": "10.00",
    "total_deducted": "510.00",
    "transaction_id": "SNDID-41909274902633713-63d26d4719894159",
    "sent_at": "10 Jun 2025, 11:33 AM"
  }
}

cURL Example

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"
  }'

POST Enable or Disable Palm Card

Toggles the status of a specific Palm Card. (Consult Apidog for details).

Path: /api/cards/{card_id}/toggle-status

Note: The {card_id} in the path must be replaced with the actual ID of the Palm Card you wish to manage (e.g., /api/cards/10/toggle-status if card ID is 10).

Headers

Parameter	Required	Example Value
Authorization	Yes	Bearer YOUR_API_TOKEN
Content-Type	Yes	application/json
Accept	Yes	application/json

Request Body

No request body is required for this endpoint. The action is performed by the POST request itself on the specific card's URL.

Responses

Disable Palm Card Success Response (200 OK):

An informative success response includes the false status for inactive card.

{
  "message": "Card status updated.",
  "is_active": false
}

Enable Palm Card Success Response (200 OK):

An informative success response includes the true status for active card.

{
  "message": "Card status updated.",
  "is_active": true
}

Example Error Response (e.g., 404 for Card not found ):

An error response includes the Card not found status.

{
  "error": "Card not found."
}

cURL Example

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'

POST Register User

Allows new users to register for a PalmPesa account. (Consult Apidog for details).

Path: /api/register

Headers

Parameter	Required	Example Value
Authorization	No Typically not required for registration. OpenAPI lists it as not required.	Bearer YOUR_TOKEN (if applicable for some specific registration flow)
Content-Type	Yes	application/json
Accept	Yes	Application/json

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Full name of the user.
`phoneNumber`	string	Yes	User's phone number (e.g., "0744000000").
`location`	string	Yes	User's location (e.g., "Dar es Salaam").
`gender`	string	Yes	User's gender (e.g., "male", "female", "other").
`role`	string	Yes	User role (e.g., "Normal"). Consult PalmPesa for available roles.
`nida_number`	string	Yes	User's National ID number.
`email`	string	Yes	User's email address (must be unique).
`password`	string	Yes	Password for the new account (min length requirements may apply).
`password_confirmation`	string	Yes	Must match the `password` field.

Example Request:

{
  "name": "Elon Musk",
  "phoneNumber": "0744000000",
  "location": "Dar es Salaam",
  "gender": "male",
  "role": "Normal",
  "nida_number": "123456789012341",
  "email": "musk@tesla.com",
  "password": "password",
  "password_confirmation": "password"
}

Responses

Example Successful Response (e.g., 201 Created):

A successful registration returns user details and an API token.

{
  "success": true,
  "message": "Registration successful.",
  "access_token": "zHeBESnUnkjOVY1Xy4CXZ2wC45hqh3YQ31w2MDgzGcd7OViVavkzMGNjiYN4J2pzMMONRxLiPKgJJUCs",
  "user": {
    "name": "Elon Musk",
    "phoneNumber": "0744000000",
    "location": "Dar es Salaam",
    "gender": "male",
    "role": "Normal",
    "nida_number": "123456789012341",
    "email": "musk@tesla.com",
    "access_token": "zHeBESnUnkjOVY1Xy4CXZ2wC45hqh3YQ31w2MDgzGcd7OViVavkzMGNjiYN4J2pzMMONRxLiPKgJJUCs",
    "updated_at": "2025-06-10T08:19:27.000000Z",
    "created_at": "2025-06-10T08:19:27.000000Z",
    "id": 79
  }
}

Example Validation Error Response (422 Unprocessable Entity):

{
  "success": false,
  "message": "Registration failed due to validation errors.",
  "errors": {
    "phoneNumber": [
      "The phone number has already been taken."
    ],
    "nida_number": [
      "The nida number has already been taken."
    ],
    "email": [
      "The email has already been taken."
    ]
  }
}

cURL Example

curl -X POST \
  'https://palmpesa.drmlelwa.co.tz/api/register' \
  -H 'Content-Type: application/json' \
  -H 'Accept: Application/json' \
  -d '{
    "name": "Elon Musk",
    "phoneNumber": "0744000000",
    "location": "Dar es Salaam",
    "gender": "male",
    "role": "Normal",
    "nida_number": "123456789012341",
    "email": "musk@tesla.com",
    "password": "password",
    "password_confirmation": "password"
  }'

POST User Login

Authenticates a user and returns an API token. (Consult Apidog for details).

Path: /api/login

Headers

Parameter	Required	Example Value
Authorization	Yes OpenAPI specifies this is required. However, login endpoints usually don't require pre-auth.	Bearer UgGnf1bYJb1vC8MoZXa7LDXcWS6sA7mxWR12MaPgr05kDowvakyzP6jBLsbs (Example value from OpenAPI)
Content-Type	Yes	application/json
Accept	Yes	Application/json

Request Body

Parameter	Type	Required	Description
`email`	string	Yes	The registered email address of the user.
`password`	string	Yes	The user's password.

Example Request:

{
  "email": "musk@tesla.com",
  "password": "password"
}

Responses

Example Successful Response (200 OK):

A login response provides user details and an API token.

{
  "success": true,
  "message": "Login successful.",
  "access_token": "zHeBESnUnkjOVY1Xy4CXZ2wC45hqh3YQ31w2MDgzGcd7OViVavkzMGNjiYN4J2pzMMONRxLiPKgJJUCs",
  "api_token": null,
  "user": {
    "id": 79,
    "name": "Elon Musk",
    "phoneNumber": "0744000000",
    "location": "Dar es Salaam",
    "gender": "male",
    "role": "Normal",
    "about_me": null,
    "profile_picture": null,
    "is_admin": 0,
    "nida_number": "123456789012341",
    "email": "musk@tesla.com",
    "email_verified_at": null,
    "created_at": "2025-06-10T08:19:27.000000Z",
    "updated_at": "2025-06-10T08:19:27.000000Z",
    "approved": 0,
    "access_token": "zHeBESnUnkjOVY1Xy4CXZ2wC45hqh3YQ31w2MDgzGcd7OViVavkzMGNjiYN4J2pzMMONRxLiPKgJJUCs"
  }
}

Example Error Response (e.g., 401 Unauthorized for bad credentials):

{
  "success": false,
  "message": "Invalid credentials."
}

cURL Example

curl -X POST \
  'https://palmpesa.drmlelwa.co.tz/api/login' \
  -H 'Content-Type: application/json' \
  -H 'Accept: Application/json' \
  -d '{
    "email": "musk@tesla.com",
    "password": "password"
  }'

Support & Resources

Get help with PalmPesa API integration, troubleshooting, and account management through our comprehensive support channels.

Support Channels

Support Channel	Contact Information	Response Time
Email Support	anoldmwinuka@gmail.com	24-48 hours
Phone Support	WhatsApp Contact	Business hours (8AM - 5PM EAT)
Documentation	palmpesa-docs.netlify.app	24/7

Common Integration Issues

Issue	Solution
Invalid API Token	Ensure your Bearer token is correctly set in the Authorization header as `Authorization: Bearer YOUR_API_TOKEN`
Phone Number Format	Use Tanzanian format (255744000000) with country code and no + sign
Webhook Not Receiving	Check your webhook URL is publicly accessible and returns 200 OK. Test with webhook.site first.
Order Status Not Updating	Mobile money payments can take several minutes to complete. Use webhooks or poll the status endpoint periodically.
Vendor ID Issues	Ensure you're using the correct vendor ID (TILL61103867) unless instructed otherwise
Redirect URL Issues	Make sure your redirect and cancel URLs are properly URL-encoded and publicly accessible

Implementation Guides

Pay by Link Implementation Step-by-step guide to implementing the Pay by Link feature, including how to generate payment links and handle customer redirects.
USSD Push Implementation Complete reference for direct mobile money payments via USSD push.
Order Status Checking Detailed instructions for implementing transaction status verification, including polling strategies and webhook integration best practices.

Additional Resources

PalmPesa Official Website Official portal for PalmPesa services, including merchant registration, account management, and latest updates about the payment platform.
Official API Reference Comprehensive technical reference for all PalmPesa API endpoints, including request/response schemas and status codes.
HTTP Status Codes Reference Comprehensive technical reference for all PalmPesa API endpoints, including request/response schemas and status codes.
cURL Documentation Official documentation for cURL command line tool, useful for testing API endpoints directly from terminal.

Isaiah's Integration Tip

API Developer & Documentation Author

When integrating with PalmPesa API, I recommend:

Always test with small amounts first (500-1000 TZS)
Implement both webhooks and manual status checking for reliability
Use unique order IDs for each transaction
Log all API requests and responses for debugging

Connect with me on LinkedIn for fintech updates!