Create a payment
curl --request POST \
--url https://api.primepay.mw/v1/payments/mobile-money \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 25000,
"currency": "MWK",
"customerPhone": "+265991234567",
"provider": "7d51b653-3c6d-46eb-b3d9-7852dfee5b26",
"merchantOrderId": "ORDER-5531",
"description": "2 x School shoes",
"email": "customer@example.com",
"firstName": "Chikondi",
"lastName": "Banda",
"callbackUrl": "https://api.yourshop.mw/webhooks/primepay",
"metadata": {
"cart": "88412"
}
}
'import requests
url = "https://api.primepay.mw/v1/payments/mobile-money"
payload = {
"amount": 25000,
"currency": "MWK",
"customerPhone": "+265991234567",
"provider": "7d51b653-3c6d-46eb-b3d9-7852dfee5b26",
"merchantOrderId": "ORDER-5531",
"description": "2 x School shoes",
"email": "customer@example.com",
"firstName": "Chikondi",
"lastName": "Banda",
"callbackUrl": "https://api.yourshop.mw/webhooks/primepay",
"metadata": { "cart": "88412" }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 25000,
currency: 'MWK',
customerPhone: '+265991234567',
provider: '7d51b653-3c6d-46eb-b3d9-7852dfee5b26',
merchantOrderId: 'ORDER-5531',
description: '2 x School shoes',
email: 'customer@example.com',
firstName: 'Chikondi',
lastName: 'Banda',
callbackUrl: 'https://api.yourshop.mw/webhooks/primepay',
metadata: {cart: '88412'}
})
};
fetch('https://api.primepay.mw/v1/payments/mobile-money', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.primepay.mw/v1/payments/mobile-money",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 25000,
'currency' => 'MWK',
'customerPhone' => '+265991234567',
'provider' => '7d51b653-3c6d-46eb-b3d9-7852dfee5b26',
'merchantOrderId' => 'ORDER-5531',
'description' => '2 x School shoes',
'email' => 'customer@example.com',
'firstName' => 'Chikondi',
'lastName' => 'Banda',
'callbackUrl' => 'https://api.yourshop.mw/webhooks/primepay',
'metadata' => [
'cart' => '88412'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.primepay.mw/v1/payments/mobile-money"
payload := strings.NewReader("{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.primepay.mw/v1/payments/mobile-money")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.primepay.mw/v1/payments/mobile-money")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}"
response = http.request(request)
puts response.read_body{
"reference": "TXN-WRYF6S2W3DQW",
"status": "processing",
"amount": 25000,
"currency": "MWK",
"merchantOrderId": "ORDER-5531",
"failureCode": null,
"createdAt": "2026-11-09T10:15:02Z",
"subMerchantAccountCode": null,
"subMerchantName": null,
"aggregatorFee": null
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}{
"reference": "TXN-WRYF6S2W3DQW",
"status": "pending",
"amount": 123,
"fee": 123,
"currency": "MWK",
"merchantOrderId": "<string>",
"failureCode": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z",
"subMerchantAccountCode": "<string>",
"subMerchantName": "<string>",
"aggregatorFee": 123
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}Payments
Create a payment
Collects money from a customer’s mobile money account into the account that owns the API key. The customer approves it on their phone, so the final result arrives later by webhook.
Guide: how a payment runs and payment errors.
POST
/
v1
/
payments
/
mobile-money
Create a payment
curl --request POST \
--url https://api.primepay.mw/v1/payments/mobile-money \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 25000,
"currency": "MWK",
"customerPhone": "+265991234567",
"provider": "7d51b653-3c6d-46eb-b3d9-7852dfee5b26",
"merchantOrderId": "ORDER-5531",
"description": "2 x School shoes",
"email": "customer@example.com",
"firstName": "Chikondi",
"lastName": "Banda",
"callbackUrl": "https://api.yourshop.mw/webhooks/primepay",
"metadata": {
"cart": "88412"
}
}
'import requests
url = "https://api.primepay.mw/v1/payments/mobile-money"
payload = {
"amount": 25000,
"currency": "MWK",
"customerPhone": "+265991234567",
"provider": "7d51b653-3c6d-46eb-b3d9-7852dfee5b26",
"merchantOrderId": "ORDER-5531",
"description": "2 x School shoes",
"email": "customer@example.com",
"firstName": "Chikondi",
"lastName": "Banda",
"callbackUrl": "https://api.yourshop.mw/webhooks/primepay",
"metadata": { "cart": "88412" }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 25000,
currency: 'MWK',
customerPhone: '+265991234567',
provider: '7d51b653-3c6d-46eb-b3d9-7852dfee5b26',
merchantOrderId: 'ORDER-5531',
description: '2 x School shoes',
email: 'customer@example.com',
firstName: 'Chikondi',
lastName: 'Banda',
callbackUrl: 'https://api.yourshop.mw/webhooks/primepay',
metadata: {cart: '88412'}
})
};
fetch('https://api.primepay.mw/v1/payments/mobile-money', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.primepay.mw/v1/payments/mobile-money",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 25000,
'currency' => 'MWK',
'customerPhone' => '+265991234567',
'provider' => '7d51b653-3c6d-46eb-b3d9-7852dfee5b26',
'merchantOrderId' => 'ORDER-5531',
'description' => '2 x School shoes',
'email' => 'customer@example.com',
'firstName' => 'Chikondi',
'lastName' => 'Banda',
'callbackUrl' => 'https://api.yourshop.mw/webhooks/primepay',
'metadata' => [
'cart' => '88412'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.primepay.mw/v1/payments/mobile-money"
payload := strings.NewReader("{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.primepay.mw/v1/payments/mobile-money")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.primepay.mw/v1/payments/mobile-money")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 25000,\n \"currency\": \"MWK\",\n \"customerPhone\": \"+265991234567\",\n \"provider\": \"7d51b653-3c6d-46eb-b3d9-7852dfee5b26\",\n \"merchantOrderId\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"email\": \"customer@example.com\",\n \"firstName\": \"Chikondi\",\n \"lastName\": \"Banda\",\n \"callbackUrl\": \"https://api.yourshop.mw/webhooks/primepay\",\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}"
response = http.request(request)
puts response.read_body{
"reference": "TXN-WRYF6S2W3DQW",
"status": "processing",
"amount": 25000,
"currency": "MWK",
"merchantOrderId": "ORDER-5531",
"failureCode": null,
"createdAt": "2026-11-09T10:15:02Z",
"subMerchantAccountCode": null,
"subMerchantName": null,
"aggregatorFee": null
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}{
"reference": "TXN-WRYF6S2W3DQW",
"status": "pending",
"amount": 123,
"fee": 123,
"currency": "MWK",
"merchantOrderId": "<string>",
"failureCode": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z",
"subMerchantAccountCode": "<string>",
"subMerchantName": "<string>",
"aggregatorFee": 123
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}Authorizations
Your API key: sk_live_… / sk_test_… (secret), pk_live_… / pk_test_… (publishable, read-only reference data) or rk_live_… / rk_test_… (payments only).
Headers
A new value for every new payment (a UUID is ideal), 8 to 255 characters. If your request times out, send it again with the same key to get the first result back instead of a second payment. The same key with a different body is refused.
Required string length:
8 - 255Example:
"6f1c2b9e8a6d4c1f9b0e3a7d5c2f8e10"
Body
application/json
What your customer owes. Depending on your fee setting, the customer may pay PrimePay's fee on top.
Example:
25000
Available options:
MWK International format, +265 and 9 digits. Must belong to the operator.
Example:
"+265991234567"
An operator refId from List mobile money operators.
Example:
"7d51b653-3c6d-46eb-b3d9-7852dfee5b26"
Your order or invoice number (letters, digits, - _ . /). One active or paid payment per order.
Maximum string length:
64Example:
"ORDER-5531"
Maximum string length:
140Example:
"2 x School shoes"
The customer's email, for receipts and your records.
Example:
"customer@example.com"
Example:
"Chikondi"
Example:
"Banda"
Sends this payment's webhooks here as well as to your endpoints. Must be HTTPS, on one of your webhook or allowed callback hosts. Required if you have no webhook endpoint.
Example:
"https://api.yourshop.mw/webhooks/primepay"
Your own key/value pairs, echoed back in webhooks.
Show child attributes
Show child attributes
Example:
{ "cart": "88412" }
Response
Accepted while the customer approves the payment.
Example:
"TXN-WRYF6S2W3DQW"
Available options:
pending, processing, success, failed, expired, cancelled, reversed Example:
"MWK"
Set when the payment was collected for a sub-merchant.
The fee you keep as the aggregator.
Was this page helpful?