Initiate a payment

POST 
https://core-prod.malipopay.co.tz/api/v1/payment

Creates a new payment intent (collection or disbursement) for the project.

Request

application/json

Body

Bodyrequired

modestringrequired
Direction/type of the payment.
Possible values: [PAYOUT, CHARGE, REFUND]
Example: CHARGE
amountnumberrequired
Amount in the smallest currency unit (e.g. TZS).
Example: 1000
referencestringnullable
Optional merchant reference. Left empty for server-generated.
Example: ORDER-2026-0091
currencystringnullable
Three-letter currency code. Defaults to TZS.
Possible values: [TZS, USD, NGN]
Example: TZS
paymentMethodDetails objectrequired

typestringrequired

Payment method channel.

Possible values: [TIGOPESA_TZ, MPESA_TZ, HALOPESA_TZ, HALOPESA_TZ_PUSH, AIRTELMONEY_TZ, TIGOPESA_TZ_PUSH, MPESA_TZ_PUSH, AIRTELMONEY_TZ_PUSH, EASYPESA_TZ, EASYPESA_TZ_PUSH, CARD, LIPA_NUMBER, LIPA_NUMBER_PUSH]

Example: MPESA_TZ_PUSH

phoneNumberstringrequired

Customer phone number (255XXXXXXXXX).

Example: 255742200105

cardNumbernumber

Card PAN (CARD only).

expiryMonthnumber

Card expiry month (CARD only).

expiryYearnumber

Card expiry year (CARD only).

holderNamestring

Name on the card (CARD only).

brandstring

Card brand, e.g. VISA, MASTERCARD (CARD only).

cvcnumber

Card CVC (CARD only).

customer object
emailemail
Example: jane@example.com
phoneNumberstring
Example: 255742200105
firstnamestring
Example: JANE
lastnamestring
Example: DOE
billingAddress object
addressstring
Example: Mikocheni, Plot 14
alternativeAddressstring
Example:
citystring
Example: Dar es Salaam
regionstring
Example: Dar es Salaam
postcodestring
Example: 14112
countrystring
Example: TZ

Example (auto)

{
  "mode": "CHARGE",
  "amount": 1000,
  "reference": "ORDER-2026-0091",
  "currency": "TZS",
  "paymentMethodDetails": {
    "type": "MPESA_TZ_PUSH",
    "phoneNumber": "255742200105",
    "cardNumber": 0,
    "expiryMonth": 0,
    "expiryYear": 0,
    "holderName": "string",
    "brand": "string",
    "cvc": 0
  },
  "customer": {
    "email": "jane@example.com",
    "phoneNumber": "255742200105",
    "firstname": "JANE",
    "lastname": "DOE",
    "billingAddress": {
      "address": "Mikocheni, Plot 14",
      "alternativeAddress": "",
      "city": "Dar es Salaam",
      "region": "Dar es Salaam",
      "postcode": "14112",
      "country": "TZ"
    }
  }
}

Responses

201

Payment initiated successfully

application/json

Schema

Schema

successbooleanrequired
Example: true
codeintegerrequired
MALIPOPAY-specific status code (see error codes reference)
Example: 800
messagestringrequired
Example: Operation completed successfully
data object

Endpoint-specific payload

property name*any

Endpoint-specific payload

Example (auto)

{
  "success": true,
  "code": 800,
  "message": "Operation completed successfully",
  "data": {}
}

400

Bad request or validation error

application/json

Schema

Schema

codeint32required
messagestringrequired

Example (auto)

{
  "code": 0,
  "message": "string"
}

401

Unauthorized

application/json

Schema

Schema

codeint32required
messagestringrequired

Example (auto)

{
  "code": 0,
  "message": "string"
}

500

Internal server error

application/json

Schema

Schema

codeint32required
messagestringrequired

Example (auto)

{
  "code": 0,
  "message": "string"
}

Authorization: apiToken

name: apiTokentype: apiKeyin: headerdescription: Project API key. Get yours from the Malipopay dashboard under Settings → API Keys.

• curl
• python
• nodejs
• php
• java
• go

• CURL

curl -L 'https://core-prod.malipopay.co.tz/api/v1/payment' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'apiToken: <apiToken>' \
--data-raw '{
  "mode": "CHARGE",
  "amount": 1000,
  "reference": "ORDER-2026-0091",
  "currency": "TZS",
  "paymentMethodDetails": {
    "type": "MPESA_TZ_PUSH",
    "phoneNumber": "255742200105",
    "cardNumber": 0,
    "expiryMonth": 0,
    "expiryYear": 0,
    "holderName": "string",
    "brand": "string",
    "cvc": 0
  },
  "customer": {
    "email": "jane@example.com",
    "phoneNumber": "255742200105",
    "firstname": "JANE",
    "lastname": "DOE",
    "billingAddress": {
      "address": "Mikocheni, Plot 14",
      "alternativeAddress": "",
      "city": "Dar es Salaam",
      "region": "Dar es Salaam",
      "postcode": "14112",
      "country": "TZ"
    }
  }
}'

Request

Base URL

https://core-prod.malipopay.co.tz

Auth

apiToken

Body required

{
  "mode": "CHARGE",
  "amount": 1000,
  "reference": "ORDER-2026-0091",
  "currency": "TZS",
  "paymentMethodDetails": {
    "type": "MPESA_TZ_PUSH",
    "phoneNumber": "255742200105",
    "cardNumber": 0,
    "expiryMonth": 0,
    "expiryYear": 0,
    "holderName": "string",
    "brand": "string",
    "cvc": 0
  },
  "customer": {
    "email": "jane@example.com",
    "phoneNumber": "255742200105",
    "firstname": "JANE",
    "lastname": "DOE",
    "billingAddress": {
      "address": "Mikocheni, Plot 14",
      "alternativeAddress": "",
      "city": "Dar es Salaam",
      "region": "Dar es Salaam",
      "postcode": "14112",
      "country": "TZ"
    }
  }
}

Response

Click the Send API Request button above and see the response here!