Mobile Transfers- Safaricom (M-Pesa)

There are 2 Types of Payment Order Requests:

Remittance Transactions
Both Remitter and Recipient details are mandatory.

Normal Transactions
The Remitter details are optional and the Remitter body can be omitted from the request

NB: For any fields marked as Optional, they can be omitted entirely from the request

Koba supports outbound payments (B2C) via Mobile Transfers to M-Pesa wallets.

This integration is for Safaricom M-Pesa.

Confirm the MCCMNC codes from the Koba Data Types Documentation:
https://docs.Koba.com/data-types-1946182m0
and scroll to the MCCMNC codes section.

Use the Find Transaction Routes API:
https://docs.Koba.com/find-transaction-routes-25375898e0
to get the route ID and channel type.

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

Sample Mobile Transfer Request - M-Pesa

{
	"originatorConversationId": "BBS217380556926",  //Mandatory - Must be Unique with each Request
	"paymentNotes": "Salary Payment", //Mandatory -A brief description of the Payment
	"paymentOrderLines": [
		{
			"remitter": { // Remitter body is Mandatory if Remittance request, Optional if Normal Transaction
				"name": "Nicholas Kimeli Koskei",
				"address": "74 Honeywell Blvd Perth",
				"phoneNumber": "+41478565808",
				"idType": "National ID",
				"idNumber": "189537279",
				"dateOfBirth": "1997/08/14",
				"country": "AU",
				"nationality": "AU",
				"ccy": 36,
				"financialInstitution": "TFS",
				"sourceOfFunds": "Salary",
				"principalActivity": "Family"
			},
			"recipient": {
				"name": "Juliet Kimeli", //Mandatory-  you can  pass your company name, e.g. "SwiftTech Ltd"
				"phoneNumber": "+254777772240",  //Optional- Safaricom based Phone number
				"financialInstitution": null, // Optional - can be passed as null
				"primaryAccountNumber": "+254799992240", // Mandatory -  Safaricom based Phone number
				"address": "56 Westlands Street", // Optional - you can pass your company's address
				"idNumber": "22068155", // Optional - you can pass your company's registration/identification number 
				"mccmnc": "63902", // Mandatory - refer to the API docs for the applicable value
				"ccy": 404, // Mandatory - ISO 4217 numeric currency code; refer to the API docs
				"country": "KE", // Mandatory - ISO 3166-1 alpha-2 country code
				"purpose": "Family",  // Optional - common values include Family, Savings, Utilities, Business, Support, Education, etc.
				"institutionIdentifier": "0000" // Optional - pass "0000" if not applicable
			},
			"transaction": {
				"routeId": "4a45b519-0d3b-1111-8286-062ab3a3eac8",  // Mandatory - Fetch from Find Transaction Routes endpoint
				"ChannelType": 1,  // Mandatory- Fetch from Find Transaction Routes endpoint
				"amount": 1100,  //Mandatory
				"reference": "Salary Payment",  // Mandatory - A brief description or reference for the payment, e.g. "Salary Payment", "Invoice Payment"
				"systemTraceAuditNumber": "DDS217380BB6" //Mandatory - Must be Unique with each Request			}
		}
	]
}

For Normal Transactions, this is a sample request containing only the minimum mandatory fields:

{
  "originatorConversationId": "{{$guid}}",
  "paymentNotes": "Salary Payment",
  "paymentOrderLines": [
    {
      "recipient": {
        "name": "SwiftTech Ltd",
        "primaryAccountNumber": "+254717245242",
        "mccmnc": "63902",
        "ccy": 404,
        "country": "KE"
      },
      "transaction": {
        "routeId": "b1d92ea1-5751-8fa4-8217-019ed12ba5bf",
        "ChannelType": 1,
        "amount": 350,
        "reference": "Salary Payment",
        "systemTraceAuditNumber": "{{$guid}}"
      }
    }
  ]

Sample Response

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

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Mobile Transfers- Safaricom (M-Pesa)

Sample Mobile Transfer Request - M-Pesa#

For Normal Transactions, this is a sample request containing only the minimum mandatory fields:#

Sample Response#

Request

Responses

Sample Mobile Transfer Request - M-Pesa

For Normal Transactions, this is a sample request containing only the minimum mandatory fields:

Sample Response