Payment Order Request

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 mobile request

{
  "originatorConversationId": "12211t21412vr434345545x",
  "paymentNotes": "Transactions",
  "paymentOrderLines": [
    {
    "remitter": {
        "name": "Einstien James Bela",
        "address": "49 abc",
        "phoneNumber": "+4491509874561",
        "idType": "NATIONALIDCARD",
        "idIssuePlace": null,
        "idNumber": "123456789",
        "idIssueDate": null,
        "idExpireDate": null,
        "nationality": "US",
        "country": "KE",
        "ccy": "404",
        "financialInstitution": "Bank",
        "sourceOfFunds": "Salary",
        "principalActivity": "Business",
        "dateOfBirth": null,
        "state": null,
        "city": null,
        "postalCode": null
      }
      "recipient": {
        "name": "John Doe",
        "address": "Nyati",
        "emailAddress": "kkhaliboy@gmail.com",
        "phoneNumber": "",
        "idType": "National ID",
        "idNumber": "28475979",
        "financialInstitution": "Mpesa",
        "primaryAccountNumber": "+254714789009",
        "mccmnc": "63902",
        "ccy": 404,
        "country": "KE",
        "purpose": "TEST"
      },
      "transaction": {
        "routeId": "90d7e7a0-2a12-ec11-aaa1-c7e0fb8016f8",
        "channelType": 1,
        "customerAccountNo":"1224355633",
        "amount": 1111,
        "reference": "s1199111s5cdd12r32rwwewsuyitt",
        "systemTraceAuditNumber": "22f323f3241s14sswwwin9uihjf"
      }
    }
  ]
}

Sample Bank request

{
  "originatorConversationId": "12211t21412vr434345545x",
  "paymentNotes": "Transactions",
  "paymentOrderLines": [
    {
    "remitter": {
        "name": "Einstien James Bela",
        "address": "49 abc",
        "phoneNumber": "+4491509874561",
        "idType": "NATIONALIDCARD",
        "idIssuePlace": null,
        "idNumber": "123456789",
        "idIssueDate": null,
        "idExpireDate": null,
        "nationality": "US",
        "country": "KE",
        "ccy": "404",
        "financialInstitution": "Bank",
        "sourceOfFunds": "Salary",
        "principalActivity": "Business",
        "dateOfBirth": null,
        "state": null,
        "city": null,
        "postalCode": null
      }
      "recipient": {
        "name": "John Doe",
        "address": "Nyati",
        "emailAddress": "kkhaliboy@gmail.com",
        "phoneNumber": "",
        "idType": "National ID",
        "idNumber": "100000000",
        "financialInstitution": "Bank",
        "institutionIdentifier": "GAFRKENAXXX",
        "primaryAccountNumber": "0122000000",
        "ccy": 404,
        "country": "KE",
        "purpose": "TEST"
      },
      "transaction": {
        "routeId": "90d7e7a0-2a12-ec11-aaa1-c7e0fb8016f8",
        "ChannelType": 1,
        "amount": 1111,
        "reference": "s1199111s5cdd12r32rwwewsuyitt",
        "systemTraceAuditNumber": "22f323f3241s14sswwwin9uihjf"
      }
    }
  ]
}

Sample Business request

{
  "originatorConversationId": "12211t21412vr434345545x",
  "paymentNotes": "Transactions",
  "paymentOrderLines": [
    {
    "remitter": {
        "name": "Einstien James Bela",
        "address": "49 abc",
        "phoneNumber": "+4491509874561",
        "idType": "NATIONALIDCARD",
        "idIssuePlace": null,
        "idNumber": "123456789",
        "idIssueDate": null,
        "idExpireDate": null,
        "nationality": "US",
        "country": "KE",
        "ccy": "404",
        "financialInstitution": "Bank",
        "sourceOfFunds": "Salary",
        "principalActivity": "Business",
        "dateOfBirth": null,
        "state": null,
        "city": null,
        "postalCode": null
      }
      "recipient": {
        "name": "John Doe",
        "address": "Nyati",
        "emailAddress": "kkhaliboy@gmail.com",
        "phoneNumber": "",
        "idType": "National ID",
        "idNumber": "200000000",
        "financialInstitution": "Business",
        "institutionIdentifier": "172989",
        "primaryAccountNumber": "172989",
        "ccy": 404,
        "country": "KE",
        "purpose": "TEST"
      },
      "transaction": {
        "routeId": "90d7e7a0-2a12-ec11-aaa1-c7e0fb8016f8",
        "ChannelType": 1,
        "amount": 1111,
        "reference": "s1199111s5cdd12r32rwwewsuyitt",
        "systemTraceAuditNumber": "22f323f3241s14sswwwin9uihjf"
      }
    }
  ]
}

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"
      }
    }
  ]
}

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Sample mobile request#

Sample Bank request#

Sample Business request#

Sample success response#

Sample failed response#

Sample validation errors response#

Sample Duplicate callback response#

Sample callback response#

Request

Responses