Collect for a sub-merchant
curl --request POST \
--url https://api.primepay.mw/v1/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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-K3P9Q2X7MZAB",
"status": "processing",
"amount": 50000,
"currency": "MWK",
"merchantOrderId": "INV-2041",
"failureCode": null,
"createdAt": "2026-11-09T10:20:44Z",
"subMerchantAccountCode": "12345678",
"subMerchantName": "Chikondi's Store",
"aggregatorFee": 500
}{
"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>"
}
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}Payments
Collect for a sub-merchant
Aggregator accounts only. Collects for a sub-merchant linked to your account. The body is the same as Create a payment, and the agreed fee always applies.
Guide: collecting for a sub-merchant and payment errors.
POST
/
v1
/
sub-merchants
/
{subMerchantCode}
/
payments
/
mobile-money
Collect for a sub-merchant
curl --request POST \
--url https://api.primepay.mw/v1/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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/sub-merchants/{subMerchantCode}/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-K3P9Q2X7MZAB",
"status": "processing",
"amount": 50000,
"currency": "MWK",
"merchantOrderId": "INV-2041",
"failureCode": null,
"createdAt": "2026-11-09T10:20:44Z",
"subMerchantAccountCode": "12345678",
"subMerchantName": "Chikondi's Store",
"aggregatorFee": 500
}{
"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>"
}
}{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance for MWK 25,000.00.",
"field": "<string>"
}
}{
"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"
Path Parameters
The sub-merchant's 8-digit account code.
Pattern:
^[0-9]{8}$Example:
"12345678"
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. The response includes whose payment it is.
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?