Introduction to the Invoice API
The Invoice API allows businesses to generate a payment reference (invoice) that can be paid by the customer (Payer) within a specified validity period. This invoice is currently payable through MoMo Pay via USSD, enabling structured and trackable payments for various use cases.
Real-World Use Cases
-
Businesses already using MoMo Pay codes can integrate this API to benefit from automated reconciliation, as payments are directly linked to internal systems such as order or invoice records.
-
Point of Sale (POS) systems in restaurants, supermarkets, retail stores, etc.
-
School management systems for collecting school fees.
-
Public transport operators for digital fare collection.
Why Use the Invoice API?
-
Improved reconciliation: Payments are automatically tied to internal orders or invoices, reducing manual tracking.
-
Simplified payment experience: The invoice reference can be embedded in a QR code, allowing the Payer to simply scan and pay.
-
Flexible payment window: Supports real-time payments or "Pay Later" within the invoice validity period.
-
Invoice management: Ability to cancel pending invoices programmatically.
How to Integrate
1. Authentication & Setup
-
Create an account on the MoMo Developer Portal.
-
Subscribe to the Collections Product, which grants access to Subscription Keys (found on your Profile page).
-
Create an API User and API Key using the Provisioning APIs:
You will now have the following credentials: Ocp-Apim-Subscription-Key, X-Reference-Id (API User), API Key
2. Generate Access Token
Use the Token Endpoint to get a bearer token (valid for 1 hour).
3. Create Invoice
Call the Create Invoice API to generate a new invoice.
4. Retrieve Invoice Status
Use the Get Invoice Status API to get the current status and obtain the payment reference.
5. Present to Payer
-
Embed the payment reference in a USSD string:
Format::MoMoPayShortCodeString]*InvoiceReference*1#
Example for MTN Uganda:*165*3*InvoiceReference*1# -
Display a QR Code embedding the above USSD string.
-
For feature phone users, instruct them to dial the USSD manually and enter the invoice reference when prompted.
6. Receive Payment Notification
-
Set up your system to receive a callback once the invoice is paid.
-
Optionally, poll the GetInvoiceStatus API to verify payment status for real-time use cases or in case the callback fails.
Common Pitfalls and How to Avoid Them
| Pitfall | Mitigation |
|---|---|
| Relying only on callback notifications | Implement both callback handling and status polling. If the callback fails or your server is unreachable, polling ensures your system can still track payment status. |
Tips for Successful Implementation
-
Offer both USSD and QR code options for maximum payer flexibility.
-
Ensure you implement both callback handling and periodic invoice status checks to guarantee reliability in payment tracking.
Additional Resources