Quick start
A step-by-step walkthrough to registering an account, obtaining credentials, initiating your first collection, and polling for results.
Video: how to integrate the API
API integration walkthrough
Step 1 / 4Create API credentials
Register, then generate an API key and secret from the dashboard Applications page.
POST /developer/gatewayConfigsQuick Start Overview
This guide walks you through sending your first real or simulated payment request on https://payment-service-mh2d.onrender.com/api. You will create a merchant account, retrieve a session token, create a Gateway API Key, initiate an MTN collection, and poll for settlement.
One API host
A separate sandbox hostname is not confirmed. Test and live credentials must not be mixed. Confirm the active provider environment with the team before sending a payment.
| Step | Action | Endpoint | Auth Header / Credentials | Outcome |
|---|---|---|---|---|
| 1 | Sign up | POST/auth/signup | None | Receive JWT access token & refresh token |
| 2 | Log in | POST/auth/login | None | Authenticate automated backend processes |
| 3 | Create API keys | POST/developer/gatewayConfigs | Authorization: Bearer <token> | Receive x-api-key and plaintext apiSecret |
| 4 | Collect payment | POST/payment/mtn-momo-pay | Authorization: Bearer <token> | Trigger USSD prompt; receive transactionReferenceId |
| 5 | Poll status | GET/payment/mtn/status/:ref | Authorization: Bearer <token> | Verify final payment status (COMPLETED) |
Implementation Steps
5 sequential steps- 1Step 1 of 5
Create an account
Register your merchant account via POST/auth/signup. Returns merchant JWT access token and refresh token.Request Examplecurl -X POST "https://payment-service-mh2d.onrender.com/api/auth/signup" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Kwame", "lastName": "Mensah", "email": "merchant@example.com", "password": "SecurePassword123!", "businessName": "Acme Retail", "businessType": "Ecommerce", "country": "Rwanda", "phoneNumber": "+250788000000", "howHear": "Developer Docs" }'Sign upAPI Reference - 2Step 2 of 5
Sign in
Sign in with POST/auth/login to retrieve your session bearer token for automated calls.Request Examplecurl -X POST "https://payment-service-mh2d.onrender.com/api/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "merchant@example.com", "password": "SecurePassword123!" }'Sign inAPI Reference - 3Step 3 of 5
Create API keys
Generate an API key and secret pair via POST/developer/gatewayConfigs for server-to-server payments.Request Examplecurl -X POST "https://payment-service-mh2d.onrender.com/api/developer/gatewayConfigs" \ -H "Authorization: Bearer $ZIBA_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Production Store Checkout", "description": "Server-to-server payment collections for online ecommerce store" }'Create API keysAPI Reference - 4Step 4 of 5
Collect payment
Trigger mobile money collection with POST/payment/mtn-momo-pay using a Bearer token.Request Examplecurl -X POST "https://payment-service-mh2d.onrender.com/api/payment/mtn-momo-pay" \ -H "Authorization: Bearer $ZIBA_ACCESS_TOKEN" \ -H "x-api-secret: $ZIBA_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "amount": 100, "currency": "RWF", "phoneNumber": "+250788000000" }'Collect a paymentAPI Reference - 5Step 5 of 5
Poll status
Poll GET/payment/mtn/status/:reference with your transaction reference until final status (COMPLETED or FAILED).Request Examplecurl -X GET "https://payment-service-mh2d.onrender.com/api/payment/mtn/status/$TRANSACTION_REFERENCE" \ -H "Authorization: Bearer $ZIBA_TOKEN"Poll statusAPI Reference
Notes
- Illustrative example. A separate sandbox hostname is not confirmed.
- The API-key route and the bearer-token route use the same MTN body. Status polling uses a bearer token.
- Poll payment status with the transactionReferenceId. Payment routes are limited to 15 requests per minute.