Developers
REST API
GuidesErrorsLogin
Get API Keys
API Navigation
  • Overview
  • Quick start
  • Authentication
  • Collect a payment
  • Payment status
  • Refunds
  • Testing
  • Production
  • Security
API reference
  • Create API keys POST
  • List API keys GET
  • Get API key GET
  • Delete API key DEL
  • Collect with MTN POST
  • MTN payment status GET
  • Collect with Airtel POST
    Create and pay
  • Create order POST
  • Order fee POST
  • Pay order with card POST
  • Pay order with bank POST
    • Status and verify
  • Order status POST
  • Verify order POST
    • Cards and tokens
  • Save card POST
  • Tokenize charge GET
    • Refunds
  • Refund order POST
    • Lists and stats
  • List orders GET
  • Get order GET
  • List banks GET
  • Order stats GET
  • List transactions GET
  • Get transaction GET
  • Transaction statuses GET
Errors and limits
  1. Docs
  3. API reference
  5. Collect with Airtel

Collect with Airtel

Start an Airtel Money collection with a merchant session.

OpenAPI SpecRun in Postman
POST/payment/airtel-momo-payAPI
Authentication:Bearer token•Authorization: Bearer <token>(Bearer token for server-to-server API calls)
Security requirement: 403 CSRF Protection
Auth guide →

Direct server-to-server calls authenticated via Bearer tokens do not require CSRF headers. If you instead invoke mutation endpoints from a web browser using cookie-based sessions, you must include the following header:

X-Requested-With: XMLHttpRequest

Request body

FieldTypeRequiredDescription
amountnumber or stringRequiredCollection amount in the configured Airtel currency. The example server configuration uses RWF.
numberstringRequiredSubscriber MSISDN phone number (e.g., '788000000').
referencestringRequiredYour unique merchant order or transaction reference.
import axios from "axios";

const url = "https://payment-service-mh2d.onrender.com/api/payment/airtel-momo-pay";

const headers = {
    Authorization: `Bearer ${process.env.ZIBA_TOKEN}`,
    "Content-Type": "application/json",
};

const payload = {
  "amount": 1500,
  "number": "788000000",
  "reference": "order-1042"
};

try {
  const response = await axios.post(url, payload, {
    headers,
    timeout: 15000,
  });
  console.log("Success:", response.status, response.data);
} catch (error) {
  console.error("Request failed:", error.response?.data || error.message);
}
Auth guide

Response fields

FieldTypePresenceDescription
data.transaction.idstringAlways returnedAirtel transaction reference ID.
data.transaction.statusstringAlways returnedTransaction processing status from Airtel gateway.
status.codestringAlways returnedResponse status code from Airtel.
status.messagestringAlways returnedStatus description message from Airtel.
status.successbooleanAlways returnedTrue when debit request is accepted for processing.

Status codes

HTTP StatusMeaning
200Airtel response body.
400amount, number, or reference missing.
401No merchant session. Missing Bearer token.
429Payment rate limit exceeded (15 req/min).
500Airtel gateway call failed.

Notes

  • Illustrative example. The sample transaction id is not a production record.
  • Airtel country and currency come from server configuration. The example configuration is country RW, currency RWF, and an Airtel UAT token URL. Live Airtel is not confirmed.
  • HTTP 400 is { message: "Please provide all required inputs (amount, number, and reference)" }.
  • HTTP 500 is { error: "Error processing Airtel Money payment" }.

Related

Collect a paymentPayment status
Was this page helpful?

Let us know how we can make our API documentation better.

PreviousMTN payment status
NextCreate order