1.0 \n\nOAS3\n\nHandaki is a JSONAPI specs formatted MPESA REST API. An enterprise grade alternative to MPESA Daraja. It aims to give developers a smooth experience while integrating to MPESA by offering
\nBEAUTIFUL API that is clear, concise and simple.For those interested, here is the match up that led to Handaki. Why the name Handaki™? Well.. because tunnels are way cooler than bridges!!!
\nHere is a presentation with more of the features that make handaki a great alternative for developers.
\nPostman is a favorite for many developers. We have put together two collections to help you integrate easily to Handaki.
\nHandaki Uses token authentication with HMAC signing, a secure asymmetric encryption algorithm that does not compromise simplicity for security. Refer here for a quick introduction to the security scheme. The developer will be assigned both a key and a secret which will be used to build the HMAC headers. Here are scripts for generating HMAC headers required for authentication:
Here is an example of HMAC authorization headers:
\nDate: Fri, 22 Nov 2019 08:47:01 GMT\nX-Custom: custom\nAuthorization: keyId=\"0f14b9acfedf4993ba73921e32de169b\",algorithm=\"hmac-sha256\",headers=\"date x-custom\",signature=\"FhJ/H0sMU3gcOAE/cUBjFaTYeUw3WQj9d8x2xGFVrNE=\"\n\nNote that the Date header should be expressed in GMT and NOT local time.
\nHMAC Clock Skew, an added feature of HMAC prevents replay attacks by checking that the timestamp lies within a few milliseconds of the request time. Clock skew ensures that, if key gets in the wrong hands through MITM interception or otherwise, it cannot be used.
Note about HMAC on Handaki: Authentication failure will result into status code 400 as opposed to 401
This resource describes a transfer transaction request that originates from the developer to MPESA system for processing and eventual crediting of the organization's account upon successful processing. Commonly referred to as a B2B transaction. Simply put, it is the process of sending money from a shortcode to another shortcode.
\nid represents a unique string generated on the developers system for universally unique identification purpose.
category represents the type of the business transaction. Defaults to BusinessPayBill. Possible values are;
- `BusinessPayBill`.\n - `BusinessBuyGoods`. \n - `AgencyFloatAdvance` \n - `MerchantToMerchantTransfer`.\n - `DisburseFundsToBusiness`.\n\namount represents the amount of money to be credited to the end user's MPESA wallet.
recipient_type represents the type of account to be credited. The value should be short_code.
recipient_no represents the short_code of the organization receiving the transaction.
posted_at represents time in UTC standard format at which the transaction was initiated.
reference represents the account number for transfers to a paybill
Request for payment from a customer via Mpesa STK push.
\nPossible category values;
customer_type is optional and defaults to msisdn
Query status of a transaction or shortcode balances
\nYou can query for a transaction using 3 possible ids(values for the on field);
resource_id - user provided idtxn_id - Mpesa Receipt numberresponse_id - Mpesa generated idThe value of q should be the actual id
Change the value of the :query path param to balance to query for balances for the passed in short_code.
This resource describes a pay out transaction request that originates from the developer to MPESA system for processing and eventual crediting of the end customer's wallet upon successful processing. Commonly referred to as a B2C transaction. Simply put, it is the process of sending money from a shortcode to a customer or another shortcode.
\nid represents a unique string generated on the developers system for universally unique identification purpose.
category represents the type of the business transaction. Defaults to BusinessPayment. Possible values are;
- `BusinessPayment`.\n- `BusinessPaymentWithWithdrawalChargePaid`.\n- `SalaryPayment`.\n- `SalaryPaymentWithWithdrawalChargePaid`.\n- `SalaryPaymentUnregisteredUser`.\n- `PromotionPayment`.\n- `PromotionPaymentUnregisteredUser`.\n\namount represents the amount of money to be creditted to the end user's MPESA wallet.
recipient_type represents the type of account to be credited. The value should be msisdn.
recipient_id_number is an optional attribute that represents the ID of the recipient. It's useful for validation before disbursement of funds is done.
recipient_id_type is an optional attributes that represents the type of id provided. Could be represented by (01-National ID, 02-Military ID, 03-Alien, 04-Diplomatic, 05-Passport)
recipient_no represents the MSISDN number of the person receiving the transaction.
posted_at represents time in UTC standard format at which the transaction was initiated.
This allows for an easy access to Quikk's M-PESA sandbox. It aids you in completing a full cycle of tests, including the requests made by the developer, the responses received, and the callbacks that the developer obtains.
\nYou'll need callback URLs, a Key and Secret provided by Quikk. Insert/replace the variables with the API credentials (Key, Secret) we have provided. To request for your API credentials, please email dean@quikk.dev.
\n","_postman_id":"7633355d-284d-4603-907c-27ae5c7a4126"},{"name":"MPESA SIMULATIONS","item":[{"name":"payin","item":[{"name":"Payin validation callback","id":"b946e762-7e77-4c6a-93fd-7c37999bb55f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/vnd.api+json"},{"key":"Accept","type":"text","value":"application/vnd.api+json"},{"key":"x-your-custom-header","value":"header-value","type":"text"}],"body":{"mode":"raw","raw":"{\n \"data\": {\n \"type\": \"payin\",\n \"attributes\": {\n \"txn_id\": \"NH701HA94Y\",\n \"sender_no\": \"2547*****459\",\n \"sender_no_sha1\": \"f001d87b438ff2959d6786f02d7dfa0fa2bbd17b\",\n \"sender_name\": \"John J D\",\n \"sender_type\": \"msisdn\",\n \"amount\": 1000,\n \"txn_created_at\": \"2022-07-01T11:00:49+0300\",\n \"short_code\": \"60134\",\n \"reference\": \"NTSPF6038\",\n \"category\": \"PayBill\"\n }\n }\n}"},"url":"http://localhost/developer_app/payins","description":"This resource describes a pay in transaction that is sent in by MPESA to a developers system for validation purpose. The validation is meant to ensure that the end customer made a valid transaction from his/her mobile end. Validation of a transaction triggers a cancellation or acceptance of the MPESA transaction. Commonly referred to as a C2B transaction.
\ntxn_id represents transaction id that MPESA generates to uniquely identify a transaction that has been initiated on its system.
category represents the kind of transaction being made. The transaction can fall under one of the following categories Merchant_payment, paybill_payment or paybill_transfer.
txn_created_at represents the time at which the transaction was initiated. It is in the UTC standard format.
sender_type represents the mpesa transaction initiator type. The value can be either msisdn or shortcode.
sender_no represents the MSISDN number of the customer that initiated the transaction from his/her mobile end.
sender_name represents the full names(as registered on MPESA system) of the person initiating the transaction.
amount represents the amount of money transacted.
short_code represents the shortcode commonly known as paybill number or Business Number to which the transaction was made.
reference represents the account number or name to which the transaction should be associated with. Used for Paybills channel
balance_working_ac represents the balance of your working account on MPESA system.
This resource describes a pay in transaction that is sent in by MPESA to a developers system for Confirmation purpose. The confirmation is an affirmation of a successful transaction on MPESA system.
\ntxn_id represents transaction id that MPESA generates to uniquely identify a transaction that has been initiated on its system.
category represents the kind of transaction being made. The transaction can fall under one of the following categories Merchant_payment, paybill_payment or paybill_transfer.
txn_created_at represents the time at which the transaction was initiated. It is in the UTC standard format.
sender_type represents the mpesa transaction initiator type. The value can be either msisdn or shortcode.
sender_no represents the MSISDN number of the customer that initiated the transaction from his/her mobile end.
sender_name represents the full names(as registered on MPESA system) of the person initiating the transaction.
amount represents the amount of money transacted.
short_code represents the shortcode commonly known as paybill number or Business Number to which the transaction was made.
reference represents the account number or name to which the transaction should be associated with. Used for Paybills channel
balance_working_ac represents the balance of your working account on MPESA system.
This resource describes a pay in transaction that is sent in by MPESA to a developers system for Confirmation purpose. The confirmation is an affirmation of a successful transaction on MPESA system.
\ntxn_id represents transaction id that MPESA generates to uniquely identify a transaction that has been initiated on its system.
category represents the kind of transaction being made. The transaction can fall under one of the following categories Merchant_payment, paybill_payment or paybill_transfer.
txn_created_at represents the time at which the transaction was initiated. It is in the UTC standard format.
sender_type represents the mpesa transaction initiator type. The value can be either msisdn or shortcode.
sender_no represents the MSISDN number of the customer that initiated the transaction from his/her mobile end.
sender_name represents the full names(as registered on MPESA system) of the person initiating the transaction.
amount represents the amount of money transacted.
short_code represents the shortcode commonly known as paybill number or Business Number to which the transaction was made.
reference represents the account number or name to which the transaction should be associated with. Used for Paybills channel
balance_working_ac represents the balance of your working account on MPESA system.
This resource describes a pay in transaction that is sent in by MPESA to a developers system for Confirmation purpose. The confirmation is an affirmation of a successful transaction on MPESA system.
\ntxn_id represents transaction id that MPESA generates to uniquely identify a transaction that has been initiated on its system.
category represents the kind of transaction being made. The transaction can fall under one of the following categories Merchant_payment, paybill_payment or paybill_transfer.
txn_created_at represents the time at which the transaction was initiated. It is in the UTC standard format.
sender_type represents the mpesa transaction initiator type. The value can be either msisdn or shortcode.
sender_no represents the MSISDN number of the customer that initiated the transaction from his/her mobile end.
sender_name represents the full names(as registered on MPESA system) of the person initiating the transaction.
amount represents the amount of money transacted.
short_code represents the shortcode commonly known as paybill number or Business Number to which the transaction was made.
reference represents the account number or name to which the transaction should be associated with. Used for Paybills channel
balance_working_ac represents the balance of your working account on MPESA system.
This describes a resource transaction that's sent to the developer's system upon successful processing and crediting of funds to a MPESA customer. It is similar to the callback resource described in the callback event of the pay_out request. This endpoint accepts any http method that supports raw json body.
\nid represents a unique string for identification of the pay out transaction. It is the same id value generated on the developers system while initiating the request.
response_id represents a unique id that's generated on MPESA system for the original request message.
txn_id represents transaction id that MPESA generates to uniquely identify a transaction that has been initiated on its system.
amount represents the amount of money transacted
recipient_type represents the mpesa transaction recipient type. The value can be either msisdn or shortcode.
recipient_name represents the full names(as registered on MPESA system) of the transaction's recipient.
recipient_no represents the MSISDN number of the recipient customer.
txn_created_at represents the time at which the transaction was initiated. It is in the UTC standard format.
recipient_registered represents the registration status of the customer recipient on the MPESA system
balance_utility_ac represents amount of the available balance of the organization’s Utility Account, which is the debit account of the transaction.
balance_charges_paid_ac represents amount of the available balance of the organization’s Charge Paid Account, which is the debit account of the transaction charge.
currency represents the currency code for the amount being transacted.
M-PESA Simulation is our internally built M-PESA sandbox. It allows you to test your callback endpoints outside the normal request-response-result cycle. All you need to do is to add your endpoints. Click \"Run in Postman\" to get started.
\nMpesa simulation provides for Mpesa callbacks that would be sent to you, the developer. You can't get a callback without the normal request-response-result cycle. So, if you want to get the look and feel of the callbacks without actually making the initial request use this collection.
\nYou should test this collection first if you are using the C2B API.
\n","_postman_id":"462d6171-f9db-4e06-aa46-75d3e4878074"}],"event":[{"listen":"prerequest","script":{"id":"5a68e780-ccd3-41e1-a314-656de57000a9","type":"text/javascript","exec":["var today = new Date();","var requestDate = today.toUTCString();","var apiSecret = pm.variables.get('secret');","var keyId = pm.variables.get('key');","","// set posted_at to be used in charge","pm.environment.set('posted_at', today.toISOString());","","// prepare request headers","pm.environment.set('date', requestDate);","","// prepare signature string","var signatureContentString = 'date: ' + requestDate;","","// sha-1 encode signature","var sigString = CryptoJS.HmacSHA1(signatureContentString, apiSecret);","","var signatureString = encodeURIComponent(CryptoJS.enc.Base64.stringify(sigString));","","pm.environment.set(\"signatureString\", signatureString);","pm.environment.set(\"keyId\", keyId);",""]}},{"listen":"test","script":{"id":"708617a5-73c3-445b-8d75-b7c77322ffce","type":"text/javascript","exec":[""]}}],"variable":[{"key":"url","value":"https://tryapi.quikk.dev","type":"string"},{"key":"key","value":"","type":"string"},{"key":"secret","value":"","type":"string"}]}