Receive payment

Payment Gateways

Start a payment from a customer. It supports mobile wallet payments and Visa card payments.

POSThttps://telcomw.com/api-v2/payments/receive

Send a JSON body. Authenticate with a Bearer token, which is your TelcoMW API key.

Parameters

Parameter	Sent in	Required	Description
`Authorization`	header	YES	Bearer YOUR_API_KEY (your TelcoMW API key).
`reference`	body	YES	A unique transaction reference, 7 to 20 characters.
`description`	body	YES	A description of the payment.
`amount`	body	YES	The amount in MWK. The minimum is MWK 50 and the maximum is MWK 750,000.
`channel`	body	YES	"wallet" for mobile wallet payments (TNM Mpamba or Airtel Money), "card" for Visa card payments (provided by Standard Bank).
`ipn`	body	YES	The address where we send the payment notifications. A valid URL of up to 100 characters.
`subscriber`	body	NO	The phone number, 9 to 13 digits, numbers only. Required when channel is wallet.

Example request

curl --location --request POST 'https://telcomw.com/api-v2/payments/receive' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference": "RE920369746454",
  "description": "Some Items",
  "amount": 50,
  "subscriber": "0992026866",
  "channel": "wallet",
  "ipn": "https://yourdomain.com/notifications"
}'

curl --location --request POST "https://telcomw.com/api-v2/payments/receive" ^
  --header "Authorization: Bearer YOUR_API_KEY" ^
  --header "Content-Type: application/json" ^
  --data "{\"reference\":\"RE920369746454\",\"description\":\"Some Items\",\"amount\":50,\"subscriber\":\"0992026866\",\"channel\":\"wallet\",\"ipn\":\"https://yourdomain.com/notifications\"}"

<?php

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
];

$data = [
    'reference' => 'RE920369746454',
    'description' => 'Some Items',
    'amount' => 50,
    'subscriber' => '0992026866',
    'channel' => 'wallet',
    'ipn' => 'https://yourdomain.com/notifications'
];

$ch = curl_init('https://telcomw.com/api-v2/payments/receive');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

const axios = require('axios');

axios.request({
  method: 'post',
  url: 'https://telcomw.com/api-v2/payments/receive',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data: {
    "reference": "RE920369746454",
    "description": "Some Items",
    "amount": 50,
    "subscriber": "0992026866",
    "channel": "wallet",
    "ipn": "https://yourdomain.com/notifications"
  }
}).then((res) => console.log(res.data))
  .catch((err) => console.error(err.response ? err.response.data : err.message));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {
    'reference': 'RE920369746454',
    'description': 'Some Items',
    'amount': 50,
    'subscriber': '0992026866',
    'channel': 'wallet',
    'ipn': 'https://yourdomain.com/notifications'
}

response = requests.request('POST', 'https://telcomw.com/api-v2/payments/receive', headers=headers, json=payload)
print(response.json())

Response

The response is JSON.

Success

{
  "message": "Service request accepted",
  "feedback": {
    "subscriber": "0992026866",
    "reference": "RE320369746450",
    "amount": 50,
    "operator": "airtel"
  },
  "status": "success"
}

Good to know

Success: the payment request is accepted, with the operator. Error: validation errors or service failures.
A duplicate transaction reference is rejected, and so is an invalid phone number for wallet payments.
The ipn address must be publicly reachable, so we can send you the payment notifications.
All amounts are in Malawian Kwacha (MWK). Transaction references must be unique across all payments.
Every response has message (a readable message), feedback (the details) and status (success, error or info).
HTTP status codes: 200 success, 400 bad request (validation errors), 404 endpoint not found, 500 internal server error.
Common validation errors: missing required fields, an amount out of range, a wrong phone number or URL format, a reference of the wrong length, and duplicate references.
Mobile wallet payments (TNM Mpamba and Airtel Money) need a valid subscriber phone number and are processed in real time.
Visa payments are credit or debit card payments with international support, provided by Standard Bank.
The base URL of this API is shown under your transactions on the TelcoMW website. Standard rate limiting applies, contact support for specific limits.