Tutorial: Integrating your app with a LOOP account via API

Use cases

Loop is a popular digital banking platform by NCBA Group, offering full banking services via a mobile app for stress-free, paperless transactions, budgeting, investments (like Loop Invest), and loans (personal loans up to KES 3M, overdrafts). It’s a modern, lifestyle-focused tool for managing finances, providing seamless access to payments, savings goals, credit, and even “Buy Now Pay Later” (BNPL) options, all built on data and AI for personalized experiences. 

With the rising technology adoption in Africa to automate business workflows, there’s a huge need to enable merchants and service providers integrate their LOOP 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 LOOP as prerequisite.

Tuma Payment Gateway enables you to connect your app with personal or business LOOP 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 LOOP C2B/LOOP Business 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 LOOP account in real-time.