1. Payment Request
ZamuPay API Documentation
  • Introduction
  • Definitions
    • Data Types
  • Authorization
    • Overview
    • Token Request
      POST
    • Find Transaction Routes
      GET
    • Health Check
      GET
  • Payment Request
    • Overview
    • Payment Order Request Information
    • Mobile Money Requests
      • Overview
      • Mobile Transfers- Safaricom (M-Pesa)
      • Mobile Transfers - Airtel Money
    • Payment Order Requests - Business Transfers
      POST
    • Payment Order Requests - Bank Transfers
      POST
    • Find Payment Order By OriginatorConversationId
      GET
    • Reject Order By OriginatorConversationId
      POST
  • Collection Request
    • Overview
    • Express Deposit Request
      POST
    • Find Express Deposit By OriginatorConversationId
      GET
  • Checkout Request
    • Overview
    • Checkout Order Request
      POST
    • Query Checkout Request
      GET
    • Checkout Callback Request
      POST
  • Bill Payments
    • Overview
    • Bill Request Validation
      POST
    • Bill Request Payment
      POST
    • Find Bill Services
      GET
    • Find Bill Number By Service Id and Account Number
      GET
    • Find Bill Request By Originator Converstion Id
      GET
    • Bill Number
      POST
  • Account Validation
    • Overview
    • Account Number Validation Request
    • Find KYC Status by SystemTraceAuditNumber
    • Account Validation
    • Find Account Validation Status by SystemTraceAuditNumber
  • Payment Links
    • Overview
    • Create Payment Link
    • Find Payment Links By Id
    • Update Payment Link
  • Customer Accounts
    • Balance Check
    • Find Charges By TransactionTypeId
  • Airtime Purchase
    • Overview
    • Airtime Purchase
    • Find Airtime Purchases By OriginatorConversationId
  1. Payment Request

Payment Order Request Information

This section gives more information related to the payment order request API.
This includes Descriptions for each field required in the payload, Sample Success Response, Sample Failed Response, Sample Validation Errors Response, Sample Success Callback Response and Sample Duplicate Callback Response


Note: A valid token is required for authentication as it expires after every hour. Refer to Token Request to generate a new token.

originatorConversationId This a unique identifier of the request from the client
paymentNotes This a brief summary of the request
remitter: This information is only required for a Payment Remittance Company
name: Name of the remitter
contact: Remitter's contact
address: Address of the remitter
idType: remitter Id type e.g. National ID, Passport
idNumber: remitter Id type number
country:This is the remitter's ALPHA 2 code. Follow ALPHA to learn more.
ccy: Remitter's currency code
financialInstitution: Remitter's financial institution
sourceOfFunds: Remitter's source of funds
principalActivity: Remitter's principal activity
dateOfBirth:The birth date of the sender in the format yyyy/mm/dd
idIssueDate:National identification card issue date of the sender in the format yyyy/mm/dd(This field is optional)
idIssuePlace: Location where the national ID was issued (This field is optional)
idExpiryDate: The expiration date of the national ID of the sender in the format yyyy/mm/dd(This field is optional)
nationality: The country where the sender is from e.g. American
recipient: These are the recipient's details
name: Name of recipient
address: Address of the recipient
emailAddress: Email address of the recipient
contact: Contact of the recipient
idType: Id type of the recipient
idNumber: Id number of the recipient
mccmnc:Mobile country code. Follow this link, MCCMNC, to find out more about the codes. Only mandatory for Mobile payment order requests.
financialInstitution: Recipient financial institution
institutionIdentifier: An identifier of the recipient institution. This is mandatory for Bank and Business payment order requests. Bank uses SWIFT code e.g. GAFRKENAXXX or an account number while the Business uses a Paybill number(this is a Bank's Paybill).
primaryAccountNumber:This is the account number being credited
ccy:This is the currency code of the recipient
country:This is the recipient's ALPHA 2 code. Follow ALPHA to learn more.
purpose:This is the purpose of the transfer.
transaction: The following are the transaction details:
routeId: Id of the route transaction to be used for the transaction.This id is generated from the FindTransactionRoutes request.
channelType: This is the channel transaction type. It is received after querying the Find Transaction Routes request
amount: Amount to be transferred
customerAccountNo: Account number to be used. This is an optional field only required if the partner has more than one account and wants to use a specific one that is not the default account
reference: A reference for the transaction
systemTraceAuditNumber: Unique identifier of the transaction from the client
NOTE: For duplicate requests, the transaction will be accepted but instead expect a callback to be sent. Refer to the Sample Duplicate Callback Response for an example.

Sample success response#

{
  "message": {
    "appDomainName": "LIVE",
    "systemConversationId": "16780000-a97d-3024-8e07-08d93713929d",
    "originatorConversationId": "origiqjwwqwqnnmqeqersationId",
    "remarks": "order submission accepted",
    "timestamp": "2021-06-24T13:25:49.5292326Z"
  }
}

Sample failed response#

{
    "appDomainName": "LIVE",
    "status": "BadRequest",
    "timestamp": "2022-02-11T10:13:11.2483928Z",
    "systemConversationId": "16780000-a97d-3024-98a9-08d9ed471bab",
    "originatorConversationId": "W93323321ei4455t40093334xxiuigggtey",
    "errors": [
          {
             "field": "PaymentOrderLines[0].Remitter",
             "message": "The Remitter field is required."
          }
      ]
}

Sample validation errors response#

{
    "appDomainName": "LIVE",
    "status": "BadRequest",
    "timestamp": "2022-02-11T10:13:11.2483928Z",
    "systemConversationId": "16780000-a97d-3024-98a9-08d9ed471bab",
    "originatorConversationId": "W93323321ei4455t40093334xxiuigggtey",
    "errors": [
          {
             "field": "PaymentOrderLines[0].Recipient",
             "message": "The Recipient field is required."
          }
      ]
}

Sample Duplicate callback response#

Kindly note the following will be the response in case a duplicate request is sent. The details will be seen under the transcationOutcome part of the callback.
{
    "id": "00000000-0000-0000-0000-000000000000",
    "customerId": "f45eca19-d0df-eb11-aa67-8d094e8aa279",
    "isEnabled": false,
    "remarks": null,
    "conversationId": null,
    "originatorConversationId": "UA5L3LSL53W5P07KWG54",
    "dueDate": "0001-01-01T00:00:00",
    "dateApproved": null,
    "dateRejected": null,
    "isProcessed": false,
    "dateProcessed": null,
    "recordStatus": 0,
    "createdBy": null,
    "createdDate": "2022-04-28T14:52:57.1131933+03:00",
    "orderLines": [
        {
            "remitter": {
                "name": null,
                "address": null,
                "phoneNumber": null,
                "idType": null,
                "idNumber": null,
                "idIssuePlace": null,
                "idIssueDate": null,
                "idExpireDate": null,
                "country": null,
                "nationality": null,
                "ccy": null,
                "financialInstitution": null,
                "sourceOfFunds": null,
                "principalActivity": null,
                "dateOfBirth": null
            },
            "recipient": {
                "name": "John Doe",
                "address": "28 Nii sackey street",
                "emailAddress": "test@gmail.com",
                "phoneNumber": "+254700000000",
                "mccmnc": "63902",
                "idType": "National Id",
                "idNumber": "10000000",
                "primaryAccountNumber": "+254713771963",
                "financialInstitution": "Business",
                "institutionIdentifier": null,
                "ccy": "404",
                "purpose": "Withdraw Amount from wallet",
                "country": null
            },
            "transaction": {
                "routeId": "dadcb601-7089-ec11-ab85-0ee00e897f52",
                "amount": 200,
                "reference": "16000000000",
                "systemTraceAuditNumber": "UA5L3LSL53W5P07KWG54",
                "type": 0,
                "channelType": 0,
                "customerAccountNo": null,
                "routeTransactionTypeId": "00000000-0000-0000-0000-000000000000"
            },
            "transactionOutcome": {
                "id": "00000000-0000-0000-0000-000000000000",
                "paymentAmount": 0,
                "feeAmount": 0,
                "trackingNumber": null,
                "transactionStatus": 6,
                "transactionStatusDescription": "Failed",
                "workingAccountAvailableFunds": 0,
                "utilityAccountAvailableFunds": 0,
                "transactionDate": null,
                "transactionCreditParty": null,
                "resultCode": "9",
                "resultCodeDescription": "Duplicate transaction",
                "thirdPartyPayload": null,
                "createdDate": "2022-04-28T14:52:57.1131933+03:00"
            }
        }
    ]
}

Sample callback response#

NOTE: There are particular fields to note in the callback response incase there is a failed status in the transactionStatus field:
resultCode:This is the code shown as defined under the Error Codes section
resultDescription:This is the description of the resultCode
thirdPartyPayload:This body contains fields that gives the exact resultCode and resultDescription from the third party e.g M-Pesa as shown above. The fields are thirdPartyResultCode and thirdPartyResultDescription
{
  "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-99300000",
        "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"
      }
    }
  ]
}
Modified at 2026-04-20 10:04:46
Previous
Overview
Next
Overview
Built with