Zamupay overview

💳 ZamuPay API Documentation Summary

This document outlines the data definitions, codes, and callback structures for the ZamuPay API, primarily for managing payment orders and transactions.

Note: To interact with the API to its full capacity, you must have an account already set up on the ZamuPay system.

📝 Data Definition for Payment Orders

This table defines the mandatory and optional fields required for a payment order request.

Field Name	Data Type	Max Length	State	Description
`originatorConversationId`	string	100	Mandatory	Unique identifier for the transaction.
`paymentNotes`	string	255	Mandatory	Notes related to the payment.
`remitterName`	string	128	Mandatory	Sender's full name.
`remitterAddress`	string	128	Mandatory	Sender's address.
`remitterPhoneNumber`	string	13	Mandatory	Sender's phone number.
`remitterIdType`	string	13	Mandatory	Type of sender's ID (e.g., National ID).
`remitterIdNumber`	string	13	Mandatory	Sender's ID number.
`remitterCountry`	string	50	Mandatory	Sender's country.
`remitterCCY`	string	3	Mandatory	Sender's currency code.
`remitterNationality`	string	64	Mandatory	Sender's nationality.
`remitterIdIssuePlace`	string	64	Optional	Place of ID issuance.
`remitterIdIssueDate`	string	64	Optional	Date of ID issuance.
`remitterIdExpiryDate`	string	64	Optional	Date of ID expiry.
`recipientName`	string	64	Mandatory	Recipient's full name.
`remitterFinancialInstitution`	string	64	Mandatory	Sender's financial institution.
`remitterSourceOfFunds`	string	64	Mandatory	Source of the sender's funds.
`remitterPrincipalActivity`	string	64	Mandatory	Sender's principal activity/occupation.
`remitterDateOfBirth`	string	64	Mandatory	Sender's date of birth.
`recipientAddress`	string	64	Optional	Recipient's address.
`recipientEmailAddress`	string	64	Optional	Recipient's email address.
`recipientPhoneNumber`	string	13	Mandatory	Recipient's phone number.
`recipientMCCMNC`	integer	6	Required Mobile only	Mobile Country Code/Mobile Network Code.
`recipientInstitutionIdentifier`	string	6	Optional (Only for Mobile)	Recipient's institution identifier.
`recipientPrimaryAccountNumber`	string	50	Mandatory	Recipient's account number (e.g., mobile number).
`recipientCCY`	integer	6	Mandatory	Recipient's currency code.
`recipientCountry`	string	3	Mandatory	Recipient's country code.
`recipientIdType`	string	3	Mandatory	Recipient's ID type.
`recipientIdNumber`	string	3	Mandatory	Recipient's ID number.
`recipientPurpose`	string	3	Mandatory	Purpose of the transaction.
`transactionRouteId`	guid	6	Mandatory	The ID of the transaction route.
`transactionAmount`	decimal	6	Mandatory	The amount of the transaction.
`transactionChannelType`	integer	6	Mandatory	The channel type of the transaction.
`transactionReference`	string	100	Mandatory	Reference for the transaction.
`transactionSystemTraceAudiNumber`	string	50	Mandatory	System Trace Audit Number.
`transactionCustomerAccountNo`	string	50	Optional	Customer Account Number.

Name Specification Note: The recipient and remitter names must adhere to the following specifications:
1.
Should contain at least two names.
2.
No capturing of initials.
3.
No input of numbers.
4.
A single space should be used between the names.

📊 Reference Codes

Transaction Status Types

Reference for the transactionStatus field on the Transfers callback payload.

Type	Description
0	Pending
1	Queued
2	Submitted
3	Submit Acknowledged
4	Success
6	Failed
7	Rejected
8	Timed Out

Category Types

Reference for the category field from the Find Transaction Routes request. Describes the transaction type for a particular route.

Type	Description
0	Mobile Wallet Transfer
1	Bank Transfer
4	Bill Payments
6	Business Transfers

Channel Types

Reference for the channel field from the Find Transaction Routes request. Describes the available transaction routes.

Type	Description
1	Mpesa
2	Pesalink
3	EFT
4	RTGS
6	B2B
8	Bill Payments
13	Business Buy Goods
14	Business PayBill
15	Business Deposit
16	Business To Business Transfer
17	Business Transfer From MMF To Utility
18	Business Transfer From Utility To MMF
19	Express Bank Transfer (via Paybill)
23	Business PayBill

Currencies

The API supports the following currencies:

Name	Code	Description
Kenyan Shillings	404	KES
Naira	566	NGN
Ghana Cedi	936	GHS
Tanzanian Shilling	834	TZS
Ugandan Shilling	800	UGX
U.S. Dollar (For Liberia)	840	USD
United Arab Emirates dirham	784	AED

MCCMNC Codes (Mobile Only)

Reference for the mccmnc field on the Payment Order Request for mobile transactions.

Code	Description
63902	Safaricom Kenya
63903	Airtel Kenya
63907	Telkom Kenya
64101	Airtel Uganda
64110	MTN Uganda
64111	Telcom Uganda
64114	Africell Uganda
64002	Tigo Tanzania
64003	ZANTEL Tanzania
64004	Vodacom Tanzania
64005	Airtel Tanzania
62001	MTN Ghana
61801	MTN Liberia

⚠️ Error Codes and Response Status

Zamupay Transactions Response Codes

Code	Description	Exception Rule	Comments
0	Success	Success
1	Insufficient funds at source account	Transient (retry with new ID)	Retry after funding the B2C account.
2	Transfer limit exceeded	Permanent (Fail and do not retry)
3	Internal server error	Transient (retry with new ID)
4	Third party internal server error	Transient (retry with new ID)
5	Invalid debit account (B2C)	Permanent (Fail and do not retry)
6	Invalid credit account	Permanent (Fail and do not retry)
7	Transfer amount below the limit	Permanent (Fail and do not retry)
8	Invalid transaction	Permanent (Fail and do not retry)
9	Duplicate transaction	Unknown (requery for status)	Requery the transaction.
10	Server busy	Transient (retry with new ID)
11	Transaction not found	Retry Transaction with same ID	Retry with same `originatorConversationID` or STAN.
12	General error	Permanent (Fail and do not retry)
13	Third party general failure	Permanent (Fail and do not retry)
14	Inconclusive status	Unknown (requery for status)	Requires manual resolution.
15	Insufficient wallet balance	Transient (retry with new ID)	Retry after funding the PYCS account.
16	Third party system unavailable	Permanent (Fail and do not retry)
17	AML Failure	Permanent (Fail and do not retry)
18	Declined	Permanent (Fail and do not retry)

Zamupay API Response Codes

Code	Description
200	The request was processed successfully.
202	The request has been accepted for processing.
401	Unauthorized request. Happens when the credentials (bearer token) have expired.
400	Bad request. Occurs due to validation errors (missing fields) or a duplicate entry (`originatorConversationId`).
404	Request URL not found.
429	Too many requests. Occurs when too many requests hit the API causing downtime.
500	Internal server error.

🔔 C2B IPN (Callback) Configuration

Navigate to Settings and switch to the Webhook Settings tab.

Check the Enable Transaction Webhooks? checkbox.

Provide your callbackUrl in the Url input box. This is where ZamuPay will send the response.

Optional: Check Is Secure? to set authentication (Username and Password) for the URL.

Set the format of the callback payload by selecting either JSON or XML.

Sample C2B Callback Response (JSON)

{
    "Id": "51539fcd-0b8e-eb11-826b-062ab3a3eac8",
    "CollectionType": "Mpesa",
    "PrimaryAccountNumber": "9abd2ba6fa3bf4847ba638040947a0945c3a4279effc96d8a6fe0db10ec76ccd",
    "InstitutionIdentifier": "301174",
    "InvoiceNumber": null,
    "Thirdpartyreceiptnumber": "PCQ1490463",
    "PaymentAmount": "1.00",
    "ThirdPartyTransID": null,
    "Payeeaccountnumber": "1",
    "Createddate": "2021-08-06T06:43:31.97",
    "Thirdpartypayload": null,
    "Payeename": "JOHN DOE"
}

🔔 Sample Payment Order Callback (JSON)

This payload is sent by the ZamuPay system to the configured callbackUrl for a Payment Order request.

{
  "id": "0c16c3a6-56a7-ec11-ab96-0ee00e897f52",
  "customerId": "a393c67c-158b-ec11-ab86-0ee00e897f52",
  "isEnabled": true,
  "remarks": "ERTU67897RQQEQ",
  "conversationId": "908cb9a6-56a7-ec11-ab96-0ee00e897f52",
  "originatorConversationId": "8f8cb9a6-56a7-ec11-ab96-0ee00e897f52",
  "dueDate": "2022-03-21T00:00:00",
  "dateApproved": null,
  "dateRejected": null,
  "isProcessed": true,
  "dateProcessed": "2022-03-19T07:32:04.3",
  "recordStatus": 2,
  "createdBy": "Flavian",
  "createdDate": "2022-03-19T07:31:55.85",
  "orderLines": [
    {
      "remitter": {
        "name": "John Gram",
        "address": "USA",
        "phoneNumber": "1-900-99398333",
        "idType": "National ID",
        "idNumber": "2000000",
        "country": "USA",
        "ccy": 404,
        "financialInstitution": "Bank",
        "sourceOfFunds": "Business",
        "principalActivity": "Business"
      },
      "recipient": {
        "name": "John Doe",
        "address": "Nyati",
        "emailAddress": "jjdoe@gmail.com",
        "phoneNumber": "",
        "idType": "National ID",
        "idNumber": "2000000",
        "financialInstitution": "Mpesa",
        "primaryAccountNumber": "+254714000000",
        "mccmnc": "63902",
        "ccy": 404,
        "country": "KE",
        "purpose": "TEST"
      },
      "transaction": {
        "routeId": "b1b67c98-84a6-ec11-ab96-0ee00e897f52",
        "amount": 10,
        "reference": "ERTU67897RQQEQ",
        "systemTraceAuditNumber": "0d4b10f3-e679-4a75-b737-11d7d8600fac",
        "type": 0,
        "channelType": 0,
        "customerAccountNo": null,
        "routeTransactionTypeId": "00000000-0000-0000-0000-000000000000"
      },
      "transactionOutcome": {
        "id": "0e16c3a6-56a7-ec11-ab96-0ee00e897f52",
        "paymentAmount": 10,
        "feeAmount": 2,
        "trackingNumber": "5O18CE9I",
        "transactionStatus": 4,
        "transactionStatusDescription": "Completed",
        "workingAccountAvailableFunds": 0,
        "utilityAccountAvailableFunds": 0,
        "transactionDate": "20220319073158",
        "transactionCreditParty": null,
        "resultCode": "0",
        "resultCodeDescription": "Success",
        "thirdPartyPayload": {
          "thirdPartyResultCode": "0",
          "thirdPartyResultCodeDescription": "Transaction processed successfully.",
          "thirdPartyReceiptNumber": null
        },
        "createdDate": "2022-03-19T07:31:55.85"
      }
    }
  ]
}

💳 ZamuPay API Documentation Summary#

📝 Data Definition for Payment Orders#

📊 Reference Codes#

Transaction Status Types#

Category Types#

Channel Types#

Currencies#

MCCMNC Codes (Mobile Only)#

⚠️ Error Codes and Response Status#

Zamupay Transactions Response Codes#

Zamupay API Response Codes#

🔔 C2B IPN (Callback) Configuration#

Sample C2B Callback Response (JSON)#

🔔 Sample Payment Order Callback (JSON)#