Base URL
All API requests for the staging environment should be sent to:Authentication
The API uses OAuth2 for security.- Generate Token: Call the
POST /oauth/tokenendpoint using Basic Authentication (Client ID and Secret) along with your username and password. - Make Requests: Use the returned
access_tokenas a Bearer token in theAuthorizationheader for all protected endpoints.
Transaction Reference (PCN)
Every transaction is identified by a unique Reference Code (often referred to as PCN). This code is generated by you (the partner) and must be unique for every request. It is used to:- Track the status of a transaction.
- Reconcile payments.
Reference Data
Transaction Types
Use these values for thetransaction_type field.
| Value | Description |
|---|---|
AIRTIME_TOPUP | Airtime Top-up |
ACCOUNTPAYMENT | Bank Transfer |
ACCOUNTPAYMENT_DEBIT_CARD | Debit Card |
ACCOUNTPAYMENT_CREDIT_CARD | Credit Card |
CASHPICKUP | Cash Pickup |
CURRENCY_CONVERTER | Bureau de Change |
CRYPTO_CURRENCY | Cryptocurrency |
BILL_PAYMENT | Bill Payment |
WALLET | Wallet |
MERCHANT_PRODUCT | Merchant Product |
MOBILE_MONEY | Mobile Money |
MERCHANT_PAYMENT | Merchant Payment |
Transaction Purposes
Use these values for thetransaction_purpose field.
| Value | Description |
|---|---|
FAMILY_SUPPORT | Family support |
EDUCATION | Education |
GIFT_AND_DONATION | Gift and other donations |
MEDICAL_TREATMENT | Medical treatment |
MAINTENANCE_EXPENSES | Maintenance or other expenses |
TRAVEL | Travel |
SMALL_VALUE_REMITTANCE | Small value remittance |
LIBERALIZED_REMITTANCE | Liberalized remittance |
OTHER | Other purposes |
Beneficiary Relationships
Common values forbeneficiaryRelationship: FRIENDS, PARENTS, RELATIVES, SPOUSE, SIBLING, SELF, BUSINESS_PARTNER, etc.
Document Types
Documents required for KYC/Compliance.| Value |
|---|
| Passport |
| National Id |
| Driving License |
| Voter’s card |
| Proof of Address |
| Customer declaration form |
| Certificate of Incorporation |
| … (and others) |
Response Statuses
The lifecycle status of a transaction.| Status | Description | Lifecycle |
|---|---|---|
SUCCESS | Instruction successfully received. | Incomplete |
PAID | Successfully paid out to beneficiary. | Completed |
FAILED | Processed but unsuccessful. | Completed |
PENDING | Sent to beneficiary bank, awaiting confirmation. | Incomplete |
READY_TO_CALL | Queued to be sent to beneficiary bank. | Incomplete |
PROCESSING | Queued for processing. | Incomplete |
CANCEL | Instruction canceled. | Completed |
ERROR | Technical issue occurred. | Completed |
Response Codes
Specific error or success codes returned inmsg_code.
| Code | Status | Description |
|---|---|---|
00 | PAID | Paid successfully |
0000 | PENDING | Awaiting processing |
0001 | FAILED | Invalid Bank Account Number |
0002 | FAILED | Recipient Contact Details Invalid |
0005 | FAILED | Invalid Bank Code |
0030 | FAILED | Insufficient Funds |
0042 | PENDING | Ready to Call (Queued) |
50004 | FAILED | Unknown Error / Transaction Failed |
HTTP Status Codes
Client Errors| Code | Description |
|---|---|
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests (implied) |
| Code | Description |
|---|---|
500 | Internal Server Error |
502 | Bad Gateway |
503 | Service Unavailable |
504 | Gateway Timeout |