Partner software system documentation v1.0
This documentation is to help you regarding each step of accessing our information. Please go through the documentation carefully to understand how our web service works. Basic JSON and HTTP knowledge is required to simulate or integrate the API
You will need the following software or their equivalence to get started.
To access our stk endpoints, you MUST HAVE AN API KEY which can be found in your admin link.
https://tinypesa.com/api/v1/express/initialize
| Header | Description | Value |
|---|---|---|
| Accept | The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. | application/json |
| Apikey | Unique api key obtained from your admin link | Dfw3sdfx234F |
The body required to initialize an stk transaction is the target phone number and amount as shown below.
In a success response, the request_id is given for reference in the webhook as the TinyPesaID.
| Parameter | Description | Sample Value |
|---|---|---|
| amount | The amount to request your customer in KES | 100 |
| msisdn | The phone number to charge this amount | 0712345678 or 254712345678 |
| account_no | Optional | This is is a custom reference sent over the webhook as ExternalReference |
{
"amount": [
"The amount field is required."
],
"msisdn": [
"The msisdn field is required."
]
}
{
"success": true,
"request_id": "f866567603d2b51ede711863d0f3d756deb08085393"
}
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Tinypesa will foward the STK callback to your configured webhook in the following json format
The result code in the request body should guide you
Success-"ResultCode": 0. The CallbackMetadata->Item list may be of varied length and is mapped directly as is from safaricom
{
"Body": {
"stkCallback": {
"MerchantRequestID": "26773-830618-1",
"CheckoutRequestID": "ws_CO_21042021114416028704",
"ResultCode": 0,
"ResultDesc": "The service request is processed successfully.",
"CallbackMetadata": {
"Item": [
{
"Name": "Amount",
"Value": 1
},
{
"Name": "MpesaReceiptNumber",
"Value": "PDL72WRAVZ"
},
{
"Name": "TransactionDate",
"Value": 20210421114425
},
{
"Name": "PhoneNumber",
"Value": 254718942538
}
]
},
"TinyPesaID": "c002f860-a27d-11eb-a7f4-c141263d7c15",
"ExternalReference": "customacct",
"Amount": 1,
"Msisdn": "254718942538"
}
}
}
Sample error
{
"Body": {
"stkCallback": {
"MerchantRequestID": "25395-1644131-1",
"CheckoutRequestID": "ws_CO_26022021085632641774",
"ResultCode": 1031,
"ResultDesc": "Request cancelled by user",
"TinyPesaID": "f8ac0d60-7a14-11eb-ba1d-e3a49273aa65",
"ExternalReference": "customacct",
"Amount": 1,
"Msisdn": "254718942538"
}
}
}
https://tinypesa.com/api/v1/express/create_link
In some instances, your platform might require merchants to self onboard and use their preferred mode of payment. In this case,
each merchant is required to have their dedicated tinypesa short link and apikey to initialize stk requests as shown above.
A request to create a link has the following expected parameters
NOTE: TheAPIKEYused in the following request is themaster account api keythat can be found in the developers section
| Header | Description | Value |
|---|---|---|
| Accept | The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. | application/json |
| ApiKey | Unique api key obtained from your tinypesa dashboard | Dfw3sdfx234F |
| Parameter | Description | Possible Value |
|---|---|---|
| name | Merchant or link name | Juicy caffe |
| description | [Optional] a short merchant description | Order smoothies near you |
| link_mode | The payment mode preferred by the merchant
|
1 or 2 or 3
|
| short_code | The paybill or till number the merchant uses. Required if the link mode is 1 or 2 | 123456 |
| account_number | [Optional] Required if a short code was specified | sales |
| bank | [Optional] Required if the link mode is bank | uuid from banks list |
| bank_acc_no | [Optional] Required if the link mode is bank. This is the bank account number the merchant holds under selected bank above | 011342436400 |
| call_back_url | [Optional] Link called after every tinypesa transaction | https://IP or https://domain |
Sample success response with an api_key that can be used henceforth to trigger stk payments
{
"name": "sample link",
"payment_mode": "BANK",
"short_code": null,
"account_number": "345235623532",
"api_key": "7dme5tvNFPi",
"bank_id": "bd01f820-7f2e-11eb-84bc-99d41292b108"
}
To create a merchant with bank as preferred mode of payment, a valid bank id is required. The list of banks with
their respective IDs can be obtained here.
https://tinypesa.com/api/v1/express/banks_list
Sample JSON list response
[
{
"name": "ABC Bank",
"id": "bd01f820-7f2e-11eb-84bc-99d41292b108"
},
{
"name": "Bank of Africa(BOA)",
"id": "bcec6850-7f2e-11eb-b3d3-ed6ab31db17b"
}...
]