API reference

The gateway takes a payment request from your system, sends it to the customer's mobile money operator, and tells you the result. You send one request. We call your server back when the payment is complete.

How it works#

1. You send POST/api/momo with the customer's phone number, an amount and your own reference.
2. We reply straight away with 202 Accepted. The customer gets a payment prompt on their phone.
3. When the payment reaches a final status, we send a FINAL callback to your notification_url.

For payments that the customer starts on their own (for example by paying your business number from their phone), we first send a VALIDATE callback so that you can confirm the payment is expected. See Callbacks.

Before you start#

You receive these during onboarding:

All communication uses HTTPS. Requests and responses are JSON (application/json, UTF-8).

Signing requests#

Every request to the gateway carries an X-Signature header, and so does every callback we send to you. The signature proves that the message came from the other side and was not changed on the way.

To compute the signature:

1. Take the X-Timestamp value and the raw JSON body, and join them as text: timestamp + body.
2. Remove every whitespace character from that text (spaces, tabs and new lines), including spaces inside values. "Airtel Money" becomes "AirtelMoney".
3. Compute an HMAC with SHA-256, using your signature key as the key.
4. Encode the result as Base64 (standard alphabet, with padding).

Use this example to test your code. With the signature key sk_test_example_key, timestamp 1792333239 and this body:

{
  "type": "FINAL",
  "data": {
    "reference": "3137804641763844",
    "transaction_reference": "21453994292708209",
    "receipt": null,
    "completed": "2026-10-18T14:20:37.698824Z",
    "status": "FAILED",
    "status_description": "Failed",
    "operator": "Airtel Money"
  }
}

the signature is:

FC68dcFwYbpNBT+STbH7ZmE+5Ij4rW+8jz2o72+QOKg=

Each snippet below returns that value for the example above.

Python

import base64, hashlib, hmac, re

def sign(timestamp: str, payload: str, secret: str) -> str:
    data = re.sub(r"\s+", "", timestamp + payload)
    digest = hmac.new(secret.encode("utf-8"), data.encode("utf-8"), hashlib.sha256).digest()
    return base64.b64encode(digest).decode("ascii")

JavaScript (Node.js)

const crypto = require("node:crypto");

function sign(timestamp, payload, secret) {
    const data = (timestamp + payload).replace(/\s+/g, "");
    return crypto.createHmac("sha256", secret).update(data, "utf8").digest("base64");
}

PHP

function sign(string $timestamp, string $payload, string $secret): string {
    $data = preg_replace('/\s+/', '', $timestamp . $payload);
    return base64_encode(hash_hmac('sha256', $data, $secret, true));
}

Go

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"regexp"
)

var whitespace = regexp.MustCompile(`\s+`)

func sign(timestamp, payload, secret string) string {
	data := whitespace.ReplaceAllString(timestamp+payload, "")
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(data))
	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}

Rust (crates hmac, sha2 and base64)

use base64::{engine::general_purpose::STANDARD, Engine};
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha256;

fn sign(timestamp: &str, payload: &str, secret: &str) -> String {
    let data: String = format!("{timestamp}{payload}")
        .chars()
        .filter(|c| !c.is_whitespace())
        .collect();
    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("any key length works");
    mac.update(data.as_bytes());
    STANDARD.encode(mac.finalize().into_bytes())
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

static String sign(String timestamp, String payload, String secret) throws Exception {
    String data = (timestamp + payload).replaceAll("\\s+", "");
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    return Base64.getEncoder().encodeToString(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));
}

Create a transaction#

POST/api/momo

Starts a payment. Sign the request as described in Signing requests.

Headers

Body

curl -X POST "https://GATEWAY_URL/api/momo" \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -H "X-Timestamp: 1792335559" \
  -H "X-Signature: iv80dq3Qv8WCDaHFUuXgzLje8NM1OfRcNflf1EERbAM=" \
  -H "Idempotency-Key: 3141259380648434" \
  -H "Content-Type: application/json" \
  -d '{"msisdn":"255685007797","reference":"3141259380648434","amount":100000,"type":"COLLECTION","notification_url":"https://shop.example.com/hooks/momo"}'

The signature in this example uses the test key sk_test_example_key. Yours will differ.

Response 202 Accepted

{
  "status": true,
  "reference": "3141259380648434",
  "message": "Transaction accepted",
  "data": null
}

reference is the value you sent. The customer now receives a prompt on their phone. The result comes later by callback.

Other responses

All error responses use the same JSON shape as the success response, with "status": false and a message that explains the problem.

Get a transaction#

GET/api/momo/{thirdPartyReference}

Returns the latest result of a transaction. {thirdPartyReference} is the reference you sent when you created it.

Use it when a callback does not arrive, or to double-check a payment before you release goods. Do not poll in a tight loop. Callbacks are the main way to learn the result.

Send the same X-Client-Id, X-Client-Secret, X-Timestamp and X-Signature headers. A GET has no body, so you sign only the timestamp.

curl "https://GATEWAY_URL/api/momo/3141259380648434" \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIGNATURE"

Response 200 OK

The data field holds the same object that a FINAL callback sends.

{
  "status": true,
  "reference": "3141259380648434",
  "message": "Transaction found",
  "data": {
    "type": "FINAL",
    "data": {
      "reference": "3141259380648434",
      "transaction_reference": "21453994292708209",
      "receipt": null,
      "completed": "2026-10-18T14:20:37.698824Z",
      "status": "FAILED",
      "status_description": "Failed",
      "operator": "Airtel Money"
    }
  }
}

Other responses

Callbacks#

We send callbacks as POST requests to the notification_url you gave in the request. There are two types, shown in the type field.

Every callback has these headers:

FINAL callback#

{
  "type": "FINAL",
  "data": {
    "reference": "3137804641763844",
    "transaction_reference": "21453994292708209",
    "receipt": null,
    "completed": "2026-10-18T14:20:37.698824Z",
    "status": "FAILED",
    "status_description": "Failed",
    "operator": "Airtel Money"
  }
}

VALIDATE callback#

{
  "type": "VALIDATE",
  "data": {
    "reference": "3137804641763844",
    "transaction_reference": "21453994292708209",
    "receipt": null,
    "operator": "Airtel Money",
    "amount": 1000,
    "business_number": 2121213
  }
}

Check the reference and the amount against your own records. If they are right, answer with success. The payment then continues, and you receive the FINAL callback when it finishes.

Your response#

Answer every callback with HTTP 200 and this body:

{
  "status": true,
  "message": "Success"
}

Respond quickly. Save the result and do slow work, such as sending emails, after you have replied.

Security checklist#

• Whitelist our IP addresses. Accept callbacks only from the addresses we gave you. Requests to the gateway from other addresses are refused with 403.
• Use HTTPS. Your notification_url must use HTTPS in production.
• Verify the signature on every callback. Compute it from the raw body and the X-Timestamp header, and compare it with X-Signature. Reject the callback if they differ. Compare in constant time, with a function such as hmac.compare_digest in Python or MessageDigest.isEqual in Java.
• Check the timestamp. Reject callbacks whose X-Timestamp is far from your clock, for example by more than 5 minutes. This stops someone from replaying an old message.
• Check the idempotency key. Ignore callbacks you have already processed.
• Check the details. Match reference and the amount with your own order before you mark it paid.
• Protect your secrets. Keep the client secret and the signature key in a secrets manager or environment variables. Do not log them, and tell us at once if you think they leaked.

Getting help#

If you contact support, include the transaction_reference and your own reference. With these two we can trace the payment from request to callback.