Collect with MTN

Select Auth Method:

POST/payment/mtn-momo-payAPI

Authentication:Bearer token•Authorization: Bearer <token>(Bearer token for server-to-server API calls)

Security requirement: 403 CSRF Protection

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

Required Headers

Authorizationstring

Bearer <merchant_token>

Content-Typestring

application/json

Request Parameters

Field	Type	Required	Description
`Authorization`	string	Required	Bearer <merchant_token>
`Content-Type`	string	Required	application/json

import axios from "axios";

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

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

const payload = {
  "amount": 1000,
  "currency": "RWF",
  "phoneNumber": "+250788000000",
  "description": "Illustrative order 1042",
  "idempotencyKey": "order-1042-mtn"
};

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

Field	Type	Presence	Description
`transactionReferenceId`	string	Always returned	Reference used to poll status.
`orderId`	string	Always returned	Ziba Pay order id.
`status`	string	Always returned	Example responses may show lowercase pending while the order record uses PENDING. Poll until COMPLETED or FAILED.
`idempotentReplay`	boolean	Optional	Present and true when an existing idempotency key was reused.

Status codes

HTTP Status	Meaning
200	Collection started successfully, or an idempotent replay.
400	Validation failed, or phone number is the merchant's own number. { error: message }.
401	Missing or invalid API key / Bearer token.
404	Authenticated merchant user not found.
429	More than 15 payment requests in a minute from this IP.
503	MTN credentials missing or provider unavailable.
503	MTN request-to-pay could not be submitted to upstream network.

Notes

Illustrative example. Identifiers in sample responses are not production records.
phoneNumber is the paying customer's MTN MSISDN. The customer does not need a Ziba Pay account. The merchant cannot collect from their own phone number.
POST /payment/mtn-momo-pay uses a Bearer token. The gateway API-key collect route still exists in the service for server jobs.
A new collection returns status "pending". Other statuses use the stored order enum.
Payment routes are limited to 15 requests per minute per IP, inside a global limit of 300 requests per 15 minutes.
After calling this endpoint, capture the transactionReferenceId and poll the MTN payment status endpoint until final status.

Select Auth Method:

POST/payment/mtn-momo-payAPI

Authentication:Bearer token•Authorization: Bearer <token>(Bearer token for server-to-server API calls)

Security requirement: 403 CSRF Protection

Auth guide →

X-Requested-With: XMLHttpRequest

Required Headers

Authorizationstring

Bearer <merchant_token>

Content-Typestring

application/json

Request Parameters

Field	Type	Required	Description
`Authorization`	string	Required	Bearer <merchant_token>
`Content-Type`	string	Required	application/json

import axios from "axios";

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

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

const payload = {
  "amount": 1000,
  "currency": "RWF",
  "phoneNumber": "+250788000000",
  "description": "Illustrative order 1042",
  "idempotencyKey": "order-1042-mtn"
};

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

Field	Type	Presence	Description
`transactionReferenceId`	string	Always returned	Reference used to poll status.
`orderId`	string	Always returned	Ziba Pay order id.
`status`	string	Always returned	Example responses may show lowercase pending while the order record uses PENDING. Poll until COMPLETED or FAILED.
`idempotentReplay`	boolean	Optional	Present and true when an existing idempotency key was reused.

Status codes

HTTP Status	Meaning
200	Collection started successfully, or an idempotent replay.
400	Validation failed, or phone number is the merchant's own number. { error: message }.
401	Missing or invalid API key / Bearer token.
404	Authenticated merchant user not found.
429	More than 15 payment requests in a minute from this IP.
503	MTN credentials missing or provider unavailable.
503	MTN request-to-pay could not be submitted to upstream network.

Notes

Illustrative example. Identifiers in sample responses are not production records.
phoneNumber is the paying customer's MTN MSISDN. The customer does not need a Ziba Pay account. The merchant cannot collect from their own phone number.
POST /payment/mtn-momo-pay uses a Bearer token. The gateway API-key collect route still exists in the service for server jobs.
A new collection returns status "pending". Other statuses use the stored order enum.
Payment routes are limited to 15 requests per minute per IP, inside a global limit of 300 requests per 15 minutes.
After calling this endpoint, capture the transactionReferenceId and poll the MTN payment status endpoint until final status.

Request Parameters

Response fields

Status codes

Notes

Related

Collect with MTN

Request Parameters

Response fields

Status codes

Notes

Related