Tutorial: Integrating your app with a Sidian Bank account via API

Use cases

Regulated by the Central Bank of Kenya, Sidian Bank(formerly K-Rep Bank) is a full-service commercial bank, providing an array of financial services to individuals and enterprises.

With the rising technology adoption in Africa to automate business workflows, there’s a huge need to enable merchants and service providers to integrate their Sidian bank accounts with inhouse apps and software like:

1) Sales e.g POS.

2)Accounting, payment reconciliation and compliance tools.

3) Invoicing & billing automation.

4)E-commerce and online shopping checkout among other use cases.

Onboarding and API Access

Note: You need to have an active account with Sidian Bank Kenya as prerequisite.

Tuma Payment Gateway enables you to connect your app with personal or business Sidian Bank account as well as merchant till numbers in minutes. Simply follow these steps.

1) Sign up here: https://merchant.tuma.co.ke

2) Fill all fields. NB: Enter full name as it appears in your National ID

3) Create your business name and configure bank details. Select Sidian Bank and enter your account number, then click ‘create business‘.

NB: For API access, you must provide an email address for the business profile. It can still be your personal email address but it’s required for API access. The email field is only optional for portal use cases.

4) Go to Developer option, select business profile, then click generate API keys.

Aunthentication and Code samples

Extract API key and use it along with business email address to authenticate and generate access token.

Authentication

Endpoint : https://api.tuma.co.ke/auth/token

Method: POST

Content-Type: application/json

Payload

{
  "email": "[email protected]",
  "api_key": "tuma_ec7d6eab48c4432ab0f144c7b7fc1b4819_1759998878"
}

Response

{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInRCJ9.eyJzaG9wX2lkIjoiNzg3ZTI0NGQtOTRhOC00ODgxLWJjNzctNDc2ZGZkNjA3ZGJlIiwidXNlcl9pZCI6ImQyYTY5NWVkLTg1MWUtNGZiYy1iOTUiIsImVtYWlsIjoic2hhZHJhY2subWF0YXRhQGljbG91ZC5jb20iLCJpcHJzX2FjY2VzcyI6ZCI6MTc2MzU0MjY2NywiZXhwIjoxNzYzNjI5MDY3fQ.3FHTZ9ENc_C-C8-AvQEXroIeNYD5Ncv5eEhB4WpEKaY",
    "shop": {
      "id": "787e244d-94a8-4881-bc77-476dfd607dbe",
      "name": "Tuma Limited",
      "email": "[email protected]"
    }
  }
}

Initiating Payment Request

With the access token you can now initiate payment request via STK push prompt for any mobile payment network.

POST https://api.tuma.co.ke/payment/stk-push
Authorization: Bearer your-jwt-token
Content-Type: application/json

{
  "amount": 100.00,
  "phone": "254712345678",
  "callback_url": "https://your-app.com/callback",
  "description": "Payment for order #123"
}

Response:
{
    "success": true,
    "message": "Payment request sent successfully. Complete payment on your phone.",
    "data": {
        "merchant_request_id": "2dfd-472d-9bbd-df490884098d625543",
        "checkout_request_id": "ws_CO_04032026165157497729598795",
        "customer_message": "Success. Request accepted for processing"
    }
}

Callback handling

Your callback URL provided in STK PUSH request will receive payment status updates as shown below.

POST https://your-app.com/callback
Content-Type: application/json

//Response model for success, result_code=0, else it's a fail

{
  "status": "completed",
  "merchant_request_id": "a5ea-442f-a424-f94158490a468325",
  "checkout_request_id": "ws_CO_23022026142735114729500095",
  "result_code": 0,
  "result_desc": "The service request is processed successfully.",
  "timestamp": "2026-02-23 14:27:46",
  "mpesa_receipt_number": "UBNGT7QNYB",
  "amount": 10
}

//fail response model e.g
{
  "status": "failed",
  "merchant_request_id": "0e96-4a74-ab9d-ae3b6a9c0e933677",
  "checkout_request_id": "ws_CO_28022026175239080729590095",
  "result_code": 2001,
  "result_desc": "The initiator information is invalid.",
  "timestamp": "2026-02-28 17:52:51",
  "failure_reason": "Invalid M-Pesa PIN entered"
}

Error handling

In the event that payment has not been completed, all API responses follow a consistent format.

// Success Response
{
  "success": true,
  "data": { ... }
}

// Error Response
{
  "success": false,
  "message": "Error description"
}

Fund settlement

Once a customer authorizes payment prompt, Tuma credits the funds directly to your Sidian Bank account in real-time.