Co-operative Bank of Kenya API Integration tutorial

Co-op Bank Kenya powers thousands of businesses in Kenya creating a huge need to enable merchants and service providers integrate their bank accounts with inhouse apps and softwares 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 Co-operative Bank of Kenya as prerequisite.

Tuma Payment Gateway enables you to connect your app with personal or business Co-operative Bank of Kenya 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 Co-operative Bank of Kenya 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 Co-operative Bank account in real-time.