Create a checkout session
curl --request POST \
--url https://api.primepay.mw/v1/checkout/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "0991234567"
},
"line_items": [
{
"name": "School shoes",
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"quantity": 1,
"unit_amount": 2500
}
],
"metadata": {
"cart": "88412"
}
}
'import requests
url = "https://api.primepay.mw/v1/checkout/sessions"
payload = {
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "0991234567"
},
"line_items": [
{
"name": "School shoes",
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"quantity": 1,
"unit_amount": 2500
}
],
"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: 42500,
currency: 'MWK',
reference: 'ORDER-5531',
description: '2 x School shoes',
return_url: 'https://shop.example.com/orders/5531/done',
cancel_url: 'https://shop.example.com/cart',
customer: {
first_name: 'Chikondi',
last_name: 'Banda',
email: 'customer@example.com',
phone: '0991234567'
},
line_items: [
{name: 'School shoes', quantity: 2, unit_amount: 20000},
{name: 'Delivery', quantity: 1, unit_amount: 2500}
],
metadata: {cart: '88412'}
})
};
fetch('https://api.primepay.mw/v1/checkout/sessions', 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/checkout/sessions",
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' => 42500,
'currency' => 'MWK',
'reference' => 'ORDER-5531',
'description' => '2 x School shoes',
'return_url' => 'https://shop.example.com/orders/5531/done',
'cancel_url' => 'https://shop.example.com/cart',
'customer' => [
'first_name' => 'Chikondi',
'last_name' => 'Banda',
'email' => 'customer@example.com',
'phone' => '0991234567'
],
'line_items' => [
[
'name' => 'School shoes',
'quantity' => 2,
'unit_amount' => 20000
],
[
'name' => 'Delivery',
'quantity' => 1,
'unit_amount' => 2500
]
],
'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/checkout/sessions"
payload := strings.NewReader("{\n \"amount\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\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/checkout/sessions")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.primepay.mw/v1/checkout/sessions")
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\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c0f6f4e-7a1b-4c59-9a3e-0d5b7f2c8e11",
"object": "checkout.session",
"url": "https://checkout.primepay.mw/c/3c0f6f4e-7a1b-4c59-9a3e-0d5b7f2c8e11",
"status": "open",
"livemode": true,
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "+265991234567"
},
"line_items": [
{
"name": "School shoes",
"description": null,
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"description": null,
"quantity": 1,
"unit_amount": 2500
}
],
"metadata": {
"cart": "88412"
},
"sub_merchant_account_code": null,
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"payment": null,
"created_at": "2026-11-12T08:00:00Z",
"expires_at": "2026-11-12T08:30:00Z",
"completed_at": null
}{
"error": {
"type": "invalid_request_error",
"code": "line_items_total_mismatch",
"param": "line_items",
"message": "line_items add up to 40000.00 but amount is 42500.00."
}
}{
"error": {
"type": "invalid_request_error",
"code": "line_items_total_mismatch",
"param": "line_items",
"message": "line_items add up to 40000.00 but amount is 42500.00."
}
}Checkout sessions
Create a checkout session
Creates a PrimePay payment page for one order. Redirect the customer to url; it can be paid for 30 minutes.
Guide: hosted checkout and checkout errors.
POST
/
v1
/
checkout
/
sessions
Create a checkout session
curl --request POST \
--url https://api.primepay.mw/v1/checkout/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "0991234567"
},
"line_items": [
{
"name": "School shoes",
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"quantity": 1,
"unit_amount": 2500
}
],
"metadata": {
"cart": "88412"
}
}
'import requests
url = "https://api.primepay.mw/v1/checkout/sessions"
payload = {
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "0991234567"
},
"line_items": [
{
"name": "School shoes",
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"quantity": 1,
"unit_amount": 2500
}
],
"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: 42500,
currency: 'MWK',
reference: 'ORDER-5531',
description: '2 x School shoes',
return_url: 'https://shop.example.com/orders/5531/done',
cancel_url: 'https://shop.example.com/cart',
customer: {
first_name: 'Chikondi',
last_name: 'Banda',
email: 'customer@example.com',
phone: '0991234567'
},
line_items: [
{name: 'School shoes', quantity: 2, unit_amount: 20000},
{name: 'Delivery', quantity: 1, unit_amount: 2500}
],
metadata: {cart: '88412'}
})
};
fetch('https://api.primepay.mw/v1/checkout/sessions', 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/checkout/sessions",
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' => 42500,
'currency' => 'MWK',
'reference' => 'ORDER-5531',
'description' => '2 x School shoes',
'return_url' => 'https://shop.example.com/orders/5531/done',
'cancel_url' => 'https://shop.example.com/cart',
'customer' => [
'first_name' => 'Chikondi',
'last_name' => 'Banda',
'email' => 'customer@example.com',
'phone' => '0991234567'
],
'line_items' => [
[
'name' => 'School shoes',
'quantity' => 2,
'unit_amount' => 20000
],
[
'name' => 'Delivery',
'quantity' => 1,
'unit_amount' => 2500
]
],
'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/checkout/sessions"
payload := strings.NewReader("{\n \"amount\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\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/checkout/sessions")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.primepay.mw/v1/checkout/sessions")
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\": 42500,\n \"currency\": \"MWK\",\n \"reference\": \"ORDER-5531\",\n \"description\": \"2 x School shoes\",\n \"return_url\": \"https://shop.example.com/orders/5531/done\",\n \"cancel_url\": \"https://shop.example.com/cart\",\n \"customer\": {\n \"first_name\": \"Chikondi\",\n \"last_name\": \"Banda\",\n \"email\": \"customer@example.com\",\n \"phone\": \"0991234567\"\n },\n \"line_items\": [\n {\n \"name\": \"School shoes\",\n \"quantity\": 2,\n \"unit_amount\": 20000\n },\n {\n \"name\": \"Delivery\",\n \"quantity\": 1,\n \"unit_amount\": 2500\n }\n ],\n \"metadata\": {\n \"cart\": \"88412\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c0f6f4e-7a1b-4c59-9a3e-0d5b7f2c8e11",
"object": "checkout.session",
"url": "https://checkout.primepay.mw/c/3c0f6f4e-7a1b-4c59-9a3e-0d5b7f2c8e11",
"status": "open",
"livemode": true,
"amount": 42500,
"currency": "MWK",
"reference": "ORDER-5531",
"description": "2 x School shoes",
"customer": {
"first_name": "Chikondi",
"last_name": "Banda",
"email": "customer@example.com",
"phone": "+265991234567"
},
"line_items": [
{
"name": "School shoes",
"description": null,
"quantity": 2,
"unit_amount": 20000
},
{
"name": "Delivery",
"description": null,
"quantity": 1,
"unit_amount": 2500
}
],
"metadata": {
"cart": "88412"
},
"sub_merchant_account_code": null,
"return_url": "https://shop.example.com/orders/5531/done",
"cancel_url": "https://shop.example.com/cart",
"payment": null,
"created_at": "2026-11-12T08:00:00Z",
"expires_at": "2026-11-12T08:30:00Z",
"completed_at": null
}{
"error": {
"type": "invalid_request_error",
"code": "line_items_total_mismatch",
"param": "line_items",
"message": "line_items add up to 40000.00 but amount is 42500.00."
}
}{
"error": {
"type": "invalid_request_error",
"code": "line_items_total_mismatch",
"param": "line_items",
"message": "line_items add up to 40000.00 but amount is 42500.00."
}
}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 session (a UUID is ideal), 8 to 255 characters. If your request times out, send it again with the same key to get the first session back. description and metadata may differ on the retry.
Required string length:
8 - 255Example:
"9b2f4c6e8a1d4f3b9c7e5a2d1f0b3c4e"
Body
application/json
At most 2 decimal places.
Required range:
1 <= x <= 10000000Your order or invoice number. One open or paid session per order.
Maximum string length:
100Where the customer goes after paying. A public https:// address (sandbox also allows http://localhost). session_id, reference and status are added to it.
Maximum string length:
2048Where the customer goes if they go back without paying. Same rules as return_url.
Maximum string length:
2048MWK today. Other currencies are accepted once PrimePay takes payments in that country.
Shown to the customer.
Maximum string length:
255Show child attributes
Show child attributes
Shown on the page. They must add up to amount.
Maximum array length:
50Show child attributes
Show child attributes
Your own values, up to 50 keys and 8 KB. Returned with the session and in webhooks.
Aggregator accounts only. The 8-digit account code of a linked, active sub-merchant to collect for. The agreed fee always applies.
Response
The session. Redirect the customer to url.
Example:
"checkout.session"
The payment page. null once the session can no longer be paid.
Available options:
open, processing, complete, expired, cancelled Example:
"MWK"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The payment that completed the session. null until it is paid.
Show child attributes
Show child attributes
Was this page helpful?