api-docs.md

<!--
ClickPesa API Documentation — full reference, formatted for LLM consumption.
Source: https://docs.clickpesa.com/llms-full.txt (official Mintlify llms-full export)
Retrieved: 2026-09-05
-->

# Retrieve Account Balance
Source: https://docs.clickpesa.com/api-reference/account/get-account-balance

GET /account/balance
Get Account Balance

<Note>
  If the merchant has not yet received a successful payment or deposit, this endpoint returns `404` with the message: `No balance account is linked to this merchant yet. Balance becomes available after the first successful payment or deposit.`
</Note>


# Retrieve Account Statement
Source: https://docs.clickpesa.com/api-reference/account/get-account-statement

GET /account/statement
Get Account Statement



# Generate Authorization Token
Source: https://docs.clickpesa.com/api-reference/authorization/generate-token

POST /generate-token
Generates JWT Authorization token required for accessing ClickPesa APIs

<Note> JTW token is valid for **1 hour** from the time of issuance. After it expires, you must generate a new token. </Note>


# Bulk Create Customer Control Numbers
Source: https://docs.clickpesa.com/api-reference/collection/billpay/bulk-create-customer-control-numbers

POST /billpay/bulk-create-customer-control-numbers
Bulk create BillPay Customer Control Numbers (max 50 per request). Each item follows the single-create format. Supports partial success — valid items are created; invalid ones are returned in the errors array



# Bulk Create Order Control Numbers
Source: https://docs.clickpesa.com/api-reference/collection/billpay/bulk-create-order-control-numbers

POST /billpay/bulk-create-order-control-numbers
Bulk creates BillPay Order Control Numbers (max 50 per request). Supports partial success: valid items are created while invalid items are reported in the errors array.



# Create Customer Control Number
Source: https://docs.clickpesa.com/api-reference/collection/billpay/create-customer-control-number

POST /billpay/create-customer-control-number
Generates a BillPay Control Number for a specific customer



# Create Order Control Number
Source: https://docs.clickpesa.com/api-reference/collection/billpay/create-order-control-number

POST /billpay/create-order-control-number
Generates a BillPay Control Number for a specific bill, transaction or invoice



# Query BillPay Number Details
Source: https://docs.clickpesa.com/api-reference/collection/billpay/querying-for-billpay-details

GET /billpay/{billPayNumber}
Queries for BillPay number details



# Update BillPay Reference
Source: https://docs.clickpesa.com/api-reference/collection/billpay/update-billpay-reference

PATCH /billpay/{billPayNumber}
Partially updates a BillPay reference. Use to update amount, description, payment mode, collection ceiling, or status without recreating the reference.



# Update BillPay Number Status
Source: https://docs.clickpesa.com/api-reference/collection/billpay/update-billpay-reference-status

PUT /billpay/update-status
**Deprecated.** Use PATCH /billpay/{billPayNumber} with body { billStatus } instead. Updates the status of a BillPay reference. Inactive references will be rejected during verification and confirmation.



# Initiate Card Payment
Source: https://docs.clickpesa.com/api-reference/collection/card-payment/initiate-card-payment

POST /payments/initiate-card-payment



# Preview Card Payment
Source: https://docs.clickpesa.com/api-reference/collection/card-payment/preview-card-payment

POST /payments/preview-card-payment
This endpoint validates card payment details like Amount, Order Reference and verifies Method availability



# Query All Payments
Source: https://docs.clickpesa.com/api-reference/collection/card-payment/query-all-payments

GET /payments/all
Query all payments with filtering, sorting, and pagination capabilities



# Query Payment Status
Source: https://docs.clickpesa.com/api-reference/collection/card-payment/querying-for-payments

GET /payments/{orderReference}
Queries for the payment status using payment's Order Reference 



# Cancel Mandate
Source: https://docs.clickpesa.com/api-reference/collection/crdb-direct-debit/cancel-mandate

api-reference/collection/crdb-direct-debit/openapi.json POST /customers/crdb-direct-debit-mandate/cancel
Cancel an ACTIVE CRDB Direct Debit mandate. When the linked payment plan is still active, the plan and unpaid cycles are cancelled too.

<Note>
  Only mandates with status **ACTIVE** can be cancelled. See the [CRDB Direct Debit API overview](/crdb-direct-debit/api-overview).
</Note>


# Get Mandate
Source: https://docs.clickpesa.com/api-reference/collection/crdb-direct-debit/get-mandate

api-reference/collection/crdb-direct-debit/openapi.json GET /customers/crdb-direct-debit-mandate
Get CRDB Direct Debit mandate details and linked payment plan summary by mandate request ID

<Note>
  Pass `requestId` (the `mandateRequestId` from [Request Mandate Approval](/api-reference/collection/crdb-direct-debit/request-mandate)) as a query parameter.
</Note>


# Request Mandate Approval
Source: https://docs.clickpesa.com/api-reference/collection/crdb-direct-debit/request-mandate

api-reference/collection/crdb-direct-debit/openapi.json POST /customers/crdb-direct-debit-mandate
Request CRDB Direct Debit mandate approval and create the linked payment schedule.

<Note>
  See the [CRDB Direct Debit API overview](/crdb-direct-debit/api-overview) for mandate status callbacks and payment webhooks. A CRDB debit account can have only one mandate at a time.
</Note>


# Generate Checkout Link
Source: https://docs.clickpesa.com/api-reference/collection/generate-checkout-link/generate-checkout-link

POST /checkout-link/generate-checkout-url
Generates a link for receiving payments via Hosted Checkout. After payment, customers are redirected to the Return URL configured on your hosted application in the dashboard. For payment status updates, use application webhooks and/or an optional callbackUrl on the request body (see Payment notifications in the Checkout Link API guide).



# Query Payment Status
Source: https://docs.clickpesa.com/api-reference/collection/querying-for-payments/querying-for-payments

GET /payments/{orderReference}
Queries for the payment status using payment's Order Reference 



# Initiate USSD-PUSH request
Source: https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/initiate-ussd-push-request

POST /payments/initiate-ussd-push-request
Sends the USSD-PUSH request to customer's mobile device for payment authorization



# Preview USSD-PUSH request
Source: https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/preview-ussd-push-request

POST /payments/preview-ussd-push-request
Validates push details like phone number, amount, order-reference and verifies payment channels availability



# Query All Payments
Source: https://docs.clickpesa.com/api-reference/collection/ussd-push-requests/query-all-payments

GET /payments/all
Query all payments with filtering, sorting, and pagination capabilities



# Create Bank Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/bank-payout/create-bank-payout

POST /payouts/create-bank-payout
Sends a payout to a bank account.

<Warning>
  Create requests are limited to one per merchant every **60 seconds**. Re-submitting earlier returns an error with the remaining wait time.
</Warning>


# Preview Bank Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/bank-payout/preview-bank-payout

POST /payouts/preview-bank-payout
Validates a bank payout and returns the fee, balance, and estimated arrival.

<Note>
  When name lookup is available for the selected bank, the response includes `nameLookupStatus` (`RESOLVED` or `UNAVAILABLE`). If `UNAVAILABLE`, `receiver.accountName` is omitted — pass your own verified name on [Create Bank Payout](/api-reference/disbursement/bank-payout/create-bank-payout).
</Note>


# Query All Payouts
Source: https://docs.clickpesa.com/api-reference/disbursement/bank-payout/query-all-payouts

GET /payouts/all
Query all payouts with filtering, sorting, and pagination capabilities



# Query Payout Status
Source: https://docs.clickpesa.com/api-reference/disbursement/bank-payout/querying-for-payouts

GET /payouts/{orderReference}
Queries for the payouts status using payout’s Order Reference



# Generate Payout Link
Source: https://docs.clickpesa.com/api-reference/disbursement/generate-payout-link/generate-payout-link

POST /payout-link/generate-payout-url
Generate Payout Link for making payouts



# Create Lipa Namba Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/lipa-namba-payout/create-lipa-namba-payout

api-reference/disbursement/lipa-namba-payout/openapi.json POST /payouts/create-lipa-namba-payout
Sends a payout to a Lipa Namba or TanQR.

<Warning>
  Create requests are limited to one per merchant every **60 seconds**. Re-submitting earlier returns an error with the remaining wait time.
</Warning>

<Note>
  Create often returns `AUTHORIZED`. That means the payout was accepted, not that it has settled. Poll [payout status](/api-reference/disbursement/lipa-namba-payout/querying-for-payouts) or listen for webhooks until `SUCCESS` or `REFUNDED`.
</Note>


# Retrieve Lipa Namba Providers
Source: https://docs.clickpesa.com/api-reference/disbursement/lipa-namba-payout/list-lipa-namba-providers

api-reference/disbursement/lipa-namba-payout/openapi.json GET /payouts/lipa-namba-providers
Returns the list of Lipa Namba providers.



# Preview Lipa Namba Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/lipa-namba-payout/preview-lipa-namba-payout

api-reference/disbursement/lipa-namba-payout/openapi.json POST /payouts/preview-lipa-namba-payout
Validates a Lipa Namba or TanQR payout and returns the fee, balance, and beneficiary name.

<Note>
  Provide exactly one destination: `lipaNamba` + `providerCode`, or TanQR `qrCode`. Preview must resolve a beneficiary name before you create the payout.
</Note>


# Query All Payouts
Source: https://docs.clickpesa.com/api-reference/disbursement/lipa-namba-payout/query-all-payouts

api-reference/disbursement/query-all-payouts/openapi.json GET /payouts/all
Query all payouts with filtering, sorting, and pagination capabilities



# Query Payout Status
Source: https://docs.clickpesa.com/api-reference/disbursement/lipa-namba-payout/querying-for-payouts

api-reference/disbursement/querying-for-payouts/openapi.json GET /payouts/{orderReference}
Queries for the payouts status using payout’s Order Reference



# Create Mobile Money Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/mno-payout/create-mno-payout

POST /payouts/create-mobile-money-payout
Sends a payout to a mobile money wallet.

<Warning>
  Create requests are limited to one per merchant every **60 seconds**. Re-submitting earlier returns an error with the remaining wait time.
</Warning>


# Preview Mobile Money Payout
Source: https://docs.clickpesa.com/api-reference/disbursement/mno-payout/preview-mno-payout

POST /payouts/preview-mobile-money-payout
Validates a mobile money payout and returns the fee and balance.



# Query All Payouts
Source: https://docs.clickpesa.com/api-reference/disbursement/mno-payout/query-all-payouts

GET /payouts/all
Query all payouts with filtering, sorting, and pagination capabilities



# Query Payout Status
Source: https://docs.clickpesa.com/api-reference/disbursement/mno-payout/querying-for-payouts

GET /payouts/{orderReference}
Queries for the payouts status using payout’s Order Reference



# Retrieve Exchange Rates
Source: https://docs.clickpesa.com/api-reference/exchange/get-latest-exchange-rates

GET /exchange-rates/all
Retrieve latest exchange rates between currencies. If no params are passed, all available rates will be returned.



# Retrieve Banks List
Source: https://docs.clickpesa.com/api-reference/list/get-bank-list

GET /list/banks
Get Bank List



# API Integration Setup
Source: https://docs.clickpesa.com/application/api-application-setup

Learn how to set up API integration with ClickPesa, including creating applications, managing API keys, and retrieving credentials

## Authentication Overview

[Client ID](#authentication-overview) - Remains accessible in your application settings and is also required for API authentication.

[API Key](#authentication-overview) - It is required for API authentication, displayed **only once** during creation. **Copy and store it securely**

[JWT Token](#authentication-overview) - `API Key` and `Client ID` are [exchanged](/api-reference/authorization/generate-token) for a short-lived `JWT Token`, which is then used in all subsequent API calls.
The JWT token is valid for **1hr (60 Minutes)** from the time of issuance. After it expires, you must generate a new token using your `API Key` and `Client ID`.

<Warning>
  Never share your API credentials or JWT token publicly. Always use HTTPS to protect your credentials during transmission.
</Warning>

[API Rate Limits](#authentication-overview) - The ClickPesa API enforces a rate limit of **120 requests per minute** per IP address. This limit applies to **all API endpoints**. If you exceed this limit, your requests will be throttled.

[Pre-KYC API daily limit](#authentication-overview) - If your merchant account has **not completed KYC**, you are also limited to **100 API calls per day** across all third-party API requests, including **[generate-token](/api-reference/authorization/generate-token)**. The count resets every day at **midnight East Africa Time (EAT)**. After KYC approval, only the per-minute IP limit applies.

<Tip>
  Implement appropriate retry logic with exponential backoff in your application to handle rate limit responses gracefully. If you receive a daily limit response before KYC is complete, wait until the next day or complete KYC to remove the cap.
</Tip>

## Application Setup

### Step 1: Log in to the ClickPesa Dashboard

Go to the [ClickPesa Dashboard](https://merchant.clickpesa.com) and log in with your credentials.

### Step 2: Access Developer Settings

1. In the dashboard, click **Settings**.
2. Navigate to the **Developers** section.

See [Developers settings](/dashboard/settings/developers) for the full dashboard walkthrough.

### Step 3: Create a New Application

Click **Create Application** to begin the setup process.

### Step 4: Configure Application Details

When creating your application, provide the following details:

* **Application Name**: A name to identify your app.
* **Integration Type**: Select **API**.
* **Features**: Choose the required features (e.g. **Payment API**, **Payout API**).

### Step 5: Submit Your Application

Click **Create** to finalize the application setup.

## Managing API Keys

<Warning> **Important**: Keep your API credentials secure and do not share them publicly.</Warning>

### Access API Keys

1. Navigate to **Settings** in the ClickPesa dashboard.
2. Go to the **Developers** section.
3. Select the application for which you want to manage API keys.
4. Click **Manage API Keys** in the application settings.
5. A panel will appear, showing the list of existing API keys, including:
   * **Name**: Assigned name of the API key.
   * **Last Activity**: Date of last use.
   * **Revoke Button**: Option to deactivate the key.

### Adding a New API Key

1. Navigate to **Settings** in the ClickPesa dashboard.
2. Go to the **Developers** section.
3. Select the application for which you want to create an API key.
4. Click **Manage API Keys** in the application settings.
5. Click **Add API Key**.
6. A modal will appear where you can enter the required details:
   * **Name**: A label for the API key.
   * **Expiry Date**: Define when the key will expire.
7. Click **Submit** to proceed.
8. The modal will prompt you to enter your password for confirmation.
9. After successfully confirming your password, the API key will be created.
10. The modal will then display:
    * The **Client ID** and newly generated **API Key**.
    * The **Expiry Date**.


# Embedded Integration Setup
Source: https://docs.clickpesa.com/application/embedded-application-setup

Learn how to set up an embedded integration with ClickPesa to seamlessly integrate payment services into your application.

## Authentication Overview

### [Initialization](#)

* Only a `ClientId` is required to initialize an embedded components
* The `ClientId` is a unique identifier generated for each application and is always visible in the application settings

### [Authentication & Authorization](#)

* When performing actions, users will be required to authenticate using their **Email** and **Password**.
* Depending on the actions, **Two-Factor Authentication** (2FA) may also be required for authorization

## Application Setup

### Step 1: Log in to the ClickPesa Dashboard

Go to the [ClickPesa Dashboard](https://merchant.clickpesa.com) and log in with your credentials.

### Step 2: Access Developer Settings

1. In the dashboard, click **Settings**.
2. Navigate to the **Developers** section.

### Step 3: Create a New Application

Click **Create Application** to begin the setup process.

### Step 4: Configure Application Details

When creating the application, fill in the following details:

* **Application Name**: Choose a name to identify your app.
* **Integration Type**: Select **Embedded**.
* **Features**: Choose the features needed (e.g., **Embedded Checkout** , **Embedded Payout Widget**).

### Step 5: Submit Your Application

Click **Create** to finalize the application setup.


# Hosted Integration Setup
Source: https://docs.clickpesa.com/application/hosted-application-setup

Learn how to set up hosted integration with ClickPesa, including creating applications, managing API keys, and retrieving credentials.

## Authentication Overview

[Client ID](#authentication-overview) - Remains accessible in your application settings and is also required for API authentication.

[API Key](#authentication-overview) - It is required for API authentication, displayed **only once** during creation. **Copy and store it securely**

[JWT Token](#authentication-overview) - `API Key` and `Client ID` are [exchanged](api-reference/authorization/generate-token) for a short-lived `JWT Token`, that will be used for the API call to generate hosted links

[OTP Authorization](#authentication-overview) - Depending on the actions, users may also be required to provide OTP code via their **Two-Factor Authentication** (2FA) method

## Application Setup

### Step 1: Log in to the ClickPesa Dashboard

Go to the [ClickPesa Dashboard](https://merchant.clickpesa.com) and log in with your credentials.

### Step 2: Access Developer Settings

1. In the dashboard, click **Settings**.
2. Navigate to the **Developers** section.

### Step 3: Create a New Application

Click **Create Application** to begin the setup process.

### Step 4: Configure Application Details

When creating your application, provide the following details:

* **Application Name**: Choose a name to identify your app.
* **Integration Type**: Select **Hosted**.
* **Features**: Choose the features needed (e.g. **Hosted Checkout**, **Hosted Payout**).
* **Return URL**: The Return URL is used in hosted solutions to redirect users after they have completed a payment or payout.

### Step 5: Submit Your Application

Click **Create** to finalize the application setup.

## Managing API Keys

<Warning> **Important**: Keep your API credentials secure and do not share them publicly.</Warning>

### Access API Keys

1. Navigate to **Settings** in the ClickPesa dashboard.
2. Go to the **Developers** section.
3. Select the application for which you want to manage API keys.
4. Click **Manage API Keys** in the application settings.
5. A panel will appear, showing the list of existing API keys, including:
   * **Name**: Assigned name of the API key.
   * **Last Activity**: Date of last use.
   * **Revoke Button**: Option to deactivate the key.

### Adding a New API Key

1. Navigate to **Settings** in the ClickPesa dashboard.
2. Go to the **Developers** section.
3. Select the application for which you want to create an API key.
4. Click **Manage API Keys** in the application settings.
5. Click **Add API Key**.
6. A modal will appear where you can enter the required details:
   * **Name**: A label for the API key.
   * **Expiry Date**: Define when the key will expire.
7. Click **Submit** to proceed.
8. The modal will prompt you to enter your password for confirmation.
9. After successfully confirming your password, the API key will be created.
10. The modal will then display:
    * The **Client ID** and newly generated **API Key**.
    * The **Expiry Date**.


# BillPay Overview
Source: https://docs.clickpesa.com/bill-pay/bill-pay-overview

Create and use BillPay Control Numbers to receive instant payments from mobile money and banks

A **BillPay Control Number** is a unique numeric identifier that customers use to pay a merchant through supported payment channels—including mobile money, SIM banking, and CRDB Wakalas.

<Tip>
  ClickPesa BillPay payment are **instant** and are instantly visible in your [Dashboard](https://merchant.clickpesa.com).
  You can also track them via the [Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments) or receive real-time [webhook notifications](/home/webhooks).
</Tip>

## Why Use BillPay Control Numbers?

* Instant payment confirmation.
* Automated reconciliation.
* Works across all major Tanzanian payment channels (mobile money, SIM banking, CRDB Internet Banking, and Wakalas).
* Flexible for different payment needs.
* Supports **one-time payments** and **subscriptions or recurring payments**.
* Can be generated **offline** and via the [Dashboard](https://merchant.clickpesa.com) and [BillPay API](/bill-pay/billpay-api-overview).

## Types of BillPay Control Numbers

ClickPesa supports **three** types of control numbers:

### [Merchant BillPay-Namba](/bill-pay/billpay-namba)

A **4-digit static number** assigned to your merchant account.

* Used to deposit funds into your ClickPesa balance.
* A base number for generating Order BillPay numbers offline.
* **Not** for sharing with customers.

### [Order BillPay Control Number](/bill-pay/order-billpay-namba)

A **dynamic number** for a specific transaction or invoice.

* Ideal for **one-time payments**.
* Closes automatically once processed.

**Two ways to generate:**

1. **Offline / Manual Concatenation:** Combine your Merchant BillPay-Namba with an internal order reference (e.g., `1122` + `231256` = `1122231256`). Quick way to accept online payments for offline invoices.
2. **API Generation:** Create via [BillPay API](/api-reference/collection/billpay/create-order-control-number) with full flexibility:
   * Set the **amount** to be paid (optional).
   * Control **payment mode**: full, partial, or over.
   * Optionally set a **max total** that can be collected; the number closes when the limit is reached.
   * Add a **bill description**.
   * Provide a **custom reference** as the control number.
   * If no reference is provided, ClickPesa will **auto-generate** one.

### [Customer BillPay Control Number](/bill-pay/customer-billpay-namba)

A **static unique number** assigned to a specific customer.

* Ideal for **repeating or subscription payments**.
* Enables **automatic payment tracking per customer**.

**Two ways to generate:**

1. [Via Dashboard](https://merchant.clickpesa.com): Assign a control number linked to the customer in the Merchant Dashboard.
2. **API Generation:** Create via [BillPay API](/api-reference/collection/billpay/create-customer-control-number) with full flexibility:
   * Specify **customer name** (e.g., student, client).
   * Add **bill description** (e.g., Tuition Fees, Rent - July 2025 ).
   * Set **payment amount** and **mode** (full, partial, over).
   * Optionally set a **max total** that can be collected across payments.
   * Allow **multiple control numbers per customer**, each for a different bill or purpose.
   * Provide a **custom reference** or let ClickPesa auto-generate one.

## Making Payments with BillPay Control Numbers

Payments can be made through:

* **Mobile Money:** Mixx By Yas, Airtel Money, Halopesa, M-Pesa
* **CRDB Banking:** SIM Banking (APP/USSD), Internet Banking, CRDB Wakalas

Step-by-step payment instructions are available on each BillPay Control Number page:

[Top up using Merchant BillPay-Namba](/bill-pay/billpay-namba#depositing-using-merchant-billpay-namba)

[Pay using Order BillPay Control Number](/bill-pay/order-billpay-namba#making-payments-with-order-billpay-control-numbers)

[Pay using Customer BillPay Control Number](/bill-pay/customer-billpay-namba#making-payments-with-customer-billpay-control-numbers)

## In the Merchant Dashboard

<CardGroup>
  <Card title="Customers" icon="users" href="/dashboard/customers">
    Add customers and assign Customer BillPay control numbers in the dashboard.
  </Card>

  <Card title="Collection Settings" icon="gear" href="/dashboard/settings/collection">
    View your Merchant BillPay-Namba and manage collection methods.
  </Card>

  <Card title="Payment Transactions" icon="list" href="/dashboard/transactions/payments">
    View and export BillPay payments received in the dashboard.
  </Card>
</CardGroup>

<br />

<CardGroup>
  <Card title="BillPay API" icon="book-open" href="/bill-pay/billpay-api-overview">
    Understand how to work with BillPay Control Numbers with BillPay API.
  </Card>

  <Card title="BillPay Use Cases" icon="screen-users" href="/bill-pay/billpay-use-cases">
    See practical examples of how to collect payments with ClickPesa BillPay.
  </Card>

  <Card title="BillPay FAQ" icon="screen-users" href="/bill-pay/billpay-faq">
    Answers to common questions about ClickPesa BillPay.
  </Card>
</CardGroup>


# BillPay API
Source: https://docs.clickpesa.com/bill-pay/billpay-api-overview

The BillPay API enables you to create BillPay Control Numbers for orders and customers to receive payments from mobile money wallets and bank accounts

## Prerequisites

1. **API Keys**
   [Create an Application](/application/api-application-setup) to generate **Client ID** and **API Keys** for API access.

2. **Authorization Token**
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token).

## How It Works

### Step 1 – Create BillPay Control Number

<Card title="Create Order BillPay Control Number" icon="brackets-curly" href="/api-reference/collection/billpay/create-order-control-number">
  This endpoint creates an **Order Control Number** for a specific transaction or invoice.
  You can specify the **amount**, **payment mode** (full or partial), a **max total** that can be collected, a **custom reference**, and other metadata.
</Card>

<Card title="Create Customer BillPay Control Number" icon="brackets-curly" href="/api-reference/collection/billpay/create-customer-control-number">
  This endpoint creates a **Customer Control Number** for a specific customer.
  You can include **customer name**, **bill description**, **amount**, a **max total** that can be collected, and **payment mode**.
  Multiple control numbers can be generated per customer for different bills or purposes.
</Card>

<Card title="Bulk Create Order Control Numbers" icon="brackets-curly" href="/api-reference/collection/billpay/bulk-create-order-control-numbers">
  Bulk create up to **50 Order Control Numbers** per request. Same item shape as the single create endpoint. Supports partial success with per-item error reporting.
</Card>

<Card title="Bulk Create Customer Control Numbers" icon="brackets-curly" href="/api-reference/collection/billpay/bulk-create-customer-control-numbers">
  Bulk create up to **50 Customer Control Numbers** per request. Same item shape as the single create endpoint. Supports partial success with per-item error reporting.
</Card>

<Note>
  You can pass your own references that already exist in your system (for example invoice IDs, loan IDs or order numbers) as `billReference`. That value becomes the customer-facing control number. It must be unique within ClickPesa for your account.
</Note>

### Step 2 – Share BillPay Control Number

<Card title="Share BillPay Control Number" icon="share">
  Once created, the BillPay Control Number can be shared with customers via:

  * **SMS or WhatsApp** message with the control number and payment instructions.
  * **Email** with bill details and the control number.
  * **Embedded in invoices** or payment links on your website.

  Customers can then pay using mobile money wallets or bank accounts by providing the control number at the time of payment.
</Card>

### Step 3 – Verify Payment

#### Query Payment Status via API

<Card title="Query Payment Status" icon="brackets-curly" href="/api-reference/collection/querying-for-payments/querying-for-payments">
  You can check the payment status using the payment’s **Order Reference** by querying the API.
  This allows you to retrieve real-time payment information for reconciliation or reporting.
</Card>

#### Receive Webhook Notifications

Configure **[Application webhooks](/home/webhooks#application-level-webhooks)** on the same application you use to create control numbers. When a customer pays via mobile money or bank BillPay against that number, you receive `PAYMENT RECEIVED` on your application webhook if you have configured it.

<Card title="Application Webhooks" icon="webhook" href="/home/webhooks#application-level-webhooks">
  Set up `PAYMENT RECEIVED` (and `PAYMENT FAILED` if needed) under **Settings → Developers → your application → Application Webhooks**.
</Card>

<Card title="Merchant Webhooks" icon="webhook" href="/home/webhooks#merchant-level-webhooks">
  If you have not set up an application webhook for the event, notifications go to your merchant-level webhook instead (if configured).
</Card>

<Note>
  This applies to order and customer control numbers you create through the BillPay API. For offline BillPay references, use merchant webhooks or the [payments API](/api-reference/collection/querying-for-payments/querying-for-payments) to check payment status.
</Note>

### Step 4 – Fetch BillPay Details (Optional)

<Card title="Query BillPay Control Number Details" icon="brackets-curly" href="/api-reference/collection/billpay/querying-for-billpay-details">
  Use this endpoint to retrieve full details of a BillPay Control Number, including amount, max total, how much can still be collected, reference, linked customer and invoice details.
  This is useful for displaying bill details to customers or performing audits.
</Card>

<Card title="Update BillPay Control Number Details" icon="brackets-curly" href="/api-reference/collection/billpay/update-billpay-reference">
  Use this endpoint to update a BillPay Control Number Details: **billStatus**, **billAmount**, **billMaxCollectionAmount**, **billDescription**, or **billPaymentMode**. Useful in reusing the reference number without recreating.
</Card>


# FAQ
Source: https://docs.clickpesa.com/bill-pay/billpay-faq

Frequently Asked Questions about BillPay Control Numbers

[Where can I find the endpoint to create an Order BillPay Control Number?](#)

**A:** You can now create an **Order BillPay Control Number via the [BillPay API](/api-reference/collection/billpay/create-order-control-number)**.

* **API Generation:** Provides flexibility to specify:
  * Amount to be paid (optional)
  * Payment mode (full, partial, or over)
  * Max total that can be collected (optional — closes the number when the limit is reached)
  * Bill description
  * Custom reference (used as the customer-facing control number)
  * If no custom reference is provided, ClickPesa will auto-generate one.
* **Offline / Manual Generation:** You can also generate an Order BillPay Control Number on your side by combining your Merchant BillPay-Namba with a unique order reference from your system. This method is quick for offline or manual invoicing.

When a customer pays using the control number, ClickPesa routes the payment to your account and sends a **webhook notification** containing the full BillPay number and payment details.

***

[If a client is given a control number for 1,000,000/= but pays only 500,000/=, will the payment go through?](#)

**A:** Yes. Partial payments are accepted **if enabled** during API creation.

* You'll be notified of the amount received via **webhook**, **email**, and **dashboard notifications**.
* If you also set a **max total** (`billMaxCollectionAmount`), the payment must fit within what’s left to collect.

***

[Can I limit how much can be collected on a control number?](#)

**A:** Yes. When payment mode is `ALLOW_PARTIAL_AND_OVER_PAYMENT`, set **`billMaxCollectionAmount`** on create or update.

* Each payment counts toward the max. A payment that would go over what’s left is rejected.
* When the max is reached, the control number becomes inactive and stops accepting payments.
* You can set a max with or without `billAmount`. If you set both, the max must be at least as large as the bill amount.
* If a payment is reversed, that amount still counts toward the max.
* Works best with **customer** control numbers if you expect several payments toward the same limit. **Order** control numbers still accept only one payment.

See the [BillPay API](/bill-pay/billpay-api-overview) and [create customer control number](/api-reference/collection/billpay/create-customer-control-number).

***

[Can the same control number be used to pay the remaining balance later?](#)

**A:** It depends on the type of BillPay control number:

* **Order BillPay Control Number** – **No**
  * Designed for one-time, specific transactions.
  * Once paid (even partially), it is **closed** or marked **fulfilled**.
  * If partial payments are allowed, the system will reflect the partial amount, but the number is still considered closed.

* **Customer BillPay Control Number** – **Yes**
  * Designed for ongoing or repeat payments from the same customer.
  * Can receive multiple payments.
  * Ideal for **partial, recurring, or subscription payments**.
  * If you set a **max total**, further payments stop once that limit is reached.
  * You can also create **multiple numbers per customer**, each tied to a different bill or purpose.

***

[What's the lifespan of the Order BillPay Control Number?](#)

**A:** An **Order BillPay Control Number** remains **valid until it is paid** or manually closed.

* **Designed for one-time payments:** Order BillPay Control Numbers are created for specific transactions or invoices and are intended to be used once.
* **No automatic expiration:** The control number does not expire automatically if unpaid—it remains active and can accept payments until it is fulfilled or closed.
* **Closes automatically once processed:** Once a payment is received (even if partial or failed), the Order BillPay Control Number is automatically **closed** or marked as **fulfilled** and cannot be reused.
* **Best practice:** For time-sensitive invoices or orders, consider implementing your own expiration logic in your system and generating new control numbers when needed.

***

[What's the lifespan of the Customer BillPay Control Number?](#)

**A:** A **Customer BillPay Control Number** is a **static, permanent number** that remains **active indefinitely** until manually deactivated or removed.

* **Designed for recurring payments:** Customer BillPay Control Numbers are created for ongoing relationships with customers and are intended for multiple transactions over time.
* **No expiration by default:** Unlike Order BillPay Control Numbers, Customer BillPay Control Numbers do **not expire** and do **not close automatically** after each payment.
* **Exception — max total:** If you set `billMaxCollectionAmount`, the number becomes inactive when that limit is reached.
* **Reusable for multiple payments:** The same Customer BillPay Control Number can be used repeatedly for **partial, recurring, or subscription payments** from the same customer.
* **Multiple numbers per customer:** You can create **multiple Customer BillPay Control Numbers** for the same customer, each tied to a different bill or purpose (e.g., tuition, fees, pocket money).
* **Manual management:** You can deactivate or remove Customer BillPay Control Numbers through the API when they are no longer needed.

***

[Can I assign multiple Customer BillPay Control Numbers to a single customer?](#)

**A:** Yes. Each customer can have **multiple Customer BillPay Control Numbers**, allowing you to manage different bills (e.g., tuition, fees, pocket money) independently. Each number can accept multiple payments and be tracked separately.

***

[Can I specify customer details and bill descriptions when creating a control number via API?](#)

**A:** Yes. When creating **Customer or Order BillPay Control Numbers via API**, you can:

* Provide the **customer name** (for Customer numbers)
* Add a **bill description**
* Set payment amount and mode
* Set a **max total** that can be collected (`billMaxCollectionAmount`), when using partial and over payments
* Provide a **custom reference** or let ClickPesa auto-generate one
  This improves reconciliation and reporting, especially for recurring or batch payments.

***


# Merchant BillPay-Namba
Source: https://docs.clickpesa.com/bill-pay/billpay-namba

Your 4-digit static BillPay number for merchant deposits

The **Merchant BillPay-Namba** is a unique **4-digit number** assigned to every ClickPesa merchant.
Used directly to deposit funds into your ClickPesa account and serves as the **root reference** for offline order number generation.

## How to Access Your Merchant BillPay-Namba

1. Log in to your [Dashboard](https://merchant.clickpesa.com).
2. Go to **Settings → Collection**.
3. Scroll to the **BillPay Payments Collection** section.
4. Your **4-digit BillPay-Namba** will be displayed there.

## Depositing Using Merchant BillPay-Namba

Merchants can deposit funds into their ClickPesa balance using this number via:

* **Mobile Money:** Mixx By Yas, Airtel Money, Halopesa, M-Pesa
* **CRDB Banking:** SIM Banking (APP/USSD), Internet Banking, CRDB Wakalas

### [ via Airtel Money](#pay-via-airtel-money)

<Tabs>
  <Tab title="Airtel Money USSD">
    1. Piga `*150*60#`
    2. Chagua Chaguo `6` --- **Huduma za Kifedha / Financial Services**
    3. Chagua Chaguo `6` --- **SACCOS and MFI**
    4. Chagua Chaguo `1` --- **MFI**
    5. Chagua Chaguo `5` --- **A-G**
    6. Chagua Chaguo `8` --- **ClickPesa**
    7. Ingiza namba ya Kumbukumbu --- **\[]**
    8. Weka Kiasi
    9. Chagua `1` --- **(Ndio) Kuthibitisha**
    10. Weka PIN
  </Tab>

  <Tab title="Airtel Money APP">
    1. Fungua AirtelMoney App
    2. Bonyeza **Lipa Bili**
    3. Bonyeza **Ingiza jina la biashara au namba**
    4. Andika *"clickpesa"*
    5. Chagua **CLICKPESA TANZANIA**
    6. Weka Kumbukumbu ya Malipo --- **\[]**
    7. Weka Kiasi
    8. Bonyeza **Endelea**
    9. Weka Namba ya Siri
  </Tab>
</Tabs>

### [ via M-Pesa](#pay-via-m-pesa)

<Tabs>
  <Tab title="M-Pesa USSD">
    1. Piga `*150*00#`
    2. Chagua Chaguo `4` --- **Lipia Kwa M-Pesa**
    3. Chagua Chaguo `4` --- **Weka Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **\[M-Pesa Merchant Number]** - *Available at onboarding*
    5. Weka namba ya Kumbukumbu ya Malipo --- **\[]**
    6. Weka Kiasi
    7. Weka Namba ya Siri
    8. Bonyeza 1 Kuthibitisha
  </Tab>

  <Tab title="M-Pesa App">
    1. Fungua M-Pesa App
    2. Bonyeza **Lipia kwa M-Pesa**
    3. Bonyeza **Kitambulisho cha biashara** na Weka **\[M-Pesa Merchant Number]**
    4. Bonyeza **Kumbukumbu** na Weka **\[]**
    5. Weka Kiasi
    6. Bonyeza **Endelea**
    7. Bonyeza **Lipa sasa** na Ingiza Namba ya Siri
  </Tab>
</Tabs>

### [ via Mixx By Yas](#pay-via-mixx-by-yas)

<Tabs>
  <Tab title="Mixx By Yas USSD">
    1. Piga `*150*01#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
  </Tab>

  <Tab title="Mixx By Yas APP">
    1. Fungua Mixx By Yas App
    2. Bonyeza **Kulipa Bili**
    3. Andika *"clickpesa"* Kwenye **Tafuta**
    4. Chagua **ClickPesa-889999** Kwenye listi
    5. Weka Namba ya kumbukumbu --- **\[]**
    6. Weka kiasi
    7. Bonyeza **Endelea**
    8. Ingiza Namba ya Siri ya Mixx By Yas
    9. Bonyeza **Thibitisha**
  </Tab>
</Tabs>

### [ via Halopesa](#pay-via-halopesa)

<Tabs>
  <Tab title="Halopesa USSD">
    1. Piga `*150*88#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
    8. Chagua `1` --- **(Ndio) Kuthibitisha**
  </Tab>

  <Tab title="Halopesa APP">
    1. Fungua Halopesa App
    2. Bonyeza **Lipia Bili**
    3. Bonyeza **Chagua Namba ya biashara**
    4. Andika *"889999"* Kwenye uwanja wa kutafuta **Namba ya biashara**
    5. Bonyeza **ENDELEA**
    6. Weka kumbukumbu namba --- **\[]**
    7. Weka kiasi
    8. Bonyeza **ENDELEA**
    9. Ingiza Namba ya Siri
    10. Ingiza OTP
  </Tab>
</Tabs>

### [ via CRDB](#pay-via-crdb)

<Tabs>
  <Tab title="SimBanking USSD">
    1. Piga `*150*03#`
    2. Chagua `1` --- **Simbanking**
    3. Weka Namba ya Siri
    4. Chagua `4` --- **Pay Bills**
    5. Chagua `6`--- **Taasisi**
    6. Chagua `7` --- **Nyinginezo**
    7. Chagua `N` –-- **Next**
    8. Chagua `N` –-- **Next**
    9. Chagua **CLICKPESA**
    10. Weka Namba ya Malipo --- **\[]**
    11. Ingiza Kiasi
    12. Thibitisha Malipo
  </Tab>

  <Tab title="SimBanking APP">
    1. Fungua CRDB SimBanking App
    2. Weka Namba ya Siri ya SimBanking
    3. **Pandisha kupata huduma zaidi**
    4. Bonyeza **Malipo Zaidi**
    5. Chagua **CLICKPESA** Kwenye listi au andika **CLICKPESA** Juu Kwenye Tafuta huduma
    6. Weka Namba ya Malipo --- **\[]**
    7. Bonyeza **PATA TAARIFA**
    8. Hakikisha Taarifa za Bili, Chagua Akaunti Ya Kutoa na Weka Kiasi
    9. Bonyeza **ENDELEA**
    10. Hakikisha Taarifa za Muamala na Bonyeza **THIBITISHA**
  </Tab>

  <Tab title="CRDB Internet Banking">
    1. Login into your CRDB Internet Banking portal
    2. Select **Payment**
    3. Select **Bill Payment**
    4. Company Category --- Select **Others**
    5. Company Name -- Select **CLICKPESA**
    6. Enter Reference Number --- **\[]**
  </Tab>

  <Tab title="CRDB Wakala (App/POS)">
    1. Tembelea wakala CRDB aliye karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>

  <Tab title="CRDB Branch (OTC)">
    1. Tembelea tawi la CRDB lililo karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>
</Tabs>

Funds will reflect instantly on your ClickPesa Dashboard, and confirmation will be sent by SMS and email.

## Deposit Tracking

* **Automatic Notifications:** Receive instant updates via [Webhooks](/home/webhooks) and Web Notifications.
* **Manual Check:** In your [Dashboard](https://merchant.clickpesa.com).


# Common Use Cases
Source: https://docs.clickpesa.com/bill-pay/billpay-use-cases

Explore common use cases and userflows for BillPay, including webshop payments, invoice payments, offline purchases, and recurring customer payments.

### Webshop Payments

A webshop generates a BillPay Control Number at checkout and displays payment instructions for the customer:

* Customer selects mobile money or bank payment method.
* Webshop generates the **Order BillPay Control Number**:
  * Can be **offline concatenation** or **API-generated** for more control (set amount, payment mode, max total, custom reference, description).
* Payment instructions, including mobile money USSD code and **Order BillPay Control Number**, are displayed.
* The customer completes the payment via mobile money USSD, SIM banking, or CRDB Wakala.
* The webshop receives **instant payment confirmation** via webhook or tracks it via [Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments).

### Invoice Payments

Businesses can generate a BillPay Control Number for each invoice and send it to customers:

* Invoice is issued with an **Order BillPay Control Number** and payment instructions.
* API generation allows specifying:
  * Fixed amount or flexible amount.
  * Partial payments or overs.
  * A max total that can be collected (optional).
  * Bill description for easy reconciliation.
* Customer pays using mobile money, CRDB SIM banking, or Wakala.
* The invoicing system automatically matches the payment using the [Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments) or webhooks.

### Offline Purchases

For merchants with physical stores, restaurants, or service outlets:

* Merchant provides the customer with a unique **Order BillPay Control Number**, either printed on the bill or shared verbally.
* Customers pay via mobile money (e.g., M-Pesa) or CRDB SIM banking.
* Merchant verifies payment in real-time via ClickPesa Dashboard or webhook notifications.
* Offline-generated numbers follow the `Merchant BillPay-Namba + Order Reference` format for quick adoption without API integration.

### Recurring or Customer-Specific Payments

Ideal for schools, gyms, or subscription services:

* Each customer can have **multiple Customer BillPay Control Numbers**, one per recurring bill (e.g., tuition, fees, or membership subscription).
* Numbers can be assigned:
  * **Via Dashboard** (manual assignment per customer).
  * **Via API** (full flexibility):
    * Specify **customer name**.
    * Add **bill description** (e.g., Fees, Pocket Money).
    * Set payment amount and mode (full, partial, over).
    * Optionally set a **max total** so collections stop when the limit is reached.
    * Create multiple numbers for the same customer, each accepting multiple payments.
* Customers can pay via mobile money, CRDB SIM banking, or Wakala.
* Payments are tracked automatically via webhook or [Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments).

### Bulk or Batch Billing

For large organizations or corporate clients:

* Generate multiple **Order or Customer BillPay Control Numbers** via API in batch.
* Assign each number to specific invoices, customers, or departments.
* Clients pays using their assigned number.
* Payments are automatically tracked and reconciled in the organization's system using API or webhooks.


# Customer BillPay Control Number
Source: https://docs.clickpesa.com/bill-pay/customer-billpay-namba

A static payment number assigned to a specific customer for repeat payments

A **Customer BillPay Control Number** is a **static unique number** assigned by a merchant to a specific customer.
It is reusable for multiple transactions and ideal for frequent or subscription-based payments.

## How to Assign a Customer BillPay Control Number

You can assign one via the **ClickPesa Dashboard** or **API**.

## 1. Via Dashboard

The number is made of your **Merchant BillPay-Namba** + a **static unique number** generated by ClickPesa.

**Steps:**

1. Log in to your [Merchant Dashboard](https://merchant.clickpesa.com).
2. Follow the guide in [Customers](/dashboard/customers) to assign a control number.

## 2. Via API

You can create Customer BillPay Control Numbers programmatically using the [BillPay API](/api-reference/collection/billpay/create-customer-control-number).
API generation provides full flexibility similar to **Order BillPay Control Numbers**, plus additional customer-specific options:

* **Specify the customer name** (e.g., student name, client name).
* **Add a bill description** (e.g., Fees, Pocket Money, Subscription).
* **Set the payment amount** and mode (full, partial, over).
* **Set a max total** that can be collected across payments (optional). When the limit is reached, the number stops accepting payments.
* **Create multiple control numbers per customer**, each for a different bill or purpose.
* **Receive a generated control number** if not provided — this becomes the customer-facing number.

## Making Payments with Customer BillPay Control Numbers

Customers can pay using their assigned control number through mobile money, SIM banking, or CRDB Wakalas.

### [ via Airtel Money](#pay-via-airtel-money)

<Tabs>
  <Tab title="Airtel Money USSD">
    1. Piga `*150*60#`
    2. Chagua Chaguo `6` --- **Huduma za Kifedha / Financial Services**
    3. Chagua Chaguo `6` --- **SACCOS and MFI**
    4. Chagua Chaguo `1` --- **MFI**
    5. Chagua Chaguo `5` --- **A-G**
    6. Chagua Chaguo `8` --- **ClickPesa**
    7. Ingiza namba ya Kumbukumbu --- **\[]**
    8. Weka Kiasi
    9. Chagua `1` --- **(Ndio) Kuthibitisha**
    10. Weka PIN
  </Tab>

  <Tab title="Airtel Money APP">
    1. Fungua AirtelMoney App
    2. Bonyeza **Lipa Bili**
    3. Bonyeza **Ingiza jina la biashara au namba**
    4. Andika *"clickpesa"*
    5. Chagua **CLICKPESA TANZANIA**
    6. Weka Kumbukumbu ya Malipo --- **\[]**
    7. Weka Kiasi
    8. Bonyeza **Endelea**
    9. Weka Namba ya Siri
  </Tab>
</Tabs>

### [ via M-Pesa](#pay-via-m-pesa)

<Tabs>
  <Tab title="M-Pesa USSD">
    1. Piga `*150*00#`
    2. Chagua Chaguo `4` --- **Lipia Kwa M-Pesa**
    3. Chagua Chaguo `4` --- **Weka Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **\[M-Pesa Merchant Number]** - *Available at onboarding*
    5. Weka namba ya Kumbukumbu ya Malipo --- **\[]**
    6. Weka Kiasi
    7. Weka Namba ya Siri
    8. Bonyeza 1 Kuthibitisha
  </Tab>

  <Tab title="M-Pesa App">
    1. Fungua M-Pesa App
    2. Bonyeza **Lipia kwa M-Pesa**
    3. Bonyeza **Kitambulisho cha biashara** na Weka **\[M-Pesa Merchant Number]**
    4. Bonyeza **Kumbukumbu** na Weka **\[]**
    5. Weka Kiasi
    6. Bonyeza **Endelea**
    7. Bonyeza **Lipa sasa** na Ingiza Namba ya Siri
  </Tab>
</Tabs>

### [ via Mixx By Yas](#pay-via-mixx-by-yas)

<Tabs>
  <Tab title="Mixx By Yas USSD">
    1. Piga `*150*01#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
  </Tab>

  <Tab title="Mixx By Yas APP">
    1. Fungua Mixx By Yas App
    2. Bonyeza **Kulipa Bili**
    3. Andika *"clickpesa"* Kwenye **Tafuta**
    4. Chagua **ClickPesa-889999** Kwenye listi
    5. Weka Namba ya kumbukumbu --- **\[]**
    6. Weka kiasi
    7. Bonyeza **Endelea**
    8. Ingiza Namba ya Siri ya Mixx By Yas
    9. Bonyeza **Thibitisha**
  </Tab>
</Tabs>

### [ via Halopesa](#pay-via-halopesa)

<Tabs>
  <Tab title="Halopesa USSD">
    1. Piga `*150*88#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
    8. Chagua `1` --- **(Ndio) Kuthibitisha**
  </Tab>

  <Tab title="Halopesa APP">
    1. Fungua Halopesa App
    2. Bonyeza **Lipia Bili**
    3. Bonyeza **Chagua Namba ya biashara**
    4. Andika *"889999"* Kwenye uwanja wa kutafuta **Namba ya biashara**
    5. Bonyeza **ENDELEA**
    6. Weka kumbukumbu namba --- **\[]**
    7. Weka kiasi
    8. Bonyeza **ENDELEA**
    9. Ingiza Namba ya Siri
    10. Ingiza OTP
  </Tab>
</Tabs>

### [ via CRDB](#pay-via-crdb)

<Tabs>
  <Tab title="SimBanking USSD">
    1. Piga `*150*03#`
    2. Chagua `1` --- **Simbanking**
    3. Weka Namba ya Siri
    4. Chagua `4` --- **Pay Bills**
    5. Chagua `6`--- **Taasisi**
    6. Chagua `7` --- **Nyinginezo**
    7. Chagua `N` –-- **Next**
    8. Chagua `N` –-- **Next**
    9. Chagua **CLICKPESA**
    10. Weka Namba ya Malipo --- **\[]**
    11. Ingiza Kiasi
    12. Thibitisha Malipo
  </Tab>

  <Tab title="SimBanking APP">
    1. Fungua CRDB SimBanking App
    2. Weka Namba ya Siri ya SimBanking
    3. **Pandisha kupata huduma zaidi**
    4. Bonyeza **Malipo Zaidi**
    5. Chagua **CLICKPESA** Kwenye listi au andika **CLICKPESA** Juu Kwenye Tafuta huduma
    6. Weka Namba ya Malipo --- **\[]**
    7. Bonyeza **PATA TAARIFA**
    8. Hakikisha Taarifa za Bili, Chagua Akaunti Ya Kutoa na Weka Kiasi
    9. Bonyeza **ENDELEA**
    10. Hakikisha Taarifa za Muamala na Bonyeza **THIBITISHA**
  </Tab>

  <Tab title="CRDB Internet Banking">
    1. Login into your CRDB Internet Banking portal
    2. Select **Payment**
    3. Select **Bill Payment**
    4. Company Category --- Select **Others**
    5. Company Name -- Select **CLICKPESA**
    6. Enter Reference Number --- **\[]**
  </Tab>

  <Tab title="CRDB Wakala (App/POS)">
    1. Tembelea wakala CRDB aliye karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>

  <Tab title="CRDB Branch (OTC)">
    1. Tembelea tawi la CRDB lililo karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>
</Tabs>

## Payment Tracking

* **Real-time:** Set up a [Webhook](/home/webhooks) to get notified when payments arrive.
* **Manual Check:** Use the [Payment Query API](/api-reference/collection/querying-for-payments/querying-for-payments).


# Order BillPay Control Number
Source: https://docs.clickpesa.com/bill-pay/order-billpay-namba

A one-time payment number for a specific transaction or invoice — created via API or, for legacy accounts, by manual concatenation.

An **Order BillPay Control Number** is a **dynamic number** for a single transaction or invoice.
It is ideal for **one-time payments** such as e-commerce orders, invoices, or single service charges.

<Tip>
  New integrations should use the **BillPay API** to create order control numbers.
</Tip>

## Via API (Recommended)

When using the [BillPay API](/api-reference/collection/billpay/create-order-control-number), you get full control over the control number. You can directly set the **custom reference**, which becomes the **actual control number customers will use to pay**.
This means the number does **not** need to follow the offline concatenation format.

<Note>
  You can use your own references that already exist in your system (for example invoice, loan IDs or order IDs) as `billReference`. The value must be unique within ClickPesa for your account.
</Note>

With API generation, you can also:

* **Set the amount** to be paid (optional).
* **Control payment mode**:
  * Require full payment only.
  * Allow partial payments.
  * Allow overs.
* **Set a max total** that can be collected (optional). Caps how much this number can take; useful if you allow overs. Order numbers still accept only one payment.
* **Add a bill description**.
* **Set a custom reference** (actual customer-facing control number).

**Example use case:**
A SaaS platform generates an Order BillPay Control Number via API with a fixed amount, partial payment allowed, and a meaningful control number like `INV2025001`.

## Legacy: Manual Concatenation

<Warning>
  Legacy mode. Available only when enabled for your account by ClickPesa.
  Contact support or your account manager to request enablement.
</Warning>

**Structure:**
\[Merchant BillPay-Namba] + \[Order Reference]

* **Merchant BillPay-Namba** — your 4-digit merchant number assigned by ClickPesa.
* **Order Reference** — any unique reference from your internal billing or order system.

**Example:**
Merchant BillPay-Namba: 1122
Order Reference: 231256
Order BillPay Control Number: 1122231256

<Tip>
  This method does not require API calls. It is intended for merchants with existing offline billing systems who collect payments by combining their BillPay-Namba with an internal order reference.
</Tip>

## Making Payments with Order BillPay Control Numbers

Customers can pay via:

* **Mobile Money:** Mixx By Yas, Airtel Money, Halopesa, M-Pesa
* **CRDB Banking:** SIM Banking (APP/USSD), Internet Banking, CRDB Wakalas

### [ via Airtel Money](#pay-via-airtel-money)

<Tabs>
  <Tab title="Airtel Money USSD">
    1. Piga `*150*60#`
    2. Chagua Chaguo `6` --- **Huduma za Kifedha / Financial Services**
    3. Chagua Chaguo `6` --- **SACCOS and MFI**
    4. Chagua Chaguo `1` --- **MFI**
    5. Chagua Chaguo `5` --- **A-G**
    6. Chagua Chaguo `8` --- **ClickPesa**
    7. Ingiza namba ya Kumbukumbu --- **\[]**
    8. Weka Kiasi
    9. Chagua `1` --- **(Ndio) Kuthibitisha**
    10. Weka PIN
  </Tab>

  <Tab title="Airtel Money APP">
    1. Fungua AirtelMoney App
    2. Bonyeza **Lipa Bili**
    3. Bonyeza **Ingiza jina la biashara au namba**
    4. Andika *"clickpesa"*
    5. Chagua **CLICKPESA TANZANIA**
    6. Weka Kumbukumbu ya Malipo --- **\[]**
    7. Weka Kiasi
    8. Bonyeza **Endelea**
    9. Weka Namba ya Siri
  </Tab>
</Tabs>

### [ via M-Pesa](#pay-via-m-pesa)

<Tabs>
  <Tab title="M-Pesa USSD">
    1. Piga `*150*00#`
    2. Chagua Chaguo `4` --- **Lipia Kwa M-Pesa**
    3. Chagua Chaguo `4` --- **Weka Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **\[M-Pesa Merchant Number]** - *Available at onboarding*
    5. Weka namba ya Kumbukumbu ya Malipo --- **\[]**
    6. Weka Kiasi
    7. Weka Namba ya Siri
    8. Bonyeza 1 Kuthibitisha
  </Tab>

  <Tab title="M-Pesa App">
    1. Fungua M-Pesa App
    2. Bonyeza **Lipia kwa M-Pesa**
    3. Bonyeza **Kitambulisho cha biashara** na Weka **\[M-Pesa Merchant Number]**
    4. Bonyeza **Kumbukumbu** na Weka **\[]**
    5. Weka Kiasi
    6. Bonyeza **Endelea**
    7. Bonyeza **Lipa sasa** na Ingiza Namba ya Siri
  </Tab>
</Tabs>

### [ via Mixx By Yas](#pay-via-mixx-by-yas)

<Tabs>
  <Tab title="Mixx By Yas USSD">
    1. Piga `*150*01#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
  </Tab>

  <Tab title="Mixx By Yas APP">
    1. Fungua Mixx By Yas App
    2. Bonyeza **Kulipa Bili**
    3. Andika *"clickpesa"* Kwenye **Tafuta**
    4. Chagua **ClickPesa-889999** Kwenye listi
    5. Weka Namba ya kumbukumbu --- **\[]**
    6. Weka kiasi
    7. Bonyeza **Endelea**
    8. Ingiza Namba ya Siri ya Mixx By Yas
    9. Bonyeza **Thibitisha**
  </Tab>
</Tabs>

### [ via Halopesa](#pay-via-halopesa)

<Tabs>
  <Tab title="Halopesa USSD">
    1. Piga `*150*88#`
    2. Chagua Chaguo `4` --- **Lipia Bili**
    3. Chagua Chaguo `3` --- **Ingiza Namba ya Kampuni**
    4. Ingiza Namba ya Kampuni --- **889999**
    5. Weka Kumbukumbu ya Malipo --- **\[]**
    6. Ingiza Kiasi
    7. Ingiza Namba ya Siri
    8. Chagua `1` --- **(Ndio) Kuthibitisha**
  </Tab>

  <Tab title="Halopesa APP">
    1. Fungua Halopesa App
    2. Bonyeza **Lipia Bili**
    3. Bonyeza **Chagua Namba ya biashara**
    4. Andika *"889999"* Kwenye uwanja wa kutafuta **Namba ya biashara**
    5. Bonyeza **ENDELEA**
    6. Weka kumbukumbu namba --- **\[]**
    7. Weka kiasi
    8. Bonyeza **ENDELEA**
    9. Ingiza Namba ya Siri
    10. Ingiza OTP
  </Tab>
</Tabs>

### [ via CRDB](#pay-via-crdb)

<Tabs>
  <Tab title="SimBanking USSD">
    1. Piga `*150*03#`
    2. Chagua `1` --- **Simbanking**
    3. Weka Namba ya Siri
    4. Chagua `4` --- **Pay Bills**
    5. Chagua `6`--- **Taasisi**
    6. Chagua `7` --- **Nyinginezo**
    7. Chagua `N` –-- **Next**
    8. Chagua `N` –-- **Next**
    9. Chagua **CLICKPESA**
    10. Weka Namba ya Malipo --- **\[]**
    11. Ingiza Kiasi
    12. Thibitisha Malipo
  </Tab>

  <Tab title="SimBanking APP">
    1. Fungua CRDB SimBanking App
    2. Weka Namba ya Siri ya SimBanking
    3. **Pandisha kupata huduma zaidi**
    4. Bonyeza **Malipo Zaidi**
    5. Chagua **CLICKPESA** Kwenye listi au andika **CLICKPESA** Juu Kwenye Tafuta huduma
    6. Weka Namba ya Malipo --- **\[]**
    7. Bonyeza **PATA TAARIFA**
    8. Hakikisha Taarifa za Bili, Chagua Akaunti Ya Kutoa na Weka Kiasi
    9. Bonyeza **ENDELEA**
    10. Hakikisha Taarifa za Muamala na Bonyeza **THIBITISHA**
  </Tab>

  <Tab title="CRDB Internet Banking">
    1. Login into your CRDB Internet Banking portal
    2. Select **Payment**
    3. Select **Bill Payment**
    4. Company Category --- Select **Others**
    5. Company Name -- Select **CLICKPESA**
    6. Enter Reference Number --- **\[]**
  </Tab>

  <Tab title="CRDB Wakala (App/POS)">
    1. Tembelea wakala CRDB aliye karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>

  <Tab title="CRDB Branch (OTC)">
    1. Tembelea tawi la CRDB lililo karibu nawe
    2. Omba kulipia bili kwa namba ya malipo ya CRDB
    3. Toa jina la taasisi --- **CLICKPESA**
    4. Toa namba ya nmaba ya malipo --- **\[]**
    5. Toa kiasi
  </Tab>
</Tabs>

## Payment Tracking

* **Automatic Notifications:** Receive instant updates via [Webhooks](/home/webhooks).
* **Manual Check:** Use the [Payment Query API](/api-reference/collection/querying-for-payments/querying-for-payments).


# Checkout Link
Source: https://docs.clickpesa.com/checkout/checkout-link

The checkout link feature is for businesses and organizations with an app, website or software product who seek a streamlined method to accept online...

## Introduction

The checkout link feature is for businesses and organizations with an app, website or software product who seek a streamlined method to accept online payments for their goods and services. By making an API request to our checkout link generation endpoint, merchants can create a unique checkout link from their apps, websites, or systems. Once generated, this link can process multiple payments, giving a notification each time a transaction is processed, with all transactions easily viewable in the ClickPesa dashboard. See [Common Use Cases](/checkout/common-use-cases) for where this fits your business.

## **How to Use the Feature**

To use this feature, you need a ClickPesa account with full KYC and the Checkout Link feature activated in your dashboard settings.

### **Activating Checkout Link**

Activate Checkout Link under **Settings → Collection** in the Merchant Dashboard. See [Collection Settings](/dashboard/settings/collection) for the full walkthrough.

After activation, create checkout links and collect payments using the [Checkout Link API](/checkout/checkout-link-api).


# Checkout Link API
Source: https://docs.clickpesa.com/checkout/checkout-link-api

Generate Hosted Checkout link using API

* Quick & Flexible – Generate Hosted Checkout links with minimal API calls and seamlessly integrate them across platforms.
* Secure & User-Friendly – Designed for a secured seamless experience for developers and users.

## Prerequisites

1. [Hosted Application](/application/hosted-application-setup) -
   Create an application and generate **Client ID** and **API Keys** for Hosted Checkout

2. **Authorization Token** -
   Use **API Keys** of to [Generate Authorization Token](/api-reference/authorization/generate-token)

## How It Works

<Card title="Generate Hosted Checkout Link" icon="brackets-curly" href="/api-reference/collection/generate-checkout-link/generate-checkout-link">
  Use this API endpoint to generate a Hosted Checkout Link
</Card>

## Payment notifications

When a customer completes payment on the hosted checkout page (including mobile push payments), you can receive status updates in three ways:

1. **[Application webhooks](/home/webhooks#application-level-webhooks)** — Configure `PAYMENT RECEIVED` (and `PAYMENT FAILED` if needed) under your hosted application in the dashboard.
2. **`callbackUrl` on the generate link request** — Optional field on [Generate Checkout Link](/api-reference/collection/generate-checkout-link/generate-checkout-link). ClickPesa sends an HTTP POST to this URL when a payment for that link succeeds.
3. **[Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments)** — Poll by your `orderReference`.

If an application webhook is configured for the event, it is used instead of the merchant-level webhook. See [Webhooks](/home/webhooks) for payload details.

<Note>
  After payment, customers are redirected to the **Return URL** on your [hosted application](/application/hosted-application-setup) in the dashboard. That redirect is not set on the generate link request.
</Note>


# Hosted Checkout Overview
Source: https://docs.clickpesa.com/checkout/checkout-overview

Hosted Checkout is a ready-to-use payment acceptance experience provided by ClickPesa.

Hosted Checkout enables seamless payment collection and supports a full range of payment methods and currencies with minimal integration.

It is available as part of ClickPesa products like [E-invoice](/dashboard/e-invoice) and [Payment Pages](/dashboard/payment-pages), where it comes built-in, and it is also available for integration into your web application or platform through [Checkout Links](/checkout/checkout-link).

* **Quick and Easy Integration** — Simply generate a hosted checkout link, share it with a customer and start accepting payments instantly.
* **Hassle-Free** — Security and updates are fully managed by ClickPesa, allowing you to focus on your business.

## How It Works

1. **Generate a Checkout Link** — Use the [Checkout Link API](/checkout/checkout-link-api) to generate a hosted checkout link from your app or system. Checkout links are also generated automatically for [Invoices](/dashboard/e-invoice) and [Payment Pages](/dashboard/payment-pages) created in the dashboard.

2. **Redirect Customers** — Add the generated checkout link into your checkout, website or share it via WhatsApp and redirect customers to Hosted Checkout to make a payment.

3. **Receive Payment Confirmation** — Receive payment updates via [Application Webhooks](/home/webhooks#application-level-webhooks), an optional [`callbackUrl`](/api-reference/collection/generate-checkout-link/generate-checkout-link) on the Generate Checkout Link request, or by polling the [Query Payment API](/api-reference/collection/querying-for-payments/querying-for-payments). Application webhooks apply to all payment methods on the hosted page, including mobile push. Customers are redirected after payment using the Return URL on your hosted application in the dashboard.

## In the Merchant Dashboard

<CardGroup>
  <Card title="Payment Pages" icon="file-invoice" href="/dashboard/payment-pages">
    Create shareable payment pages with built-in hosted checkout.
  </Card>

  <Card title="E-Invoice" icon="receipt" href="/dashboard/e-invoice">
    Create and send invoices with a built-in checkout link.
  </Card>

  <Card title="Checkout Links" icon="link" href="/dashboard/checkout-links">
    View and manage hosted checkout links created via API or integrations.
  </Card>

  <Card title="Collection Settings" icon="gear" href="/dashboard/settings/collection">
    Enable payment methods and activate Checkout Link in the dashboard.
  </Card>
</CardGroup>

## Learn More

<CardGroup>
  <Card title="The Hosted Checkout Page" icon="credit-card" href="/checkout/checkout-page">
    What your customers see and how they pay — payment methods, currencies and receipts
  </Card>

  <Card title="Checkout Link" icon="link" href="/checkout/checkout-link">
    Use cases and how to activate the Checkout Link feature in your dashboard
  </Card>

  <Card title="Checkout Link API" icon="brackets-curly" href="/checkout/checkout-link-api">
    Generate Hosted Checkout links from your own application via API
  </Card>
</CardGroup>


# The Hosted Checkout Page
Source: https://docs.clickpesa.com/checkout/checkout-page

Hosted Checkout is a feature that facilitates seamless payments for customers of ClickPesa merchants. It allows users to pay for Payment Pages, Invoices,...

## Introduction

Hosted Checkout is a feature that facilitates seamless payments for customers of ClickPesa merchants. It allows users to pay for [Payment Pages](/dashboard/payment-pages), [Invoices](/dashboard/e-invoice), or [Checkout Links](/checkout/checkout-link) with ease. This document provides an overview of how this feature works and guides users through common use cases.

## How to Use checkout

To utilize Hosted Checkout, users need to follow these steps:

## **Accessing a Valid Link**

To initiate a payment, users must have a valid [Payment Page link](/dashboard/payment-pages), [Invoice link](/dashboard/e-invoice), or [Checkout-Link Link](/checkout/checkout-link). Invoice and Payment Page links can be found in the ClickPesa dashboard in their respective sections and for Checkout-link Link, please see [Checkout Link documentation](/checkout/checkout-link) to learn more about generating checkout links.

### Payment Page

When customers visit the payment page, they see the page name and, if a customer is attached, the customer’s name. The merchant’s email is shown at the bottom so customers can get in touch.

* **Fixed amount:** The amount and currency are shown on the page
* **Open amount:** No amount is shown until the customer enters one in checkout

If the page has passed its expiry date or has been deactivated, it no longer accepts payments.

<Frame>
  <img alt="Checkout Payment Page" />
</Frame>

Lastly, there is a **Pay Now** button which opens checkout so the customer can enter details and pay. More about making payments in the section about [Filling Payment Details](#filling-details).

### Invoice

When customers visit the Invoice link, they will see the name of the merchant who sent the invoice, the invoice amount and currency, the invoice due date if available, the customer name if the customer was added during invoice creation, the invoice number, an option to view details which will show all items added to the invoice, the merchant’s email at the bottom which customers can use to contact the merchant.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

The invoice also shows the invoice status, we have three statuses for invoices, OVERDUE, PARTIAL PAID and PAID. If an invoice is paid it's going to have PAID status stamped on it, if invoice total payments amount is less than the invoice amount, the status is PARTIAL PAID and if the invoice payments are overdue it's going to have an OVERDUE status stamped on it.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

**Download invoice as pdf file.**

You can download invoice as pdf file and share it with your customers. When they open the file they wil be able to open checkout from within a file as we embedded an invoice link.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

Lastly, there is a button called “Make Payment” which will open a drawer and allow the customer to fill in the details needed to make their payment. More about making payments in the section about [Filling Payment Details](#filling-details).

### Checkout Link

When customers visit the checkout link, they will see the name of the merchant who sent the checkout link, the checkout link amount and currency, the order reference that was provided during checkout link creation, the customer name if the customer was added during checkout link creation, an option to view details which will show all items added to the checkout link, the merchant’s email at the bottom which customers can use to contact the merchant.

<Frame>
  <img alt="Image 1 1024x692" />
</Frame>

Lastly, there is a button called “Make Payment” which will open a drawer and allow the customer to fill in the details needed to make their payment. More about making payments in the section about [Filling Payment Details](#filling-details).

<Frame>
  <img alt="Image 2 1024x692" />
</Frame>

<Frame>
  <img alt="Image 3 1024x849" />
</Frame>

## Filling Payment Details

When a customer visits a valid Payment Page, Invoice, or Checkout-Link link, they will see details about the payment — including the amount when one is set, who is receiving the payment, and the customer's name if provided. Users can proceed by clicking the "Pay Now" button.

<Frame>
  <img alt="Image 7 1024x692" />
</Frame>

### **Customer Details Section**

If the Payment Page, Invoice, or Checkout-Link lacks customer details, users will be prompted to enter their full name, email, and phone number in this section.

<Frame>
  <img alt="Image 4 1024x675" />
</Frame>

### **Amount Section**

* **Open amount Payment Pages:** The amount field is empty. The customer must enter how much to pay
* **Fixed amount Payment Pages and Invoices:** The amount is prefilled. Customers can change it only if **Allow Amount Update** is enabled in [Collection settings](/dashboard/settings/collection)
* **Checkout Links:** The amount field is locked. Customers must pay the amount set when the link was created

<Frame>
  <img alt="Image 5 1024x387" />
</Frame>

### **Payment Method Selection**

In this section, customers will see a list of available payment methods. Each payment method is accompanied by a logo, a commonly known name, information on supported currencies, processing fees, and exchange rates (if applicable).

<Frame>
  <img alt="Screenshot 2023 11 01 At 09.13.30 687x1024" />
</Frame>

Integrated payment methods include:

* Mixx By Yas PUSH USSD which supports TZS payments
* AIRTEL MONEY PUSH USSD which supports TZS payments
* Mixx By Yas BILLPAY which supports TZS payments and is a backup of Mixx By Yas USSD, i.e. it is only available if Mixx By Yas PUSH USSD is not available.
* NMB BILLPAY which supports TZS payments
* CARDS (VISA, MASTERCARD, and UNION PAY) which supports USD payments
* BANK DEPOSIT/TRANSFER.

The availability of payment methods depends on various factors, including ClickPesa team decisions, merchant preferences, and currency exchange settings.

* **ClickPesa Team Decisions** The ClickPesa team has the authority to enable or disable payment methods for a specific merchant.
* **Technical Complications and Integration Issues** ClickPesa may enable or disable an individual payment method if technical complications or integration issues arise.
* **Merchant Preferences** Merchants have control over their payment method offerings within their merchant dashboards. They can enable or disable specific payment methods based on their preferences and the expectations of their customers.
* **New Merchant Settings** For new merchants joining the platform, all payment methods are initially disabled. Merchants need to log in to their ClickPesa dashboard and manually enable the payment methods they wish to offer.
* **Currency Exchange Feature** The currency in which an order (Payment Page, Invoice, or Checkout Link) is denominated and the exchange capabilities within ClickPesa also influence payment method availability. If the exchange feature for a particular currency is disabled, only payment methods that support that currency will be available for orders denominated in that currency.

### Fee

Customer will be responsible for all the fee encountered during making payments. [Click here](https://clickpesa.com/payment-gateway/pricing/) to learn more about how we charge fees.

### **Payment Initiation**

After filling in the necessary details and selecting a suitable payment method, users can initiate the payment. The system will provide instructions on how to complete the payment. At this point, the payment will be in "PROCESSING" status, and its progress can be monitored in the ClickPesa dashboard of the merchant.

### **Payment Completion**

* If the customer successfully follows the instructions and completes the payment, they will be redirected to a receipt page, displaying a summary of their successful payment. Then funds will shortly be settled to your wallet. This will send [notification](/dashboard/notifications) to you via email or merchant dashboard.
* Customer will also receive notification via sms or email on successfully payment.
* If the payment timer runs out or if the transaction fails, the customer will be redirected to the receipt page with information about the failed payment.
* In the event that the payment is still in a "PROCESSING" state, the receipt page will display a loader until the payment reaches a "failed" or "successful" state.
* Users also have the option to go back or try the payment again based on whether the payment was successful or failed.
* Successfully card payments can be REVERSED or REFUNDED upon request to do so.

Hosted Checkout is designed to cater to the following common use cases:

## Common Use Cases

1. Paying for Payment Pages created by ClickPesa merchants.
2. Settling Invoices issued by ClickPesa merchants.
3. Finalizing payments for Checkout Links, as detailed in the Checkout-link documentation.

## Frequently Asked Questions

1. Where can I find the Payment Page or Invoice?
   * The links can be found in the ClickPesa dashboard within their respective sections. Check documentation for [e-invoice](/dashboard/e-invoice) and [payment page](/dashboard/payment-pages).
2. How to generate Checkout-Link links
   * Please see the [documentation for checkout-link](/checkout/checkout-link)
3. Can I modify the payment amount for Payment Pages and Invoices?
   * Yes, for Payment Pages and Invoices, customers can enter a custom payment amount, which may differ from the originally assigned amount during order creation.
4. What payment methods are available for Hosted Checkout?
   * Hosted Checkout supports various payment methods, including:-
     * Mixx By Yas PUSH USSD
   * * AIRTEL MONEY PUSH USSD
   * * Mixx By Yas BILLPAY
   * * NMB BILLPAY
   * * CARDS (VISA, MASTERCARD, and UNION PAY)
   * * BANK DEPOSIT/TRANSFERPayment methods may or may not be available depending on factors such as merchant preferences, currency exchange settings, or ClickPesa team decisions.
5. What happens if my payment is still in "PROCESSING" status while on the receipt page?
   * If your payment is in "PROCESSING" status, the receipt page will display a loader until the payment reaches a "failed" or "successful" state.
6. How do I handle a failed payment through Hosted Checkout?
   * If your payment fails, the receipt page will provide information about the failed payment and offer options for retrying the payment.


# Common Use Cases
Source: https://docs.clickpesa.com/checkout/common-use-cases

Where Hosted Checkout and Checkout Links fit your business

The checkout link feature is for businesses and organizations with an app, website or software product who seek a streamlined method to accept online payments for their goods and services. This includes e-commerce platforms selling both digital and physical items, exclusive membership apps, ticketing systems, and even third-party software vendors aiming for customer integration. Once generated, a checkout link can process multiple payments, giving a notification each time a transaction is processed, with all transactions easily viewable in the ClickPesa dashboard.

* **E-commerce Checkout**:
  This feature can empower online businesses, from fashion retailers to electronics shops. Customers can visit an online shop, select their preferred products, generate a checkout link, and make secure payments from anywhere.
* **Event Ticketing**:
  Event organizers for concerts, sports games, or local events can utilize this feature. They generate checkout links for ticket purchases. Attendees can pay online, and the organizer easily tracks ticket sales from the ClickPesa dashboard.
* **Digital Products**:
  Content creators, such as authors, musicians, or online educators, can leverage checkout links to streamline the purchase of digital products like ebooks, music, or online courses.
* **Subscription Services**:
  Whether it's a streaming platform or a fitness app, businesses offering subscription-based services can integrate checkout links. This enables customers to pay their monthly fees conveniently.
* **Food Delivery Services**:
  Food delivery services can provide a hassle-free payment experience for customers. They can place orders online and use checkout links to complete payments securely.
* **Donations and Fundraising**:
  Non-profit organizations and charities can use checkout links to collect donations for various causes. It makes contributing to fundraising campaigns more accessible.
* **Microfinance**:
  Microfinance institutions can streamline payment collections by integrating the checkout link feature with their existing loan management systems. This simplifies the repayment process for borrowers, enhancing financial inclusion.


# CRDB Direct Debit API
Source: https://docs.clickpesa.com/crdb-direct-debit/api-overview

Request mandate approvals, query, and cancel CRDB Direct Debit mandates with the Collection API

The CRDB Direct Debit API lets you request mandate approvals for recurring collections from customers' CRDB bank accounts, receive mandate status callbacks, and get payment events through webhooks.

## Prerequisites

1. **Activate CRDB Direct Debit** for your merchant account in the [Merchant Dashboard](/crdb-direct-debit/setup).
2. **API keys** — [Create an Application](/application/api-application-setup) with the **Collection API** feature enabled.
3. **Authorization token** — Use your API keys to [Generate an Authorization Token](/api-reference/authorization/generate-token).

## How It Works

### Step 1 – Request Mandate Approval

<Card title="Request Mandate Approval" icon="brackets-curly" href="/api-reference/collection/crdb-direct-debit/request-mandate">
  Request mandate approval and create the linked payment schedule. Provide customer details, CRDB debit account, SimBanking phone number, dates, frequency, installment amount, and a mandate callback URL.
</Card>

The response includes `mandateRequestId`, initial `mandateStatus` (**REQUESTED**), total amount, and number of installments.

The customer then receives notifications with instructions on how to approve the mandate via their CRDB SIM-Banking App.

### Step 2 – Receive Mandate Status Callbacks

ClickPesa sends an HTTP `POST` to your `mandateCallbackUrl` when the mandate status changes to **ACTIVE**, **REJECTED**, or **CANCELLED**.

Use `mandateReference` from the **ACTIVE** / **REJECTED** callback to correlate later installment payments (`orderReference` on payment webhooks matches this reference).

See [Mandate status callbacks](/crdb-direct-debit/api-overview#mandate-status-callbacks) below and the [Request Mandate Approval](/api-reference/collection/crdb-direct-debit/request-mandate) reference.

### Step 3 – Query Mandate Details (optional)

<Card title="Get Mandate" icon="brackets-curly" href="/api-reference/collection/crdb-direct-debit/get-mandate">
  Retrieve mandate status, CRDB account details, and payment plan summary using `mandateRequestId`.
</Card>

### Step 4 – Receive Payment Events

Configure **[Application webhooks](/home/webhooks#application-level-webhooks)** (or merchant webhooks) for:

* `PAYMENT RECEIVED` — installment collected successfully
* `PAYMENT FAILED` — installment failed (for example insufficient funds, or mandate issues)

Payment payloads use `"channel": "CRDB DIRECT DEBIT MANDATE"`. The `orderReference` field is the **mandate reference** from CRDB.

### Step 5 – Cancel Mandate (optional)

<Card title="Cancel Mandate" icon="brackets-curly" href="/api-reference/collection/crdb-direct-debit/cancel-mandate">
  Cancel an **ACTIVE** mandate. The linked payment plan and unpaid cycles are cancelled when the plan is still active.
</Card>

## Mandate Status Callbacks

Callbacks are sent to the `mandateCallbackUrl` you provided when requesting mandate approval.

**ACTIVE**

```json theme={null}
{
  "mandateRequestId": "69383ce4f8b5a8e2077df9c7",
  "mandateReference": "9009099",
  "mandateStatus": "ACTIVE",
  "mandateConfirmedAt": "2025-12-09T15:16:09.557Z"
}
```

**REJECTED**

```json theme={null}
{
  "mandateRequestId": "69382ac2358bdec745001d88",
  "mandateReference": "7767768907",
  "mandateStatus": "REJECTED",
  "mandateConfirmedAt": "2025-12-09T13:58:47.229Z"
}
```

**CANCELLED**

```json theme={null}
{
  "mandateRequestId": "693072b84e85ba41d1de3580",
  "mandateStatus": "CANCELLED",
  "mandateReference": "10540",
  "mandateCancelledAt": "2025-12-03T17:26:54.264Z"
}
```

## Important Rules

* One **active mandate per CRDB debit account** at a time
* `phoneNumber` must be a **SimBanking-registered** number for the debit account (12 digits, country code, no `+`)
* Dates: `DD-MM-YYYY` or `YYYY-MM-DD`
* Frequency types: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY` (optional `frequency` multiplier, default `1`)
* Cancel is only allowed when mandate status is **ACTIVE**

## API Reference

| Endpoint                                                                                | Description                                              |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [Request Mandate Approval](/api-reference/collection/crdb-direct-debit/request-mandate) | Request mandate approval and create the payment schedule |
| [Get Mandate](/api-reference/collection/crdb-direct-debit/get-mandate)                  | Retrieve mandate status and plan summary                 |
| [Cancel Mandate](/api-reference/collection/crdb-direct-debit/cancel-mandate)            | Cancel an active mandate                                 |

## Also See

* [CRDB Direct Debit Overview](/crdb-direct-debit/crdb-direct-debit-overview)
* [Payment Plans (dashboard)](/crdb-direct-debit/payment-plans)
* [Webhooks](/home/webhooks)
* [FAQ](/crdb-direct-debit/faq)


# CRDB Direct Debit Overview
Source: https://docs.clickpesa.com/crdb-direct-debit/crdb-direct-debit-overview

Collect recurring payments from customers' CRDB bank accounts with mandate-based Direct Debit

**CRDB Direct Debit** lets you collect scheduled payments from a customer's CRDB bank account after they approve a mandate. Once the mandate is active, installments are collected automatically according to the schedule you set.

Use it through the **Merchant Dashboard** with [Payment Plans](/crdb-direct-debit/payment-plans), or through the **[CRDB Direct Debit API](/crdb-direct-debit/api-overview)** for full control in your own systems.

<Tip>
  Direct Debit collections appear in your [Merchant Dashboard](https://merchant.clickpesa.com) payments list with channel **CRDB DIRECT DEBIT MANDATE**, and can trigger [webhook notifications](/home/webhooks) when payments succeed or fail.
</Tip>

## When To Use It

* **Installment collections:** School fees, loans, rent, or other payments spread over time
* **Subscriptions and memberships:** Recurring charges on a daily, weekly, monthly, or yearly schedule
* **Customer agreements:** Collect from a named customer after they approve the mandate via their CRDB SIM-Banking App
* **Automated collection:** Reduce manual follow-up once the mandate is active

## How It Works

1. **Activate** — Enable CRDB Direct Debit in your Merchant Dashboard under **Settings → Collection** (KYC and activation fee required).
2. **Request mandate approval** — Create a Payment Plan in the dashboard, or call the API with the customer's CRDB account, SimBanking phone number, schedule, and installment amount.
3. **Customer approves** — The customer receives notifications with instructions on how to approve the mandate via their CRDB SIM-Banking App. You receive a status update when it becomes **ACTIVE** or **REJECTED**.
4. **Installments collect** — While the mandate is active, scheduled debits run automatically. Successful and failed collections are recorded as payments.
5. **Optional cancel** — You can cancel an **ACTIVE** mandate (and the linked payment plan) from the dashboard or via the API.

<Warning>
  A CRDB account can only have **one mandate at a time**. Cancel or complete any existing mandate on that debit account before requesting a new one.
</Warning>

## Mandate statuses

| Status        | Meaning                                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| **REQUESTED** | Mandate submitted; customer receives notifications with instructions to approve via their CRDB SIM-Banking App |
| **ACTIVE**    | Mandate approved; scheduled collections can run                                                                |
| **REJECTED**  | Mandate was not approved; no installments will collect                                                         |
| **CANCELLED** | Mandate revoked; further scheduled collections stop                                                            |

## In the Merchant Dashboard

<CardGroup>
  <Card title="Set Up Direct Debit" icon="gear" href="/crdb-direct-debit/setup">
    Activate CRDB Direct Debit in Collection settings.
  </Card>

  <Card title="Payment Plans" icon="calendar" href="/crdb-direct-debit/payment-plans">
    Create and manage installment plans and mandates.
  </Card>

  <Card title="Customers" icon="users" href="/dashboard/customers">
    View a customer's payment plans from their customer profile.
  </Card>

  <Card title="Payment Transactions" icon="list" href="/dashboard/transactions/payments">
    Track Direct Debit installment payments.
  </Card>
</CardGroup>

## For Developers

<CardGroup>
  <Card title="API Overview" icon="code" href="/crdb-direct-debit/api-overview">
    Request, query, and cancel mandates with the Collection API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/home/webhooks">
    Receive payment events and mandate status callbacks.
  </Card>
</CardGroup>


# CRDB Direct Debit FAQ
Source: https://docs.clickpesa.com/crdb-direct-debit/faq

Common questions about CRDB Direct Debit, Payment Plans, and mandates

## Activation

**Why can't I turn on CRDB Direct Debit?**

Complete [KYC](/dashboard/settings/kyc) first. Direct Debit also requires a one-time activation fee of **250,000 TZS**. See [Set Up CRDB Direct Debit](/crdb-direct-debit/setup).

## Mandates and accounts

**Can one CRDB account have multiple mandates?**

No. A debit account can have only **one mandate at a time**. Cancel or complete the existing mandate before requesting another.

**What phone number should I use?**

Use the customer's **CRDB SimBanking** mobile number for the debit account: 12 digits starting with the country code (for example `2557…`), without a `+`.

**How does the customer approve a mandate?**

The customer receives notifications with instructions on how to approve the mandate via their CRDB SIM-Banking App.

**What do REQUESTED, ACTIVE, REJECTED, and CANCELLED mean?**

See [mandate statuses](/crdb-direct-debit/crdb-direct-debit-overview#mandate-statuses) in the overview.

## Payment Plans

**Where do I create a plan in the dashboard?**

Open **Payment Plans** in the sidebar, or open a customer and use the **Payment Plans** tab. Guide: [Payment Plans](/crdb-direct-debit/payment-plans).

**What happens if a mandate is rejected?**

The related plan will not collect installments. Create a new plan only after resolving the rejection (and ensuring no conflicting mandate remains on the account).

**Can I cancel collections mid-plan?**

Yes, if the mandate is **ACTIVE**. Cancel from the plan details in the dashboard or via [Cancel Mandate](/api-reference/collection/crdb-direct-debit/cancel-mandate).

## API and webhooks

**Which application feature do I need?**

The application must have the **Collection API** feature enabled.

**How do I match installment payments to a mandate?**

Use `mandateReference` from the mandate status callback. On `PAYMENT RECEIVED` / `PAYMENT FAILED` webhooks, `orderReference` is that mandate reference, and `channel` is `CRDB DIRECT DEBIT MANDATE`.

**Are mandate status updates sent on the same webhook as payments?**

No. Mandate status changes go to the **`mandateCallbackUrl`** you supply when requesting mandate approval. Payment success/failure uses your configured [application or merchant webhooks](/home/webhooks).

## Notifications

**Will I get notified in the dashboard?**

Yes. Merchants receive notifications when a mandate is requested, approved, rejected, or cancelled. See [Notifications](/dashboard/notifications).

## Need more help?

Contact [support@clickpesa.com](mailto:support@clickpesa.com).


# Payment Plans
Source: https://docs.clickpesa.com/crdb-direct-debit/payment-plans

Create and manage CRDB Direct Debit payment plans in the Merchant Dashboard

**Payment Plans** are how you set up recurring CRDB Direct Debit collections in the Merchant Dashboard. Each plan links a customer, a debit schedule, and a CRDB mandate.

<Note>
  Activate [CRDB Direct Debit](/crdb-direct-debit/setup) before creating a plan. Developers can also request mandate approvals with the [CRDB Direct Debit API](/crdb-direct-debit/api-overview).
</Note>

## What You Can Do

* Create a plan with installment amount, start/end dates, and frequency (daily, weekly, monthly, or yearly)
* Request CRDB Direct Debit mandate approval for the customer's CRDB account
* Track mandate status (**REQUESTED**, **ACTIVE**, **REJECTED**, **CANCELLED**)
* Review upcoming and past installment cycles on the plan details page
* See plans for a specific customer on the customer **Payment Plans** tab
* Cancel an active mandate when collections should stop

## Create a Payment Plan

1. Open **Payment Plans** in the Merchant Dashboard sidebar, or open a [customer](/dashboard/customers) and use their **Payment Plans** tab.
2. Start **Create Payment Plan**.
3. Choose the customer and plan details:
   * **Installment amount** (TZS)
   * **Start date** and **end date**
   * **Frequency** (for example every month, or every 2 weeks)
   * **Bill details** / description
4. Add the CRDB payment method details:
   * **CRDB account number** (debit account)
   * **CRDB SimBank mobile number** (12 digits, country code, no `+`) — must be registered for SimBanking on that account
5. Review the plan summary and upcoming installments, then submit to **request approval**.

After submission, the mandate starts as **REQUESTED**. The customer receives notifications with instructions on how to approve the mandate via their CRDB SIM-Banking App. When the mandate becomes **ACTIVE**, scheduled collections can begin. If the mandate is **REJECTED**, installments will not collect.

<Warning>
  A CRDB account can only have **one mandate at a time**. If the debit account already has an active mandate, cancel or complete it before creating a new plan.
</Warning>

## Plan Details

On a plan's details page you can:

* See customer and mandate information (including CRDB account and SimBank number)
* Review installment cycles (due dates, amounts, and collection status)
* Follow mandate status changes
* Cancel an **ACTIVE** mandate when needed

## Notifications

You receive merchant notifications when a Direct Debit mandate is:

* **Requested**
* **Approved** (plan active)
* **Rejected**
* **Cancelled**

See [Notifications](/dashboard/notifications) for in-app, email, and web channels.

## Payments

Successful and failed installment attempts appear under **Transactions → Payments** with channel **CRDB DIRECT DEBIT MANDATE**. Configure [webhooks](/home/webhooks) if you want the same events in your own systems.


# Set Up CRDB Direct Debit
Source: https://docs.clickpesa.com/crdb-direct-debit/setup

Activate CRDB Direct Debit in the ClickPesa Merchant Dashboard

<Note>
  Learn what CRDB Direct Debit is in the [CRDB Direct Debit Overview](/crdb-direct-debit/crdb-direct-debit-overview). Collection settings are also documented in [Collection Settings](/dashboard/settings/collection).
</Note>

## Before You Start

Make sure you have:

* A **verified ClickPesa merchant account** with completed [KYC](/dashboard/settings/kyc)
* The **CRDB Direct Debit activation fee** (**250,000 TZS**) ready to pay when prompted

<Info>
  CRDB Direct Debit cannot be enabled until KYC is approved. See [limits before KYC approval](/home/onboarding#limits-before-kyc-approval).
</Info>

## Activation Steps

### 1. Open Collection Settings

1. Log in to your [Merchant Dashboard](https://merchant.clickpesa.com).
2. Go to **Settings → Collection**, or open **Get Started → Payment Methods**.
3. Find **CRDB Direct Debit** under online / checkout collection methods.

### 2. Complete KYC (if not already done)

If your account is not yet verified, complete KYC under **Settings → KYC** before activation.

### 3. Pay the Activation Fee

Toggle on **CRDB Direct Debit** and complete the one-time activation payment of **250,000 TZS** when prompted.

### 4. Confirm the Method Is Active

After successful payment and activation:

* **CRDB Direct Debit** shows as active in Collection settings
* You can create [Payment Plans](/crdb-direct-debit/payment-plans) that collect via Direct Debit
* API applications with **Collection API** access can [request mandate approvals](/crdb-direct-debit/api-overview)

## Managing Direct Debit

* **View status** anytime under **Settings → Collection**.
* **Toggle the method** on or off using the switch next to CRDB Direct Debit (platform availability and your activation still apply).
* **Create plans** from **Payment Plans** in the sidebar, or from a [customer](/dashboard/customers) profile.
* **Track payments** in [Payments](/dashboard/transactions/payments) with channel **CRDB DIRECT DEBIT MANDATE**.

## Need Help?

Contact [support@clickpesa.com](mailto:support@clickpesa.com) for activation issues or questions about Direct Debit registration.


# Balance
Source: https://docs.clickpesa.com/dashboard/account/balance

Balance is where collected payments are settled and also balance is used for disbursing (bulk) payouts to

## Introduction

Balance is where collected payments are settled and also balance is used for disbursing (bulk) payouts to recipients.

For collected payments, as soon as the payment from your customer is successful, it is settled to the balance. You should be able to see added funds on your balances. After funds are settled to your ClickPesa balance, you will be able to [withdraw funds](/dashboard/account/withdraws) to your [local account](/dashboard/settings/disbursement).

For disbursement of payouts, you can top-up your [balance](/dashboard/disbursement/bulk-payouts) via [bulk payout](/dashboard/disbursement/bulk-payouts) or [deposit](/dashboard/account/deposits) processes.

## How to use balance

### How to view all balances

1. From your dashboard, navigate to the left-hand side and select "Account".
2. You will see two cards under the title Balances, the first showing the Available TZS balance and the other showing the Available USD balance. You can withdraw funds from USD and TZS balances.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Frequently Asked Questions (FAQ)

1. **Where is balance used for?**\
   Balance is used for the settlement of your collected payments and [(bulk) payouts](/dashboard/disbursement/bulk-payouts).
2. **Does my collected payments also show in this balance** **after received**?\
   Yes, collected payment show in the balance after received
3. **What is the settlement time of my collected payments**?\
   Collected payments through card (Mastercard / Visa / UnionPay) are settled within T+2 working days. Any other collected payment is nearly instant.
4. **I collected a payment of one of my customers but my collected payment does not show yet in my balance, what do I do?**\
   The status of collected payments can be followed under [transactions](/dashboard/transactions/payments). Card payments sometimes can take longer then T+2 working days to process due to various checks and authorizations that need to take place.
5. **Do my collected payments settle in a single payment or do you settle each collected payment separately?**\
   Each payment is settled separately to your ClickPesa balance which you will be able to withdraw funds to the bank account you added as [settlement account](/dashboard/settings/disbursement).
6. **Can I see the status of my collected payments?**\
   Yes, that is possible under [transactions](/dashboard/transactions/payments).
7. **Why does USD balance show?**\
   Payment pages and invoices can accept payments from USD via card or bank transfer. Payments made for invoices or payment pages with USD currency will be settled to USD balance.
8. **How do I top-up my balance for a (bulk) payout?**\
   You can top-up your using the [deposit](/dashboard/account/deposits) functionality on this account page.


# Deposits
Source: https://docs.clickpesa.com/dashboard/account/deposits

This guide will walk you through the process of doing a deposit to your account. With Deposit you can fund your balance. You can use funds to payout via...

This guide will walk you through the process of doing a deposit to your account. With Deposit you can fund your [balance](/dashboard/account/balance). You can use funds to payout via [bulk payouts](/dashboard/disbursement/bulk-payouts) or [single payout](/dashboard/disbursement/single-payout).

Oversees your deposit transactions is a crucial aspect of any business, and being able to track and review deposits is fundamental to maintaining transparency and control over your finances. Our dashboard offers a streamlined and user-friendly interface to view all your deposits and even export this data for further analysis or record-keeping.

## How to use deposits

### How to do a deposit

1. From your dashboard, navigate to the left-hand side and select "Account".

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. Click the “Deposit” button at the top right corner of the transactions page. You can only withdraw when there is a positive balance.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. This will open a drawer with Bank method already selected, an amount field and currency selector with two options (TZS and USD).

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You will be presented with deposit instructions upon clicking Next button. You will also receive [notification](/dashboard/notifications) via email and dashboard with deposit instructions.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Once deposit is successful you will receive funds to your account and a [notification](/dashboard/notifications) via email or dashboard.
6. If funds are not deposited within 3 days, the deposit will automatically be canceled and you will have to initiate another deposit.

### View all deposits

1. From your dashboard, navigate to the left-hand side and select "Account"

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. You will be able to filter deposits summary and data by date, status and searching by reference, order id, channel or channel provider.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the page you should be able to see summary with deposits count and value
4. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

6. You'll be able to view deposits data on the table.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

* Deposits will be shown with different status,
  * **PROCESSING** – Transaction was initiated successfully and waiting for you to make deposit
  * **SUCCESS** – Transaction was successfully and funds are in your balance
  * **FAILED** – Transaction failed

### View single deposit

1. In the deposits table, locate the a withdraw you wish to view. On the far right of its row, click the "View" button.

<Frame>
  <img alt="View Deposit" />
</Frame>

2. A drawer will appear on the right, showcasing detailed information about the selected deposit

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. You are able to copy ID and other data from details drawer for this transaction. For sharing it with clickpesa support team in case transaction went wrong or other usage.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export deposits

1. In the Withdraws Table, locate and click the "Export" button at the far right. This will take you to [deposit export page](/dashboard/data-export/deposit-export).

<Frame>
  <img alt="Export Deposits 1" />
</Frame>

## Common Use Cases

1. You use this feature mainly if you want to view your transaction details for deposits
2. You can use this feature when you want to export the deposit transaction and export it to another system.
3. In case you want to payout but you don't have enough funds on your balance, you can deposit enough funds to make the payout.


# Withdrawal
Source: https://docs.clickpesa.com/dashboard/account/withdraws

This guide will walk you through the process of doing a withdrawal. With withdrawal you can withdraw any TZS or USD balance. You can use withdrawal to...

## Introduction

This guide will walk you through the process of doing a withdrawal. With withdrawal you can withdraw any TZS or USD balance. You can use withdrawal to withdraw the fund the your [settlement account](/dashboard/settings/disbursement) that is setup.

Oversees your withdraw transactions is a crucial aspect of any business, and being able to track and review payouts is fundamental to maintaining transparency and control over your finances. Our dashboard offers a streamlined and user-friendly interface to view all your withdraws and even export this data for further analysis or record-keeping.

## How to use withdrawal

### How to configure

In order to be able to withdraw, you need to add your bank account. [Learn how to add bank account here.](/dashboard/settings/disbursement)

### How to do a withdrawal

1. From your dashboard, navigate to the left-hand side and select "Account".

<Frame>
  <img alt="Withdraws 5" />
</Frame>

2. Click the “Withdraw” button at the top right corner of the transactions page. You can only withdraw when there is a positive balance.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. If you haven’t set your settlement account yet, you will be prompted with this alert and a button to take you to the settings to add your [settlement account](/dashboard/settings/disbursement).

<Frame>
  <img alt="Withdrawal Add Settlement Account" />
</Frame>

4. On the right side of your screen, a drawer with title 'Withdraw' will appear. Under the 'Amount' field, choose the currency you wish to withdraw from. Ensure you enter the amount you want to take out of your account. Then decide which settlement type you would like to use for the settlement. You can choose from ACH (EFT) and RTGS (TISS), below is an explanation of both settlement type:
   1. **ACH (EFT)**\
      The withdrawal is settled within 1 working day. Weekend days and holidays are not included.
   2. **RTGS (TISS)**\
      The withdrawal is settled within the same day. Weekend days and holidays are not included.
5. Once everything is filled in, click "Withdraw" button on the right bottom.

<Frame>
  <img alt="Screenshot 2023 10 31 At 18.35.42" />
</Frame>

6. You will see a summary of the transaction you are about to make once you are sure of the details click the “Withdraw” button again to complete the withdraw process. You will see a success notification, you have completed the withdraw process wait for your funds to arrive.

<Frame>
  <img alt="Screenshot 2023 10 31 At 18.36.42" />
</Frame>

7. OTP will be sent out to your registered phone number. You will be prompted with OTP field to confirm the payout with options to resend if OTP was not received on your phone number.
8. Once withdraw is successful initiated you will receive [notification](/dashboard/notifications) via email or merchant.

**Note**: If your settlement bank account is **GT Bank**, the withdraw will be free of charge

### View all withdraws

1. From your dashboard, navigate to the left-hand side and select "Account" and the select Withdraws tab.

<Frame>
  <img alt="Withdraws 5" />
</Frame>

2. You will be able to filter withdraws summary and data by date, status, currency and searching by reference, channel channel provider, account number or account name.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the page you should be able to see summary with withdraws count and value
4. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

6. You'll also be presented with a transactions table displaying all withdraws.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

* Withdraws will be shown with different status,
  * **PROCESSING** – Transaction was initiated successfully and funds are on the way
  * **SUCCESS** – Transaction was successfully, Funds will be settled to your [settlement account](/dashboard/settings/disbursement)
  * **FAILED** – Transaction failed
  * **REFUNDED** – Transaction was refunded before it was successful.
  * **REVERSED** – Transaction was reversed after it was successful.

### View single withdraw

1. In the withdraws table, locate the a withdraw you wish to view. On the far right of its row, click the "View" button.

<Frame>
  <img alt="View Withdraw 3" />
</Frame>

2. A drawer will appear on the right, showcasing detailed information about the selected withdraw

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

**Note**: If withdraw was from asset with currency different from currency in your Bank account, the withdraw details will contain exchange information as displayed on the image above.
3\. You are able to copy ID and other data from details drawer for this transaction. For sharing it with clickpesa support team in case transaction went wrong or other usage.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export withdraws

1. In the Withdraws Table, locate and click the "Export" button at the far right. This will take to the [withdraw export page](/dashboard/data-export/withdraw-export).

<Frame>
  <img alt="Export Withdraws 3" />
</Frame>

## **Common Use Cases**

1. You use this feature mainly if you want to view your transaction details for withdraws
2. You can use this feature when you want to export the withdraw transaction and export it to another system

## **Frequently Asked Questions (FAQ)**

1. **Is it possible to export withdraw transaction data from the ClickPesa Merchant Dashboard to another system?**\
   Yes, you can export all the transaction data from ClickPesa Merchant Dashboard and then import it manually within the other system if they allow for data import.
2. **Which file formats can data be exported from the ClickPesa Merchant Dashboard?**\
   ClickPesa Merchant Dashboard allows you to export data in Excel format.
3. **What is the difference between payouts and withdraws?**\
   Payouts are transfers to third parties and withdraws are transfers to your own bank account.
4. **How long does it take before withdrawal is received in my bank account?**\
   This depends on the selected Transfer type, if selected transfer type is ACH funds will be received in 1 working day and for RTGS funds will be received instant.
5. **I did a withdrawal but the transaction is not received after T+1 working days, what do I do?**\
   Contact [customer sup](https://clickpesa.com/contact-us/)[/contact-us/](https://clickpesa.com/contact-us/)[port](https://clickpesa.com/contact-us/) with your [withdraw transaction reference](/dashboard/transactions/payouts) to find out


# Checkout Links
Source: https://docs.clickpesa.com/dashboard/checkout-links

View and manage hosted checkout links in the Merchant Dashboard

<Note>
  Learn what Checkout Links are in the [Hosted Checkout Overview](/checkout/checkout-overview). To generate links from your application, use the [Checkout Link API](/checkout/checkout-link-api). Activate the feature under [Collection settings](/dashboard/settings/collection#checkout-link-activation).
</Note>

The **Checkout Links** page lists all hosted checkout links associated with your account — whether created via the [Checkout Link API](/checkout/checkout-link-api), plugins, or other integrations.

## How to access

1. Log in to the [Merchant Dashboard](https://merchant.clickpesa.com).
2. Under **Collection** in the sidebar, select **Checkout Links**.

<Note>
  Checkout Links requires the `merchant_checkout_links` feature to be enabled for your account. Activate Checkout Link under **Settings → Collection** first.
</Note>

## What you can do

* **View all links** — see reference IDs, amounts, currencies, and status in a searchable table
* **Open a link** — click a row to view full link details
* **Monitor performance** — use summary charts for link count and total value (TZS and USD)
* **Filter and search** — filter by date range, status, and other fields

## Creating checkout links

Checkout links are created through your integration, not from this page directly:

* **[Checkout Link API](/checkout/checkout-link-api)** — generate links from your application
* **Plugins** — WooCommerce and other integrations that use Checkout Link

Payment Pages and E-Invoices generate their own checkout URLs automatically. See [Payment Pages](/dashboard/payment-pages) and [E-Invoice](/dashboard/e-invoice).

## Related

* [Checkout Link](/checkout/checkout-link) — use cases and activation
* [Payment Transactions](/dashboard/transactions/payments) — view payments received through checkout links


# Customers
Source: https://docs.clickpesa.com/dashboard/customers

Add customers and assign BillPay control numbers in the Merchant Dashboard

<Note>
  Learn about Customer BillPay control numbers in the [BillPay Overview](/bill-pay/bill-pay-overview).
</Note>

### Create customer

1. To add a new customer, navigate to the left-hand side of your ClickPesa Merchant Dashboard and select "Customers". You will be presented with a screen like the one shown below.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. On the page you should be able to see summary with all customers count and new customers (customers that were created today) count.
3. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. On the graph you will be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the Customers screen, click the "New Customer" button located in the top right corner to begin adding a new customer.

<Frame>
  <img alt="Customers Add New Customer" />
</Frame>

6. A drawer will appear with a "Create Customer" form. Here, you can enter essential details like the customer's Full Name and Email. Optionally, you can also provide additional information such as Phone Number, City/Region, and Country. Once filled out, click the "Save Customer" button to store the customer's details.

<Frame>
  <img alt="Customers Create Customer" />
</Frame>

### View all customers

To add a new customer, navigate to the left-hand side of your ClickPesa Merchant Dashboard and select "Customers". You'll be presented with a summary which shows the total number of customers and a customers table which shows all the customers list.

You will be able to sort by date or search by customer name, email, phone, city or country.

### View single customer

1. Locate the customer you wish to view in the customer's table. Then, at the far right of the customer's row in the "Action" column, click the "View" button to access that customer's information.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. Then you will be able to see details of your customer and a summary of all transactions under this customer.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On each customer page you will see **Customer Offline Reference** section which allows customers to make payments via offline methods. [Learn more here.](/bill-pay/customer-billpay-namba)

### Edit customer

1. From the individual customer view (as mentioned in the previous step), look to the top right corner of the customer information section. Click the "Edit Customer" button to modify the customer's details.

<Frame>
  <img alt="Customers Edit Customer" />
</Frame>

2. A drawer will slide out from the right side of the page displaying the selected customer's information fields. You can edit these details as needed. Once you've made the necessary changes, click the "Save Customer" button to store the updated information.

### View customer transactions, payment pages, invoices, and payment plans

To view a customer's payments, payment pages, invoices, and [Payment Plans](/crdb-direct-debit/payment-plans), open the individual customer view. Tabs show payments for that customer, related payment pages and invoices, and CRDB Direct Debit payment plans linked to the customer.

## Common Use Cases

1. You can use this feature to manage your customer transactions related information so that you do not have to add the information every time you want to send funds or receive funds from the customer


# Merchant Dashboard Overview
Source: https://docs.clickpesa.com/dashboard/dashboard-overview

Manage collections, payouts, transactions, and account settings from the ClickPesa Merchant Dashboard — no coding required

The **ClickPesa Merchant Dashboard** is your web-based control center for running payments and payouts day to day. Use it to collect money, send payouts, track transactions, export data, and configure your account — without writing code.

<Tip>
  New to ClickPesa? Start with [Get Started With ClickPesa](/home/onboarding) to register and complete KYC. After login, open **Get Started** in the dashboard sidebar — see [Get Started in the Dashboard](/dashboard/get-started).
</Tip>

## When To Use It

* **Account setup** — Follow the six-step [account setup checklist](/dashboard/setup-company-account): General, KYC, Collection, Disbursement, and Team settings.
* **No-code collections** — Create [Payment Pages](/dashboard/payment-pages), [E-Invoices](/dashboard/e-invoice), manage [Checkout Links](/dashboard/checkout-links), activate [TanQR/Lipa Namba](/tan-qr/lipa-namba-setup) and [BillPay](/dashboard/customers), or collect on a schedule with [CRDB Direct Debit Payment Plans](/crdb-direct-debit/payment-plans).
* **Manual payouts** — Send [single](/dashboard/disbursement/single-payout) or [bulk payouts](/dashboard/disbursement/bulk-payouts).
* **Operations** — View [payments](/dashboard/transactions/payments) and [payouts](/dashboard/transactions/payouts), check [balance](/dashboard/account/balance), and [export data](/dashboard/data-export/payment-export).
* **API integration** — Configure applications, API keys, and webhooks under [Developers settings](/dashboard/settings/developers).

Developers integrating via API should also see [Integration Overview](/home/integration-overview).

## How It Works

1. **Register and log in** — Create an account at [merchant.clickpesa.com](https://merchant.clickpesa.com/account-registration) and complete [KYC](/home/onboarding#step-2-complete-kyc).
2. **Set up your account** — Use [Get Started in the Dashboard](/dashboard/get-started) or the [six-step setup checklist](/dashboard/setup-company-account).
3. **Collect or disburse** — Use dashboard features or integrate via [Hosted Checkout](/checkout/checkout-overview), [BillPay](/bill-pay/bill-pay-overview), [TanQR/Lipa Namba](/tan-qr/tan-qr-overview), [Mobile USSD-PUSH API](/payment-api/mobile-money-payment-api/mobile-money-payment-api-overview), [Card API](/payment-api/card-payment-api/card-payment-api-overview), [Mobile Payouts API](/payout-api/mobile-money-payout-api/mobile-money-payout-api-overview), [Bank Payout API](/payout-api/bank-payout-api/bank-payout-api-overview), or [Lipa Namba Payout API](/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview).
4. **Monitor and export** — Track transactions, receive [notifications and account alerts](/dashboard/notifications), and export records for reconciliation.

## Learn More

<CardGroup>
  <Card title="Get Started in the Dashboard" icon="rocket" href="/dashboard/get-started">
    In-dashboard setup hub, payment options, and developer resources.
  </Card>

  <Card title="Set Up Your Account" icon="gear" href="/dashboard/setup-company-account">
    Six-step checklist: profile, KYC, collection, settlement, and team.
  </Card>

  <Card title="Collection" icon="money-bill" href="/dashboard/payment-pages">
    Payment Pages, E-Invoices, Checkout Links, and customers.
  </Card>

  <Card title="Payouts" icon="paper-plane" href="/dashboard/disbursement/single-payout">
    Send single or bulk payouts from the dashboard.
  </Card>

  <Card title="Transactions & Wallet" icon="chart-line" href="/dashboard/transactions/payments">
    View payments, payouts, balance, deposits, and withdraws.
  </Card>

  <Card title="Settings" icon="sliders" href="/dashboard/settings/general">
    General, collection, disbursement, team, KYC, developers, and security.
  </Card>
</CardGroup>


# Deposit Export
Source: https://docs.clickpesa.com/dashboard/data-export/deposit-export

This feature simplifies the process of exporting your deposits data exactly how you want it. We've already organized the data for you, so all you need to do...

## Introduction

This feature simplifies the process of exporting your deposits data exactly how you want it. We've already organized the data for you, so all you need to do is choose which data you want and export it to Excel or CSV.

In this guide, we'll walk you through how to filter your deposits data to find exactly what you're looking for. Then, we'll show you how to export that data into an Excel or CSV file. It's a straightforward way to get the information you need, hassle-free. Let's dive in and get started!

### Export deposits as CSV

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Deposits as CSV card.

<Frame>
  <img alt="Deposits Csv" />
</Frame>

3. You should land to page called Export Deposits as CSV, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status and date range to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called deposits.csv. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export deposits for excel

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Deposits for Excel card.

<Frame>
  <img alt="Deposits Xlsx" />
</Frame>

3. You should land to page called Export Deposits for Excel, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status and date range to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called deposits.xlsx. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use cases

1. Importing data into account systems or third parties systems.


# Payment Export
Source: https://docs.clickpesa.com/dashboard/data-export/payment-export

This feature simplifies the process of exporting your payments data exactly how you want it. We've already organized the data for you, so all you need to do...

## Introduction

This feature simplifies the process of exporting your payments data exactly how you want it. We've already organized the data for you, so all you need to do is choose which data you want and export it to Excel or CSV.

In this guide, we'll walk you through how to filter your payments data to find exactly what you're looking for. Then, we'll show you how to export that data into an Excel or CSV file. It's a straightforward way to get the information you need, hassle-free. Let's dive in and get started!

### Export payments as CSV

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Payments as CSV card.

<Frame>
  <img alt="Payments Csv" />
</Frame>

3. You should land to page called Export Payments as CSV, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range, payment channel to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called payments.csv. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export payments for excel

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Payments for Excel card.

<Frame>
  <img alt="Payments Xlsx" />
</Frame>

3. You should land to page called Export Payments for Excel, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range, payment channel to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called payments.xlsx. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use cases

1. Importing data into account systems or third parties systems.


# Payout Export
Source: https://docs.clickpesa.com/dashboard/data-export/payout-export

This feature simplifies the process of exporting your payouts data exactly how you want it. We've already organized the data for you, so all you need to do...

## Introduction

This feature simplifies the process of exporting your payouts data exactly how you want it. We've already organized the data for you, so all you need to do is choose which data you want and export it to Excel or CSV.

In this guide, we'll walk you through how to filter your payouts data to find exactly what you're looking for. Then, we'll show you how to export that data into an Excel or CSV file. It's a straightforward way to get the information you need, hassle-free. Let's dive in and get started!

### Export payouts as CSV

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Payouts as CSV card.

<Frame>
  <img alt="Payouts Csv 1" />
</Frame>

3. You should land to page called Export Payouts as CSV, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range, channel (**MOBILE MONEY**, **BANK TRANSFER**, **LIPA NAMBA**), and payout type to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called payouts.csv. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export payouts for excel

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Payouts for Excel card.

<Frame>
  <img alt="Payouts Xlsx" />
</Frame>

3. You should land to page called Export Payouts for Excel, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range, and channel (**MOBILE MONEY**, **BANK TRANSFER**, **LIPA NAMBA**) to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called payouts.xlsx. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use cases

1. Importing data into account systems or third parties systems.


# Quickbooks
Source: https://docs.clickpesa.com/dashboard/data-export/quickbooks

This feature simplifies the process of exporting your transactions for   quickbooks  . We've already organized the data for you, so all you need to do is...

## Introduction

This feature simplifies the process of exporting your transactions for [**quickbooks**](https://quickbooks.intuit.com/global/). We've already organized the data for you, so all you need to do is choose which data and fields you want and export.

In this guide, we'll walk you through how to filter your transactions to find exactly what you're looking for. Then, we'll show you how to export that data for quickbooks.

## How to use this feature

### How to access this feature

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com/) account.
2. Navigate to Data Export and select Export Transactions for Quickbooks card.

<Frame>
  <img alt="Quickbooks 1" />
</Frame>

3. Once clicked it will open a popup / modal with fields to select for export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Configure data to export

1. Select Transaction type, we have 4 different transaction types in our platform, "PAYOUT", "PAYMENT", "DEPOSIT" and "WITHDRAW". Selecting atleast one of this will add options to other selectors as well grouped by selected transaction types.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. Other selections shown on the modal are date format, this will let you select date format that will be suitable for how you have set your quickbooks account. other fields includes
   * Select Fields\
     This will allow you to select fields per transaction type. This fields will be added in record description in the order of selection ie. first selected field in transaction type will be added first and last will be added last, more explanation is on Description column on step 3.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

* Select Currency\
  Currently we support TZS and USD for payments and withdraws and only TZS for payouts and deposits. We allow selecting currency that you want their records for instance if in PAYMENT type you select TZS, only payments with TZS as settlement currency will return. By default if no currency is selected will return all transactions
* Select Status\
  You should be able to filter transaction by their status. For quickbooks we only support transactions that went through hence fewer status. for instance for DEPOSIT we only support SUCCESS, for PAYMENTS we support SETTLED, REFUNDED, REVERSED and REVERSED WITH CHARGES, for PAYOUT and WITHDRAW we support SUCCESS, REFUNDED and REVERSED.

  These status when selected will return only transactions with those status by transaction type. By default if no status is selected for a particular transaction type all transactions will be returned
* Select Channels\
  Channels field is also used for filtering data, each Transaction type has their own channels which was the medium for them to go through. Once channel is selected it will return transactions that belong to that channel. By default if none is selected it will return all transactions.
* Sort\
  You should be able to sort data by newest or oldest first when exporting data for Quickbooks.

3. Once you have selected your options and click Preview it will open a page with title "" and list of all transactions per your selection with five columns
   * **Description**\
     This will contain record name and all the fields you selected in the modal separated by " - ".\
     These record names are different per transaction type and transaction status.

     For instance you selected status, channel and channel provider in the fields of PAYOUT transaction type here is how description will look like,\
     "Payout - SUCCESS - MOBILE MONEY - TIGOPESA TANZANIA" in the order of selected fields. where "Payout" is the record name. Lipa Namba payouts appear as **Lipa Namba** in the channel field.\
     Here is the list of all names and description per transaction types

     1. PAYOUT\
        **Payout** = SUCCESS Payout\
        **Fee - Payout** = Payout fee\
        **Reversed Payout** = REVERSED Payout\
        **Refunded Payout** = REFUNDED Payout
     2. WITHDRAW\
        **Withdraw** = SUCCESS Withdraw\
        **Fee - Withdraw** = Withdraw fee\
        **Reversed Withdraw** = REVERSED Withdraw\
        **Refunded Withdraw** = REFUNDED Withdraw
     3. PAYMENT\
        **Payment** = SETTLED Payment\
        **Fee - Payment** = Fee incurred on SETTLED BILLPAY payments\
        **Reversed Payment** = REVERSED Payment\
        **Refunded Payment** = REFUNDED Payment\
        **Charge** = Charges for when reversing a payment incurred charges
     4. DEPOSIT

     * **Deposit** = SUCCESS Deposit
   * **Date**\
     This entails the time the record was created.
   * **Debit**\
     Money that went out from your ClickPesa balance.
   * **Credit**\
     Money that went in your ClickPesa balance.
   * Currency\
     Record currency.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. Once Export button is clicked it will download file called quickbooks.csv with four columns "Description", "Date", "Debit" and "Credit". Which is now ready to be imported in quickbooks system without any hassle.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

|                 |                 |
| --------------- | --------------- |
| Name            | Description     |
| Payout          | SUCCESS Payout  |
| Fee - Payout    | Payout Fee      |
| Reversed Payout | REFUNDED Payout |
| Refunded Payout | REVERSED Payout |

## Common Use cases [#](/dashboard/data-export/withdraw-export)

1. Importing data into quickbooks account system.


# Withdraw Export
Source: https://docs.clickpesa.com/dashboard/data-export/withdraw-export

This feature simplifies the process of exporting your withdrawal data exactly how you want it. We've already organized the data for you, so all you need to...

## Introduction

This feature simplifies the process of exporting your withdrawal data exactly how you want it. We've already organized the data for you, so all you need to do is choose which data you want and export it to Excel or CSV.

In this guide, we'll walk you through how to filter your withdrawal data to find exactly what you're looking for. Then, we'll show you how to export that data into an Excel or CSV file. It's a straightforward way to get the information you need, hassle-free. Let's dive in and get started!

### Export withdraws as CSV

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export Withdraws as CSV card.

<Frame>
  <img alt="Withdraws Csv" />
</Frame>

3. You should land to page called Export Withdraws as CSV, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range and currency to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called withdraws.csv. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Export payments for excel

1. Login to your [merchant.clickpesa.com](https://merchant.clickpesa.com) account.
2. Navigate to Data Export and select Export WIthdraws for Excel card.

<Frame>
  <img alt="Withdraws Xlsx" />
</Frame>

3. You should land to page called Export Withdraws for Excel, with filters (Status and date preselected) and table and button to export and button for More Exports options.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

4. You can use filters such as status, date range and currency to return the actual data you want to export.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. Upon clicking export browser will download a file called withdraws.xlsx. It will look like this.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use cases

1. Importing data into account systems or third parties systems.


# Bulk Payouts
Source: https://docs.clickpesa.com/dashboard/disbursement/bulk-payouts

Send payouts to multiple beneficiaries from the Merchant Dashboard

<Note>
  For programmatic payouts, see the [Mobile Payouts API](/payout-api/mobile-money-payout-api/mobile-money-payout-api-overview), [Bank Payout API](/payout-api/bank-payout-api/bank-payout-api-overview), or [Lipa Namba Payout API](/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview). Lipa Namba are not currently supported on Bulk Payouts.
</Note>

## How to send bulk payouts

### How to access and configure

### How to access

To access the bulk payout feature, visit [merchant.clickpesa.com](https://merchant.clickpesa.com/), login with your account and navigate to the "Bulk Payout" menu item.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

1. On the page you should be able to see summary with bulk payouts count and value and all payouts associated to batches count.
2. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to configure

**User Levels (optional)**

An admin has the ability to setup additional users with two type of users levels. There is the option to create admin (upload and access funds) and employee (upload and no access to funds) user level. Refer to the [team setting](/dashboard/settings/team).

**How to prepare payout file**

To use this feature, you have to create a file with the payout details following the field format below. Each field has its own requirements. [Download here our sample file](/images/knowledge-base/files/sample_file.csv), just remember to remove the example data and put in your payment details. You can add the payout data in the file on your computer using Excel (for Windows) or Numbers (for Apple). Once you are done, save or export this file as a CSV or Excel format on your computer ready to upload.

| Fields                        | Explanation                                                                                                                                                                                                                                                                    | Example                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| Recipient Name                | Name of the BANK ACCOUNT or MOBILE MONEY WALLET.                                                                                                                                                                                                                               | John Massawa                                       |
| Receiving Channel             | BANK or MOBILE MONEY                                                                                                                                                                                                                                                           | MOBILE MONEY                                       |
| Receiving Channel Provider    | [BANK NAME](#bank-names) or [MOBILE MONEY PROVIDER NAME](#mobile-money-provider-names)                                                                                                                                                                                         | TIGO PESA                                          |
| Account Number                | Mobile Money Number (format 12 digits including 255 and no 0)                                                                                                                                                                                                                  | 255789101219                                       |
| Amount                        | **Mobile Money**  Minimum: 2,500 TZS  Maximum: 5,000,000 TZS   **Bank ACH** Minimum: 2,500 TZS Maximum: 20,000,000 TZS  **Bank RTGS** Minimum: 11,900 TZS Maximum: 1,000,000,000.00 TZS                                                                                        | 100,000                                            |
| Transfer Type                 | Only applicable for Bank Transfer                                                                                                                                                                                                                                              | ACH                                                |
| Note To Recipient (optional)  | Note to Recipient                                                                                                                                                                                                                                                              | This is the payout for gasoline usage 4 June 2023. |
| Recipient Contacts (optional) | Email or Phone Number (format 12 digits including 255 and no 0)                                                                                                                                                                                                                | 255789101219                                       |
| Language (optional)           | Language for this beneficiary notification only: `SWAHILI` or `ENGLISH` (see [Payout Notification Examples](#payout-notification-examples)). Overrides your [Settings → General](/dashboard/settings/general) default for this send. Leave blank to use the dashboard default. | SWAHILI                                            |

Note:

1. **ACH (EFT)**\
   The payout is settled within 1 working day. Weekend days and holidays are not included.
2. **RTGS (TISS)**\
   The payout is settled within the same day. Weekend days and holidays are not included

If the bank account name is not correct, the payout will bounce, make sure you enter the correct account name.

These are the mobile money receiving channels we support, make sure to use this names mentioned in this list when creating your payout file.

| Mobile Money Provider Names |
| --------------------------- |
| AIRTEL MONEY                |
| EZY PESA                    |
| HALOPESA                    |
| MPESA                       |
| TIGO PESA                   |

This are the bank receiving channels we support, make sure to use this names mentioned in this list when creating your payout file.

| Bank Names                                 |
| ------------------------------------------ |
| ABSA BANK TANZANIA LIMITED                 |
| AKIBA COMMERCIAL BANK PLC                  |
| AMANA BANK LIMITED                         |
| BANCABC TANZANIA LIMITED                   |
| BANK OF AFRICA TANZANIA LIMITED            |
| BANK OF BARODA TANZANIA LIMITED            |
| BANK OF INDIA TANZANIA LIMITED             |
| CANARA BANK TANZANIA LIMITED               |
| CHINA DASHENG BANK LIMITED                 |
| CITIBANK TANZANIA LIMITED                  |
| CRDB BANK PLC                              |
| DCB COMMERCIAL BANK PLC                    |
| DTB TANZANIA PUBLIC LIMITED COMPANY        |
| ECOBANK TANZANIA LIMITED                   |
| EQUITY BANK TANZANIA LIMITED               |
| EXIM BANK TANZANIA LIMITED                 |
| GT BANK TANZANIA LIMITED                   |
| HABIB AFRICAN BANK LIMITED                 |
| I\&M BANK TANZANIA LIMITED                 |
| INTERNATIONAL COMMERCIAL BANK TANZANIA LTD |
| KCB BANK TANZANIA LIMITED                  |
| MKOMBOZI COMMERCIAL BANK PLC               |
| MWALIMU COMMERCIAL BANK PLC                |
| MWANGA HAKIKA BANK LTD                     |
| NBC LIMITED                                |
| NCBA BANK TANZANIA LIMITED                 |
| NMB BANK PLC                               |
| PEOPLES BANK OF ZANZIBAR LIMITED           |
| STANBIC BANK TANZANIA LTD                  |
| STANDARD CHARTERED BANK TANZANIA LTD       |
| TANZANIA COMMERCIAL BANK PLC               |
| UBA TANZANIA LIMITED                       |

### Notifications

Notifications are sent to the beneficiary in your [default language](/dashboard/settings/general), unless the payout row includes **Language**. That value is used only for that beneficiary notification and does not change your saved Settings → General default.

Once payout is successfully initiated to beneficiary you will receive notification in your merchant dashboard and email.

If payout fails for any reason and is refunded or reversed you will receive notification via your merchant dashboard and email. Learn more about notifications [here](/dashboard/notifications). If payout was created with customer contact details, they will also receive notification when payout is reversed.

### Fees and fee configurations

#### Fee bearer

You can set up who is the **fee bearer** between you and recipient or both on [Payout Settings](/dashboard/settings/disbursement).

What will this mean on the payouts?

1. If fee is on you, the fee will be added on top of the amount you've entered and the recipient will receive the exact amount you provided (You will be charged the whole fee)
2. If fee is on beneficiary, The fee will be deducted from the amount you've entered and the recipient will receive amount minus fee (Recipient will be charged the whole fee)
3. If fee is on both, Half of the fee will be added on top of the amount you've entered (you will be charged half of the fee). Recipient will receive Amount minus half of the fee (recipient will be charged half of the fee).

[Click here](https://clickpesa.com/payment-gateway/pricing/) to learn more about how we charge fees

#### Free GTBank Transfer

1. When paying out to customer using GTBank, its free of charge, fee will be 0

### How to use bulk payout

1. **Create new batch payout**\
   To create a bulk payout click the “Create New Batch” button.

<Frame>
  <img alt="Bulk Payouts Create New Batch Button" />
</Frame>

2. **Upload payout file**\
   You will be taken to the Create Bulk Payout page, on this page you can click on the “Upload your file here” section. This will prompted to select a file, go to the correct folder on your computer where you saved the payout file, select the payout file and upload the payout file. Find explanation [here](#prepare-payout-file) how to prepare your payout file.

<Frame>
  <img alt="Bulk Payouts Create Batch Payout" />
</Frame>

3. **Verification: Field Match**\
   The first verification step ensure that columns in your payout file (called Incoming Fields) match our system's columns (Destination Fields). If your column names are different or slightly off, our system may not understand them. This step lets you fix any mismatches. Check the preview of your data to make sure everything lines up. Once it looks correct, click the “continue” button.
4. **Verification: Data Check**\
   The second verification step, ensure that your payout file's data is accurate and formatted correctly. If something is off, like the receiving channels are named correctly as per this [overview](#payment-channels), the row highlights red. To fix it, click the pencil icon beside the row. After making corrections in the correct manner, the row turns green; click the save icon then. If there are issues with the minimum or maximum amount, adjust those too. When all rows are green, you will see the total amount on top, including fees, for the payout.
5. **Balance: Top-up and Payout**\
   Once the payout is green, based on your balance, you have two choices:
   1. **Save Draft and Top-up (Ignore when enough balance) I**f your balance is not sufficient for the payout, the "Confirm and Payout" button will be disabled. In addition a message will display showing your current balance and the exact amount you are short for doing the batch payout. To address this, click on the top-up option in the highlighted message to do a top-up.

<Frame>
  <img alt="Bulk Upload" />
</Frame>

It opens a drawer, in that drawer select the bank deposit option.

<Frame>
  <img alt="Bulk Payouts Top Up" />
</Frame>

Instruction on how to top up using bank will be provided and you can use these instructions to top up your balance, once your deposit is done you can click on the “Done” button.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. **Confirm and Payout (Enough balance)** When there is enough balance funds to do the batch payout click on the button “Confirm and Payout”. The status of the batch payout and transaction will change to “processing” and the payout will happen accordingly by end of the day.
3. OTP will be sent to your registered phone number and you will be prompted with OTP field for security check before confirming the batch.
4. Once payouts are successful initiated you will receive [notification](/dashboard/notifications) via email or your dashboard.
5. Ability to verify mobile account names before paying out\
   When paying out to mobile, you will be able verify account names. After uploading your batch, you will find a verify button under account number on Mobile payouts which when clicked it will return account name which you will be able to compare with the name you submitted.

<Frame>
  <img alt="Bulk Upload Name Check" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

This is important feature as it helps reduce human errors especially when you enter a wrong number.

**Note**: Its currently supported only on **Mixx By Yas** (`TIGOPESA`) and **AIRTELMONEY** Mobile Payouts Only
6\. **View Single Batch**\
This page contains information about a single payout such as status, total amount and fees. It also includes all payout transaction of that particular batch.
7\. **View All Batches**\
This page contains an overview of all the generated batches.

## **Common Use Cases**

1. Example of a **Manufacturing Company** using the bulk payouts feature\
   “*We are a 24 employees manufacturing business located just outside the city. We deal with many outgoing transaction on weekly basis. Our banking branch is in the city. We still pay out our staff manually because our bank does not support mobile money. We asked the MNOs for a bulk payment solution last year but that was time consuming. The bulk payout feature covers both, it sends funds to bank account and mobile wallets. It also enables us to stay in our office and use a good portal*“
2. Example of a **Microfinance Company** using the bulk payouts feature\
   *“We have a bank account setup that we use to disburse a loan to another bank account or mobile wallet. We use to attach all transactions in those bank accounts manually to the right customer and loan within our loan management system, which took a lot of time and it is hard to keep an overview. With the bulk payout feature this happens automatically and in a controlled manner”*

## **Frequently Asked Questions (FAQ)**

1. **What if the available funds in my balance are not enough?**\
   If the balance is not sufficient, the "Confirm and Payout" button is disabled. You will be given provided with a message that shows your current balance and the balance you are short. You need to top-up your balance using the bank deposit option, once bank transfer is received the new balance will reflect and you are ready to complete the bulk payout.
2. **How long does it take before the deposit appear in my balance once I have done the bank transfer?**\
   When a bank transfer is done to top-up your balance, it takes a maximum of 24 hours to reflect in your balance.
3. **What if the recipient bank name or bank number is incorrect and I already sent out the funds?** When payout details are incorrect the payout will bounce and the funds will be returned to your balance. Do note this takes a couple of days, therefore always make sure that the payout details such as recipient bank or mobile money wallet name and recipient bank and mobile money wallet number are correct and match
4. **What if the recipient mobile money wallet name or mobile money wallet number is incorrect and I already sent out the funds?**\
   When payout details are incorrect the payout will bounce and the funds will be returned to your balance. Do note this takes a couple of days, therefor always make sure that the payout details such as recipient bank or mobile money wallet name and recipient bank and mobile money wallet number are correct and match.
5. **Shall my organization have an account as an user or should our customers have this?**\
   Your organization requires an account under ClickPesa to use bulk payouts, your recipients or customer do not need a ClickPesa account. ClickPesa disburses to all existing bank accounts and mobile money wallets and not to other ClickPesa accounts.
6. **Can the payment made via ClickPesa be used as evidence of payment in case of a dispute, let's say someone denies receiving the payment form?**\
   Yes, the transaction records can be used as evidence.
7. **We have a bank account with CRDB, and we want to disburse a funds to a recipeint, the command to make a disbursement, is that done through the CRDB or does ClickPesa just track the record of that transaction?**\
   The funds have to be send from your bank account to your balance within your ClickPesa account by doing a top-up. The disbursement than takes place within your ClickPesa account whereby your balance in your ClickPesa account is used to payout to the recipients specified bank accounts or mobile wallets.
8. **Does this work with other systems?**\
   Yes, users can contact ClickPesa for integration possibilities.
9. **How much per transaction are you charging?**\
   Transaction charges are not provided in the explanation. Users should consult ClickPesa's fee structure or contact their support for detailed information.
10. **How do the funds move during disbursement from our organization bank accounts to customers' accounts?**\
    The funds have to be send from your bank account to your balance within your ClickPesa account by doing a top-up. The disbursement than takes place within your ClickPesa account whereby your balance in your ClickPesa account is used to payout to the recipients specified bank accounts or mobile wallets.
11. **How is the process in case they make a wrong payment?**\
    When payout details are incorrect the payout will bounce and the funds will be returned to your balance. Do note this takes a couple of days, therefore always make sure that the payout details such as recipient bank or mobile money wallet name and recipient bank and mobile money wallet number are correct and match.
12. **When bulk payment is confirmed, the transaction's status is PROCESSING, do receivers receive any notification that the transfer was initiated to keep track of the initiation time?**\
    No, the recipient only received a notification when the funds are received in their bank account or mobile wallet.
13. **When a transaction is FAILED, how does a receiver know that the transaction has failed?**\
    You are informed via your ClickPesa account that a transaction failed and you have to inform the receiver accordingly.
14. **By using ClickPesa can I be able to see the amount I disbursed and to who?**\
    Yes, users can view detail under "View All Batches" and "View Single Batch", including amounts and recipients. Also each payout appears under transaction, whereby there is the option to export data.
15. **Can ClickPesa be able to top up my account, in case I need to disburse to someone and I do not have enough balance? ie. like Songesha does.?**\
    ClickPesa does not automatically top-up like "Songesha". You have to make sure your balance is sufficient using the "Top-up" option.
16. **What happens in case I make a mistake and pay to the wrong number using ClickPesa?**\
    When payout details are incorrect the payout will bounce and the funds will be returned to your balance. Do note this takes a couple of days, therefore always make sure that the payout details such as recipient bank or mobile money wallet name and recipient bank and mobile money wallet number are correct and match.
17. **Do my customers require to use ClickPesa as well when using ClickPesa to do disbursement?** Your customers do not need a ClickPesa account as ClickPesa is a not wallet. We payout to existing bank accounts and mobile money wallets.


# Single Payout
Source: https://docs.clickpesa.com/dashboard/disbursement/single-payout

Send a payout to one beneficiary from the Merchant Dashboard

<Note>
  For programmatic payouts, see the [Mobile Payouts API](/payout-api/mobile-money-payout-api/mobile-money-payout-api-overview), [Bank Payout API](/payout-api/bank-payout-api/bank-payout-api-overview), or [Lipa Namba Payout API](/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview).
</Note>

## How to send a single payout

### How to Access and Configure

To access the bulk payout feature, visit [merchant.clickpesa.com](https://merchant.clickpesa.com/), login with your account and navigate to the "Payout" menu item.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

In order to be able to make a single payout make sure you have enough balance on your account.

**Initiating a Single Payout**

On a Payout page, A 'Create Payout\` button will appear on top right conner. Upon clicking it, a drawer will open with one field to fill, 'Send Via' which allows you to select between BANK, MOBILE MONEY, or Lipa Namba.

<Frame>
  <img alt="Image 9 1024x69" />
</Frame>

<Frame>
  <img alt="Image 11 1024x616" />
</Frame>

Selecting BANK, MOBILE MONEY, or Lipa Namba, will show other fields related to selected option explained below.

**What are the payout details?**

The following are the fields you will find when doing single payout for **BANK** channel

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

| Fields            | Explanation                                                                                                                 | Example            |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Receiving Channel | BANK                                                                                                                        | BANK               |
| Amount            | **Bank ACH** Minimum: 2,500 TZS  Maximum: 20,000,000 TZS   **Bank RTGS** Minimum: 11,900 TZS  Maximum: 1,000,000,000.00 TZS | 100,000 TZS        |
| Transfer Type     | ACH or RTGS                                                                                                                 | ACH                |
| Bank Name         | [BANK NAME](#bank-names)                                                                                                    | AMANA BANK LIMITED |
| Account Name      | Name of the BANK ACCOUNT                                                                                                    | John Doe           |
| Account Number    |                                                                                                                             | 0123001298647      |

Note:

1. **ACH (EFT)**\
   The payout is settled within 1 working day. Weekend days and holidays are not included.
2. **RTGS (TISS)**\
   The payout is settled within the same day. Weekend days and holidays are not included

If the bank account name is not correct, the payout will bounce and reserve without fees, make always sure you enter the correct account name.

After filling in those details, there will be an option or a button to add note to recipient. This note includes **Mobile Number**, **Email** and **Message** and they are optional. Filling in these fields will ensure Recipient receives notification via Email or SMS upon successfully payout.

The following are the fields you will find when doing single payout for **MOBILE MONEY** channel

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

| Fields                      | Explanation                                                                                    | Example      |
| --------------------------- | ---------------------------------------------------------------------------------------------- | ------------ |
| Receiving Channel           | BANK                                                                                           | BANK         |
| Amount                      | **Mobile Money** Minimum: 2,500 TZS  Maximum: 5,000,000.00 TZS                                 | 100,000 TZS  |
| Mobile Network Name         | [MOBILE MONEY PROVIDER NAME](/dashboard/disbursement/bulk-payouts#mobile-money-provider-names) | TIGO PESA    |
| Mobile Network Account Name | Name of the MOBILE MONEY WALLET                                                                | John Doe     |
| Account Number              | Phone Number (format 12 digits including 255 and no 0)                                         | 255789101219 |

After filling in those details, there will be an option or a button to add note to recipient. This note includes **Email** and **Message** and they are optional. Filling in these fields will ensure Recipient receives notification via Email or SMS upon successfully payout.

The following are the fields you will find when doing single payout for **Lipa Namba**

| Fields            | Explanation                                                  | Example        |
| ----------------- | ------------------------------------------------------------ | -------------- |
| Receiving Channel | Lipa Namba                                                   | Lipa Namba     |
| Amount            | Send from TZS or USD. The recipient always receives TZS.     | 100,000 TZS    |
| Provider          | Lipa Namba provider                                          | Vodacom M-Pesa |
| Lipa Namba        | The Lipa Namba number                                        | 123456         |
| Account Name      | Filled by **Verify Name**. Required before you can continue. | JOHN DOE       |

Click **Verify Name** after entering the Lipa Namba and provider. The beneficiary name is required — you cannot type it in.

You can send from a TZS or USD balance. The recipient always receives TZS.

After filling in those details, there will be an option or a button to add note to recipient. This note includes **Email** and **Message** and they are optional. Filling in these fields will ensure Recipient receives notification via Email or SMS upon successfully payout.

**Note**: The notification will be delivered to recipient will be delivered using default language you have set on [General settings](/dashboard/settings/general).

**Note**: Some mobile money number have a limit of 3,000,000 TZS which if you enter amount greater than this, it will cause transaction to bounce.

These are the mobile money receiving channels we support, make sure to use this names mentioned in this list when creating your payout file.

| Mobile Money Provider Names |
| --------------------------- |
| AIRTEL MONEY                |
| EZY PESA                    |
| HALOPESA                    |
| MPESA                       |
| TIGO PESA                   |

These are the bank receiving channels we support, make sure to use this names mentioned in this list when creating your payout file.

| Bank Names                                 |
| ------------------------------------------ |
| ABSA BANK TANZANIA LIMITED                 |
| AKIBA COMMERCIAL BANK PLC                  |
| AMANA BANK LIMITED                         |
| BANCABC TANZANIA LIMITED                   |
| BANK OF AFRICA TANZANIA LIMITED            |
| BANK OF BARODA TANZANIA LIMITED            |
| BANK OF INDIA TANZANIA LIMITED             |
| CANARA BANK TANZANIA LIMITED               |
| CHINA DASHENG BANK LIMITED                 |
| CITIBANK TANZANIA LIMITED                  |
| CRDB BANK PLC                              |
| DCB COMMERCIAL BANK PLC                    |
| DTB TANZANIA PUBLIC LIMITED COMPANY        |
| ECOBANK TANZANIA LIMITED                   |
| EQUITY BANK TANZANIA LIMITED               |
| EXIM BANK TANZANIA LIMITED                 |
| GT BANK TANZANIA LIMITED                   |
| HABIB AFRICAN BANK LIMITED                 |
| I\&M BANK TANZANIA LIMITED                 |
| INTERNATIONAL COMMERCIAL BANK TANZANIA LTD |
| KCB BANK TANZANIA LIMITED                  |
| MKOMBOZI COMMERCIAL BANK PLC               |
| MWALIMU COMMERCIAL BANK PLC                |
| MWANGA HAKIKA BANK LTD                     |
| NBC LIMITED                                |
| NCBA BANK TANZANIA LIMITED                 |
| NMB BANK PLC                               |
| PEOPLES BANK OF ZANZIBAR LIMITED           |
| STANBIC BANK TANZANIA LTD                  |
| STANDARD CHARTERED BANK TANZANIA LTD       |
| TANZANIA COMMERCIAL BANK PLC               |
| UBA TANZANIA LIMITED                       |

### Notifications

Notifications are sent to beneficiary when payout is initiated using merchant default language which can be set [here](/dashboard/settings/general).

Once payout is successfully initiated to beneficiary you will receive notification in your merchant dashboard and email.

If payout fails for any reason and is refunded or reversed you will receive notification via your merchant dashboard and email. Learn more about notifications [here](/dashboard/notifications). If payout was created with customer contact details, they will also receive notification when payout is reversed.

### Fees and fee configurations

#### Fee bearer

You can set up who is the **fee bearer** between you and recipient or both on [Payout Settings](/dashboard/settings/disbursement).

What will this mean on the payouts?

1. If fee is on you, the fee will be added on top of the amount you've entered and the recipient will receive the exact amount you provided (You will be charged the whole fee)
2. If fee is on beneficiary, The fee will be deducted from the amount you've entered and the recipient will receive amount minus fee (Recipient will be charged the whole fee)
3. If fee is on both, Half of the fee will be added on top of the amount you've entered (you will be charged half of the fee). Recipient will receive Amount minus half of the fee (recipient will be charged half of the fee).

[Click here](https://clickpesa.com/payment-gateway/pricing/) to learn more about how we charge fees

#### Free GTBank Transfer

1. When paying out to customer using GTBank, its free of charge, fee will be 0

### How to create single payout

1. On a Payout page, A 'Create Payout\` button will appear on top right conner. Upon clicking it, a drawer will open with one field to fill, 'Send Via' which allows you to select between BANK, MOBILE MONEY, or Lipa Namba.
2. Fill in details per method selected. Find explanation [here](#payout-details) on what details to fill on those fields

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. Click Next Button to see the summary of the details before submitting them.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

On the summary step, you can use **Save Beneficiary Details** to store this recipient for later. On the next payout, choose a saved beneficiary to fill in the details automatically. Works for **Mobile Money**, **Bank Transfer**, and **Lipa Namba**. Saving a Lipa Namba beneficiary requires **Verify Name**.

4. If everything is correct, Click Payout button to initiate the payout.
5. OTP will be sent out to your registered phone number. You will be prompted with OTP field to confirm the payout with options to resend if OTP was not received on your phone number.

<Frame>
  <img alt="Chrome Capture 2024 5 31 1" />
</Frame>

6. Once payout is successful initiated you will receive [notification](/dashboard/notifications) via email or your dashboard.

### Ability to verify mobile account names before paying out

When paying out to mobile, you will be able verify account names. On step 2 after entering details you will find a verify button under account number which when clicked it will return account name which you will be able to compare with the name you submitted.\
This is important feature as it helps reduce human errors especially when you enter a wrong number.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

**Note**: Its currently supported only on **Mixx By Yas** (`TIGOPESA`) and **AIRTELMONEY** Mobile Payouts Only

### Ability to verify Lipa Namba names before paying out

When paying out to a Lipa Namba, click **Verify Name** after you enter the number and provider. The name is required before you can continue.

### How to view single payouts

1. On a Payout page, it contains the summary and table of all single payouts.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. You will be able to filter payouts summary and data by date, status, channels (**MOBILE MONEY**, **BANK TRANSFER**, **LIPA NAMBA**), and searching by reference, account name, account number or Lipa Namba, channel, or channel provider.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the page you should be able to see summary with payouts count and value
4. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

6. You will also be able to sort payouts in the table by amount, date and fee

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

7. To view single payout,
   * In the payouts table, locate the payout you wish to view. On the far right of its row, click the “View” button.

<Frame>
  <img alt="View Payout 5" />
</Frame>

* A drawer will appear on the right, showcasing detailed information about the selected payout.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

8. You are able to copy ID and account number data from details drawer for this payout. For sharing it with clickpesa support team in case payout went wrong or sharing it with your customers.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

9. To export payouts,
   * In the Payouts Table, locate and click the “Export” button at the far right. this will take you to the [payout export page](/dashboard/data-export/payout-export).

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## **Common Use Cases**

Single payouts are ideal for various scenarios, such as:

* Paying a one-time bonus to an employee.
* Disbursing funds to a specific supplier or contractor.
* Making individual payments to clients or partners on an as-needed basis.

## **Frequently Asked Questions (FAQ)**

1. **Can I use ClickPesa for single payouts if my customers do not have ClickPesa accounts?**
   * Yes, your customers or recipients do not need ClickPesa accounts to receive single payouts. ClickPesa disburses to existing bank accounts, mobile money wallets, and Lipa Namba.
2. **What happens if I make a mistake and send a payment to the wrong recipient using ClickPesa's Single Payout feature?**
   * It's important to ensure that recipient details are accurate when initiating a single payout. If the details are incorrect, the transaction may fail, and the funds will be returned to your ClickPesa account. This process may take a few days.
3. **Can I track the details of the single payouts I've made using ClickPesa?**
   * Yes, you can view transaction details, including amounts and recipients, under the "Transaction" section of your ClickPesa account. There is also an option to export transaction data for your records.
4. Can A Team member initiate or approve a payout?
   * Yes, we support assigning payout roles to team members for initiating or approving single payouts. [Learn More](/dashboard/settings/disbursement)


# E-Invoice
Source: https://docs.clickpesa.com/dashboard/e-invoice

Create and manage invoices in the Merchant Dashboard

<Note>
  Learn how E-Invoices connect to hosted checkout in the [Hosted Checkout Overview](/checkout/checkout-overview).
</Note>

## How to Use E-Invoice

### How to access invoices

To access the Invoice feature, visit [merchant.clickpesa.com](https://merchant.clickpesa.com/), login and navigate to the "Invoices" menu item.

<Frame>
  <img alt="Invoices 1 1024x562" />
</Frame>

1. On the page you should be able to see summary with invoices count, value and total payments count associated with invoices.
2. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to create an invoice

To fully utilize this feature, refer to the [Payment methods documentation.](/dashboard/settings/collection)

1. Click the "Create New Invoice" button on the Invoices tab.

<Frame>
  <img alt="E Invoice New Invoice" />
</Frame>

2. Fill in the following information about the invoice and submit

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

1. Invoice No.
2. Customer. If the customer is not existing, a new customer can be used to create customer following [this guide](/dashboard/customers).

<Frame>
  <img alt="E Invoice Select Customer" />
</Frame>

3. Date
4. Due Date
5. Items
   * Item Name
   * Description
   * Quantity
   * Amount

<Frame>
  <img alt="E Invoice Add Items" />
</Frame>

6. VAT

To add more items, use the add item button to add more fields

After all the information is filled in you can:

1. **Save as draft** (notification won’t be sent to customer)
2. **Create Pro Forma Invoice** (an email notification is automatically send to a customer)
   * A **Pro Forma Invoice** does not confirm a sale and payment. It acts like a proposal.
3. **Create Tax Invoice** (creates and mark invoice as paid)
   * **Tax Invoice** this confirms a sale and payment.

When creating a pro forma invoice, the following email is send to a customer

### How to share an invoice

1. Once an invoice is saved it will redirect to the created invoice page, where it will show summary and items of the created invoice.
2. Invoice exists in three statuses, **DRAFT**, **PENDIN**G, **PARTIAL PAID** and **PAID**
   * **DRAFT** means the invoice was created but was neither sent to customer nor paid.
   * **PENDING** means a pro forma invoice is sent to a customer but not yet paid.
   * **PAID** means the invoice was paid.
   * **PARTIAL PAID** means the invoice total payments amount is less than the invoice amount.
3. You have the option resend the e-invoice to the customer via email with a link to the e-invoice.
4. Reminders can be send to a customer if they fail to pay in time
5. All payments made on the e-invoice are visible to the organization.

### How to modify an invoice

1. Invoice can be edited, deleted or marked as paid, When viewing single **DRAFT** or **PENDING** invoice there are three actions, edit, delete and mark as paid
   1. E-invoice details can be updated with the latest invoice details
   2. E-invoice can be deleted if it is no longer required
   3. E-invoice can be marked as paid if customer has paid an invoice without using [Hosted Checkout](/checkout/checkout-page). For example a customer makes a payment using cash.
2. Editing a **PENDING** invoice will send a notification to customer notifying them of the new updates.
3. **PAID** invoice has only one action, delete.

### How to keep track of payments on e-invoice

1. On viewing **PAID** invoice it will also show payment history for the invoice.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use Cases

1. **Businesses:** Business owners can use the Invoices feature to bill their clients for products or services rendered, helping to maintain cash flow and financial organization.
2. **Freelancers:** Freelancers can create professional invoices for their clients, simplifying the process of requesting payment for their work.

## Frequently Asked Questions (FAQ)

1. **Is an e-invoice the same as a normal invoice?**\
   Yes, it is the exact same.
2. **Can I add my business bank account details to the invoice?**\
   There is no option to add your business bank account details. The invoice is connected to use bank transfer in the checkout. Once the funds are received by us we will settle those funds in the provided business bank account.
3. **During collection who gets charged, is it me or my customer?**\
   The customer is paying the charges when doing a payment depending on the payment method.
4. **My customers don’t have smartphones, how do they pay?**\
   The invoice can only be opened on a computer or smartphone as the invoice is web-based. For customers that don't have a computer or smartphone, a merchant can go to the invoice, choose NMB Bill Number (valid for 15 minutes) or Bank Deposit (valid for 7 days) and share these payment instructions and details manually with the customer. The customer can then do the payment accordingly.
5. **When a customer pays me do I get notifications?**\
   Currently notifications are not sent when a customer pays.
6. **Is ClickPesa limited to specific operators i.e. M-Pesa, Mixx By Yas, or just Artel Money?**\
   There are multiple methods to collect funds via ClickPesa such as Mixx By Yas, Airtel Money, Mpesa, Bank and Card. Learn more about all the [payment methods](/dashboard/settings/collection) that ClickPesa supports.


# Get Started in the Dashboard
Source: https://docs.clickpesa.com/dashboard/get-started

Use the in-dashboard Get Started hub to set up your account, enable payments, and find developer resources

After you register and log in, the Merchant Dashboard includes a **Get Started** section in the sidebar. It guides you through setup tasks and links to external documentation where needed.

Open it at [merchant.clickpesa.com/get-started](https://merchant.clickpesa.com/get-started).

## Setup guides

| Guide                           | What it covers                                                                                                                                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Set Up Your Account Quickly** | Six-step checklist: business profile, authorised person, KYC, payment methods, settlement account, and team. See [Set Up Your Company Account](/dashboard/setup-company-account). |
| **Enable Payment Options**      | Choose and activate collection methods (mobile money, cards, TanQR, and more). Links to [Collection settings](/dashboard/settings/collection).                                    |
| **Issue a New Invoice**         | Create your first e-invoice. See [E-Invoice](/dashboard/e-invoice).                                                                                                               |

## Developer resources

**Developer Resources** opens the in-dashboard integration hub at `/get-started/developers`. It tracks API setup progress and links to:

* [Integration Overview](/home/integration-overview)
* [API Integration Setup](/application/api-application-setup)
* [Webhooks](/home/webhooks)
* [API Explorer](/api-reference)

See [Developers settings](/dashboard/settings/developers) for applications, API keys, webhooks, and IP whitelisting.

## Finance and support

| Guide                        | What it covers                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| **For Finance & Accounting** | Export transactions and accounting workflows. See [Data Export](/dashboard/data-export/payment-export). |
| **Customer Support**         | Contact options and support resources.                                                                  |

## After setup

Once your account is configured, use the sidebar to collect payments ([Payment Pages](/dashboard/payment-pages), [E-Invoice](/dashboard/e-invoice), [Checkout Links](/dashboard/checkout-links)), send [payouts](/dashboard/disbursement/single-payout), and monitor [transactions](/dashboard/transactions/payments).


# Notifications
Source: https://docs.clickpesa.com/dashboard/notifications

Stay informed about payments, deposits, payouts, and withdrawals via email, in-app, and web notifications — plus account alerts in the dashboard

The Merchant Dashboard keeps you informed in two ways:

1. **Transaction notifications** — real-time updates about payments, deposits, and payouts (bell icon, email, and web)
2. **Account alerts** — banners at the top of relevant pages for setup, KYC, settlement, collection, and product updates

## Account alerts

Account alerts highlight actions that need your attention or share important product updates. They appear below the page title and breadcrumbs.

**What you can expect**

* **Relevant pages only:** Most alerts show where you can resolve them — for example collection setup on **Get Started** and **Settings → Collection**, settlement updates on account and payout pages, and developer product updates on the dashboard and **Settings → Developers**
* **Critical KYC limits:** If your pre-KYC transaction limit is reached, a restriction alert stays available across the dashboard until KYC is approved
* **Dismiss informational updates:** Product updates and similar messages can be dismissed after you’ve read them so they don’t keep reappearing
* **Collapse when needed:** You can temporarily hide or expand alerts on a page while you work

Account alerts are separate from the notification bell. Use [notification settings](#notification-settings) for payment, payout, and deposit preferences.

## Transaction notifications

Transaction notifications alert you to key account activity in real time. You can customize which transaction types and channels you receive alerts for.

**Notification categories**

1. **Payout** — payout initiated, refunded, or reversed
2. **Deposit** — deposit instructions and confirmations
3. **Local payment** — payments settled into your account
4. **CRDB Direct Debit mandates** — mandate requested, approved, rejected, or cancelled (see [Payment Plans](/crdb-direct-debit/payment-plans))

**Channels**

1. **Email** — sent to your registered email address
2. **In-app** — shown inside the Merchant Dashboard
3. **Web** — browser notifications when logged in (Safari support may vary)

## View notifications

<Steps>
  <Step title="Open notifications">
    Click the notification icon at the top right of the dashboard.

    <Frame>
      <img alt="Notification icon in Merchant Dashboard header" />
    </Frame>
  </Step>

  <Step title="Browse in-app notifications">
    View payment, payout, and deposit updates in the notifications panel.

    <Frame>
      <img alt="In-app notifications panel" />
    </Frame>
  </Step>

  <Step title="Open a notification">
    Click a notification to open its details in a drawer.

    <Frame>
      <img alt="Notification detail drawer" />
    </Frame>
  </Step>

  <Step title="Delete or mark as read">
    Use the three-dot menu on a notification to delete it or mark it read or unread.

    <Frame>
      <img alt="Notification delete and mark as read menu" />
    </Frame>
  </Step>
</Steps>

You also receive **email** notifications with the same information when email alerts are enabled.

If web notifications are enabled and you have granted permission for merchant.clickpesa.com, you can receive **web** notifications while logged in, even when the dashboard tab is in the background.

## Notification settings

<Steps>
  <Step title="Open notifications">
    Click the notification icon at the top right of the dashboard.

    <Frame>
      <img alt="Notification icon in Merchant Dashboard header" />
    </Frame>
  </Step>

  <Step title="Open settings">
    Click the settings icon at the bottom right of the notifications panel.

    <Frame>
      <img alt="Notification settings icon" />
    </Frame>
  </Step>

  <Step title="Customize preferences">
    Turn categories and channels on or off per your preference.

    <Frame>
      <img alt="Notification settings toggles" />
    </Frame>
  </Step>
</Steps>

## FAQ

**Can I receive notifications for only certain transaction types?**

Yes. Use notification settings to enable alerts for selected categories only.

**Are web notifications available when I am not on the dashboard?**

Web notifications require an active browser session where you are logged in and have granted permission.

**How do I stop email notifications?**

Turn off **Email** for the categories you do not want in notification settings.

**Do notification settings affect security alerts?**

Security-related alerts are mandatory and are not controlled by these preferences.

**Where do account alert banners appear?**

Most account alerts appear on the pages where you can act on them. Critical KYC limit alerts stay available across the dashboard until KYC is approved. Informational product updates can be dismissed after you read them.


# Payment Pages
Source: https://docs.clickpesa.com/dashboard/payment-pages

Create and manage payment pages in the Merchant Dashboard

<Note>
  Learn what Payment Pages are and how they fit hosted checkout in the [Hosted Checkout Overview](/checkout/checkout-overview).
</Note>

## How to use Payment Page

### How to access payment pages

To access the Payment Page feature, visit [merchant.clickpesa.com](https://merchant.clickpesa.com/), login and navigate to the "Payment Pages" menu item. On this page you find all the payment pages

<Frame>
  <img alt="Pages 1024x586" />
</Frame>

1. On the page you should be able to see summary with payment pages coun, value and total payments count associated with payment pages.
2. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to create a payment page

To fully use this feature, refer to the [Payment methods documentation](/dashboard/settings/collection).

1. Click the "Create New Page" button on the Payment Pages tab.

<Frame>
  <img alt="Create New Payment Page" />
</Frame>

2. Fill in the following information about the payment page and submit
   1. Name of the page
   2. Amount mode
      * **Fixed amount:** Set the amount and currency. Use this for tickets, products, or a set price. Whether the payer can change that amount is controlled by **Allow Amount Update** in [Collection settings](/dashboard/settings/collection)
      * **Open amount:** Choose the currency only. The payer enters how much to pay on checkout. Use this for donations and other contributions where the amount is not fixed
   3. Description (optional). Click **Add description** to open the description field as shown below.

<Frame>
  <img alt="Payment Page Description" />
</Frame>

<Frame>
  <img alt="Payment Page Add Page Description" />
</Frame>

4. Expiry date (optional). Click **Add expiry date** to set a last day the page can accept payments. After that date, the page stops accepting payments
5. Customer (optional). Click **Attach customer** to open the customer field as shown below.

<Frame>
  <img alt="Payment Payment Create" />
</Frame>

<Frame>
  <img alt="Payment Page Add New Customer" />
</Frame>

6. Image of the product or service (if applicable).
7. After you create the page, open it from the list to see a summary and all payments made for that page.

### How to share a payment page

1. Open the payment page. Under **Actions**, you can:
   * **Open Page** — open the hosted checkout page in a new tab
   * **Copy Link** — copy the checkout URL to share by email, WhatsApp, your website, or any other channel
   * **Share WhatsApp** — open WhatsApp with the checkout link ready to send
   * **Download QR** — download a QR code image of the checkout link

<Frame>
  <img alt="Sharepage" />
</Frame>

### How to modify a payment page

1. Payment page can be edited, deleted or turned off/on, when viewing single payment page there are three actions.
   1. **Edit**\
      When viewing payment page, there is an edit button which redirects to edit payment page. All the details about the page can be edited.

<Frame>
  <img alt="Editpage" />
</Frame>

2. **Deactivate**\
   After creation by default a payment page is activated, this means it can receive payments. When viewing payment page there is a toggle to deactivate the payment page. When the payment page is deactivated, the payment page will no longer receive payments.

<Frame>
  <img alt="Deactivate Page" />
</Frame>

3. **Delete**\
   When viewing payment page, there is delete button which will delete the payment page.

<Frame>
  <img alt="Deletepage" />
</Frame>

### Tips and Best Practices

When creating a payment page, if you know which payment method the customers are going to use, it is best to select a currency supported by that method. However, it's not mandatory since the our checkout supports allows customers to pay in various currencies using all available payment methods.

## Common Use Cases

1. Events, festivals and sport facilities can use a **fixed amount** Payment Page to sell online tickets.
2. Educational institutions can use Payment Pages to collect school contributions from students and their parents. Use **open amount** when each contribution can differ, or **fixed amount** when the fee is set.
3. Microfinances can use Payment Pages to receive funds from their customers. This not only facilitates easier collection of loan repayments but also helps them keep track of customers who have paid and those who haven't, particularly in relation to loans.
4. NGOs can use an **open amount** Payment Page to accept contributions and donations from supporters.

## Frequently Asked Questions (FAQ)

1. **During collection who gets charged, is it me or my customer?**\
   Customer is paying for the charges during collection.
2. **My customers don’t have smartphones, how do they pay?**\
   The payment page can only be opened on a computer or smartphone as the payment page is web-based. For customers that don't have a computer or smartphone, a merchant can go to the payment page, choose NMB Bill Number (valid for 15 minutes) or Bank Deposit (valid for 7 days) and share these payment instructions and details manually with the customer. The customer can then do the payment accordingly.
3. **When a customer pays me do I get notifications?**\
   Currently notifications are not sent when a customer pays.
4. **Is ClickPesa limited to specific operators i.e. M-Pesa, Mixx By Yas, or just Artel Money?**\
   There are multiple methods to collect funds via ClickPesa such as Mixx By Yas, Airtel Money, Mpesa, Bank and Card. Learn more about all the [payment methods](/dashboard/settings/collection) that ClickPesa supports.


# Collection
Source: https://docs.clickpesa.com/dashboard/settings/collection

In this section, you'll find all the settings related to receiving funds through   Online   and   Offline Collections  . These settings control payment...

In this section, you'll find all the settings related to receiving funds through **Online** and **Offline Collections**. These settings control payment options, methods, and certain customer permissions within the checkout process.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Online Payments Collection

### Collection Tools

Online collection allows merchants to receive payments through various tools like:

* **[Invoice](/dashboard/e-invoice)**
* **[Payment Page](/dashboard/payment-pages)**
* **[Checkout Link](/checkout/checkout-link)**

This guide will focus on the general settings that apply across these tools.

### Checkout Page Settings

Each tool opens a **Checkout Page**, where customers can make payments

Merchants can control what customers are allowed to do on the checkout page. Settings include:

* **Allow/Disallow Currency Exchange**: This lets customers choose if they want to pay in a currency other than the one specified (e.g., exchange USD to TZS).
* **Allow/Disallow Customer Info Update**: This lets customers edit their information (such as name, email, and phone number.).
* **Allow/Disallow Amount Update**: For invoices and **fixed amount** payment pages, this lets customers change the payment amount if enabled by the merchant. It does not apply to **open amount** payment pages — the customer always enters the amount — or to Checkout Links, where the amount stays locked.

When a tool (Invoice, Payment Page, Checkout Link) is created, it generates a checkout page. The checkout page will display the customer (if pre-attached), the amount to be paid when one is set, and the supported payment methods.

### Checkout Link Activation

To generate checkout links via the [Checkout Link API](/checkout/checkout-link-api), activate Checkout Link in collection settings:

<Steps>
  <Step title="Open Collection settings">
    Log in to the Merchant Dashboard and open **Settings → Collection**.

    <Frame>
      <img alt="Collection settings page" />
    </Frame>
  </Step>

  <Step title="Activate Checkout Link">
    Scroll to the **Checkout Link** section and activate the feature.

    <Frame>
      <img alt="Checkout Link activation toggle" />
    </Frame>
  </Step>
</Steps>

See [Checkout Link](/checkout/checkout-link) for use cases and API integration.

### Collection Methods

Merchants can enable or disable specific payment methods depending on their preferences. Available methods include:

* **Cards**: Visa, Mastercard, UnionPay
* **NMB Bill Number**
* **Bank Deposit**
* **Mixx By Yas**
* **Airtel Money**
* **MPesa** - if not available you can request it via [support@clickpesa.com](mailto:support@clickpesa.com)
* **TanQR/Lipa Namba** — see [TanQR/Lipa Namba setup](/tan-qr/lipa-namba-setup) (KYC required)
* **CRDB Direct Debit** — mandate-based recurring collections; see [Set Up CRDB Direct Debit](/crdb-direct-debit/setup) (KYC required)

After activating CRDB Direct Debit, create [Payment Plans](/crdb-direct-debit/payment-plans) in the dashboard or use the [CRDB Direct Debit API](/crdb-direct-debit/api-overview).

### Customizing Payment Methods

By turning on or off any of these methods in the settings, merchants can decide what options will appear on the checkout page for customers to use.

### How to Access Online Collection Settings

1. Navigate to Collection Settings:

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. Enable/Disable Payment Methods:

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. Customize Checkout Page (Invoice as an example):
   * Click Settings button, it will open a drawer with the following actions

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Offline Payments Collection

### Collection Methods

There are three payment methods available for offline collections:

* **Mixx By Yas** **Bill-Pay**
* **Airtel Money** **Bill-Pay**
* **MPesa Bill-Pay** - if not available you can request it via [support@gmail.com](mailto:support@clickpesa.com)

### Collection Tools

The offline collection setup includes three key tools for managing customer payments:

1. **Merchant Offline Reference**\
   This provides a static reference number for the merchant, which customers can use to pay via mobile money. Detailed instructions on how to use this reference are available on [here](/bill-pay/billpay-namba).
2. **Customer Offline Reference**\
   Similar to the merchant reference, but unique for each customer. Detailed instructions on using customer references are available [here](/bill-pay/customer-billpay-namba).
3. **Order Reference**\
   A unique order identifier used in offline transactions. This reference is explained thoroughly in the [Developer Documentation](https://developers.clickpesa.com).

### How to Access Offline Collection Settings

1. Navigate to Collection Settings and scroll down to **Offline Collection**:

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>


# Developers
Source: https://docs.clickpesa.com/dashboard/settings/developers

Create applications, manage API keys, webhooks, and IP whitelisting in the Merchant Dashboard

Developers settings is where you configure API integration from the dashboard. For the full integration walkthrough, see [API Integration Setup](/application/api-application-setup).

<Note>
  The Developers tab is available to users with the **Main**, **Manager**, or **Developer** role when developer features are enabled for your account.
</Note>

## How to access

1. Log in to the [Merchant Dashboard](https://merchant.clickpesa.com).
2. Open **Settings** and select **Developers**.

You can also open the in-dashboard developer hub at [merchant.clickpesa.com/get-started/developers](https://merchant.clickpesa.com/get-started/developers).

## Applications

Create an application for each platform or integration you connect to ClickPesa.

1. Click **Create New Application**.
2. Enter an application name.
3. Select **API** as the integration type.
4. Choose the features you need (for example **Payment API**, **Payout API**, **Checkout Link**).
5. Click **Create**.

After creation, copy your **Client ID** and **API Key** immediately — the API key is shown only once. See [API Integration Setup](/application/api-application-setup) for authentication details.

<Note>
  If KYC is not yet approved, API access is limited to **100 calls per day** (including token generation). The limit resets at midnight East Africa Time. Complete [KYC](/dashboard/settings/kyc) to remove this cap.
</Note>

## Webhooks

Configure webhook endpoints under **Developers** to receive real-time payment and payout notifications. See [Webhooks](/home/webhooks) for event types and payload formats.

## Encryption

If your integration uses checksum validation, configure encryption keys in the Developers section. See [Checksum Security](/home/checksum).

## IP Whitelisting

Restrict API access to approved IP addresses under **Developers → Whitelisted IPs**. Requests from unlisted IPs are denied. See [IP Whitelisting](/home/whitelisted-ip-address).

## Developer setup checklist

The in-dashboard developer hub tracks five setup items:

1. **Add Developer Access** — invite a team member with the Developer role under [Team settings](/dashboard/settings/team)
2. **Create Application** — create an application in Developers settings
3. **API Keys** — generate and store API keys for your application
4. **Webhooks** — configure webhook endpoints
5. **IP Whitelisting** — add approved IP addresses

## Related documentation

<CardGroup>
  <Card title="Integration Overview" icon="compass" href="/home/integration-overview">
    Compare API, hosted, and embedded integration options.
  </Card>

  <Card title="API Explorer" icon="brackets-curly" href="/api-reference">
    Explore and test ClickPesa API endpoints.
  </Card>
</CardGroup>


# Disbursement
Source: https://docs.clickpesa.com/dashboard/settings/disbursement

This settings is the location where your company's bank account is added. The withdraw settlement account is the bank account where funds are settled when...

## Withdraw Settlement Account

This settings is the location where your company's bank account is added. The withdraw settlement account is the bank account where funds are settled when you make a withdraw.

**How to add and update settlement account details**

1. On the ClickPesa Merchant Dashboard homepage, go to the bottom left corner and click on the Settings tab, select Disbursement tab.
2. Click the “Add Bank Details” button to add the details of the account that you to settle funds on withdraw.
3. After adding your Bank Name, Account Name, Account Number, Account Currency, Swift Code, and Routing Number(Routing number does not apply to some of the banks and countries like Tanzania so you can leave it blank)

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

**Note:** The bank account name needs to be in the name of the registered company. Any other name will not be accepted and the collected funds will not be settled accordingly.
4\. You will be prompted with password field for security check to verify its you who setting bank details.
5\. Edit Settlement Account details

1. On settlement settings page, click edit button to modify any information in your settlement account details.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. Once you've updated your settlement account details, click the "Save" button to ensure the changes are saved.
3. You will be prompted with password field for security check to verify its you who is updating bank details.

### Frequently Asked Questions (FAQ)

1. **Can I add my personal bank account as director as a settlement account?**\
   The bank account name needs to be in the name of the registered company. Any other name will not be accepted and the collected funds will not be settled accordingly.

## Payouts

### **How to Access Payout Settings**

1. Log in to your ClickPesa Merchant Dashboard.
2. Navigate to the settings tab, which is typically located at the bottom left corner of your dashboard.
3. Click on DIsbursement tab on settings page
4. Scroll to the section called Payouts

<Frame>
  <img alt="Payout Settings 1024x588" />
</Frame>

### Fee Bearer Settings

This Payout Settings allows merchants to define who bears the fees associated with payouts. There are three options available for fee allocation: the merchant, the beneficiary, or both the merchant and beneficiary sharing the fee equally. This document explains how to configure these settings.

These settings are used on [single payout](/dashboard/disbursement/single-payout) and [bulk payouts](/dashboard/disbursement/bulk-payouts).

<Frame>
  <img alt="Payout Fee" />
</Frame>

#### **Configuring Fee Bearer Settings**

Once you have accessed the Payout Fee Bearer Settings, you will find the following options:

1. **Merchant (Default):** With this option selected, the merchant covers all fees associated with payouts. The beneficiary receives the full payout amount.
2. **Beneficiary:** When this option is chosen, the beneficiary is responsible for covering all payout fees. The merchant disburses the payout amount, and any fees are deducted from the beneficiary’s portion.
3. **Both:** Selecting this option means that both the merchant and beneficiary share the payout fees equally. The fees are divided evenly between the two, and the net payout amount is calculated accordingly.

**How to Set the Fee Bearer**

1. Click on the preferred fee bearer option. The selected option will be highlighted or marked for clarity.
2. You will be prompted with password field drawer for security check to verify its you who is updating fee bearer.

<Frame>
  <img alt="ScreenShot Tool 20231031165255 1024x140" />
</Frame>

### Payout Roles

This settings help merchants to assign payout roles to their team members so they can create/authorize payouts on their behalf.

<Frame>
  <img alt="Payout Roles" />
</Frame>

#### **Configuring Payout Role Settings**

Once you have accessed the Payout Settings:

1. If you don’t have any role added, you will find a button saying Assign Role

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. If you already have assigned roles you will find a button saying Assign Role

<Frame>
  <img alt="Assign Role" />
</Frame>

3. Clicking those buttons will open a drawer where you can assign a role to your team members, roles including **Initiator** and **Approver**. Team members who are just employees will only be able to be assigned an Initiator role while Managers will be able to be assigned Initiators or Approvers.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

**What are these Payout Roles?**

**Initializor**

1. Can create / initiate [bulk payouts](/dashboard/disbursement/bulk-payouts) but can not confirm it.
2. Can initiate a [single payout](/dashboard/transactions/payouts) but can not authorize it. The payouts that were created by initiator will have **UNAUTHORIZED** status

**Approver**

1. Can confirm [bulk payouts](/dashboard/disbursement/bulk-payouts)
2. Can authorize [single payouts](/dashboard/transactions/payouts)

**Tips and Best Practices**

* Consider your business model and customer base when setting the fee bearer option. For example, if your customers are price-sensitive, you may opt to cover the fees as the merchant to enhance the customer experience.
* It's advisable to clearly communicate the fee bearer settings to your customers, so they are aware of any potential deductions from their payouts.

### **Frequently Asked Questions (FAQ)**

1. **Where are Payout Fee Bearer Settings Used?**
   * The Payout Fee Bearer Settings are applied to all payout transactions processed through the ClickPesa Merchant Dashboard. The selected fee bearer option determines who covers the fees associated with each payout.
2. **Can I Change the Fee Bearer for Each Payout Transaction?**
   * The fee bearer settings are typically configured at the account level. This means that the selected option applies to all payout transactions processed by the merchant. If you have a transaction that need different configurations the best option is to change Fee settings to match transaction requirements, perform the payout and change the settings back to the previous settings. You can always change this setting to match your requirements.
3. **Can the Fee Bearer Setting Be Communicated to the Beneficiary?**
   * Yes, it's a good practice to inform the beneficiary about the fee bearer setting for transparency. This can be done through clear communication in your payment or payout policies and during the transaction process to ensure that beneficiaries are aware of any fee deductions from their payouts.


# General
Source: https://docs.clickpesa.com/dashboard/settings/general

Manage business profile, contact details, and authorised person information in the Merchant Dashboard

General settings cover your business identity and the authorised person on your account. Complete both sections as part of the [account setup checklist](/dashboard/setup-company-account).

## Business Profile

Under **Settings → General**, update:

* **Business details** — industry, description, TIN, and VAT number
* **Business type** — set during registration and displayed read-only here. To change it, email [support@clickpesa.com](mailto:support@clickpesa.com).
* **Company name** — displayed read-only after it is set. To change it, email [support@clickpesa.com](mailto:support@clickpesa.com).
* **Contact details** — phone, email, address, city, country, default language, and website

Your company name and contact details appear on ClickPesa receipts, invoices, and payment pages.

## Authorised Person

On the same page, add the authorised contact person:

* Name
* Phone number
* Email

## How to update

<Steps>
  <Step title="Open General settings">
    Open **Settings** from the bottom-left sidebar and select **General**.

    <Frame>
      <img alt="Settings sidebar with General selected" />
    </Frame>
  </Step>

  <Step title="Edit your profile">
    Click **Edit** in the top right corner.

    <Frame>
      <img alt="General settings edit form" />
    </Frame>
  </Step>

  <Step title="Save your changes">
    Update the fields and click **Save**.

    <Frame>
      <img alt="General settings saved confirmation" />
    </Frame>
  </Step>
</Steps>

## Tips

Set up General settings before using payment or payout features. Default language here is used for merchant and customer notifications. On [bulk payouts](/dashboard/disbursement/bulk-payouts), the **Language** column overrides this default for that beneficiary notification only.

## FAQ

**Do my company details appear on receipts, invoices, and payment pages?**

Yes. Your company name, email, and contact number are shown on ClickPesa receipts, invoices, and payment pages.


# KYC
Source: https://docs.clickpesa.com/dashboard/settings/kyc

Upload and manage KYC documents to verify your business in the Merchant Dashboard

ClickPesa is a licensed financial institution. Before you can use the platform without transaction limits, you must complete **Know Your Customer (KYC)** verification.

<Note>
  KYC is step 3 of the [account setup checklist](/dashboard/setup-company-account). Document requirements by business type are also listed in [Get Started With ClickPesa](/home/onboarding#step-2-complete-kyc).
</Note>

## How to access KYC settings

1. Log in to the [Merchant Dashboard](https://merchant.clickpesa.com).
2. Open **Settings** and select **KYC**.

The KYC tab is available to users with the **Main** or **Manager** role when KYC is enabled for your account.

## Before you start

1. Your **business type** is set during registration and shown under **Settings → General**. It cannot be changed from the dashboard. Requirements depend on the type on your account.
2. Have registration documents ready. Sample templates and forms are available for download in the KYC page.
3. For each required **beneficial owner (UBO)**, you will upload identity documents (NIDA, Voter's ID, Driving Licence, or Passport) for directors, shareholders, partners, trustees, or other roles listed for your business type.

<Warning>
  **I am not registered / Individual** is not a KYC-supported business type. To complete KYC, register your business (for example as a **Sole Proprietor**), then email [support@clickpesa.com](mailto:support@clickpesa.com) to request a business type change before uploading documents. Business type changes can only be made by ClickPesa support.
</Warning>

## Submission steps

1. Review required **business documents** and **UBO** sections shown for your business type.
2. Upload each required document.
3. Complete any required **forms** (for example board resolution or ClickPesa Terms and Conditions) with signatures, seal, and witness where stated.
4. If prompted, complete **KYC search payment** before your submission is reviewed.
5. Submit for compliance review.

Our compliance team reviews your submission. You receive an email when KYC is **approved** or if more information is needed. After approval, transaction and API limits are removed and additional features (such as card, TanQR/Lipa Namba, and CRDB Direct Debit collections) become available.

## Restrictions before KYC approval

Until KYC is approved:

* **Transaction limit:** **TZS 100,000 total** combined across collections, payouts, deposits, and withdraws in TZS. A separate limit applies to USD activity.
* **When the limit is reached:** You can still view your account and complete KYC, but payouts, collections, and other payment actions are paused until verification is approved.
* **Card collections:** Card payment methods cannot be enabled until KYC is complete.
* **TanQR/Lipa Namba and CRDB Direct Debit:** These collection methods cannot be enabled until KYC is complete.
* **Other collection channels:** Some additional online collection channel activations also require KYC before they can be enabled.
* **API usage:** **100 API calls per day**, including token generation. Resets at **midnight East Africa Time (EAT)**. Removed after KYC approval.
* You receive a notification when you reach **half** of your transaction limit.

## Need help?

Contact [compliance@clickpesa.com](mailto:compliance@clickpesa.com) for questions about document requirements or review status.


# Security
Source: https://docs.clickpesa.com/dashboard/settings/security

In today's digital landscape, safeguarding your accounts against unauthorized access is crucial. This feature enables users to effortlessly update their...

## Introduction

In today's digital landscape, safeguarding your accounts against unauthorized access is crucial. This feature enables users to effortlessly update their registered phone numbers, used for one-time passwords (OTPs), and passwords utilized for system login.

The ability to change crucial account credentials, such as phone numbers and passwords, serves as a fundamental aspect of maintaining account security. With this feature, users gain greater control over their account's integrity and accessibility. Let's explore how this feature empowers users to take charge of their account security effortlessly.

### OTP Phone number

1. Log in to your ClickPesa Merchant Dashboard.
2. Navigate to the settings tab, which is typically located at the bottom left corner of your dashboard. And then click security tab on settings page.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. Click on Security tab on settings page and then click on "Change" button under "OTP NUMBER" card. It will open a drawer

<Frame>
  <img alt="Otp 1" />
</Frame>

4. Enter your new OTP phone number and your password to confirm changes and submit

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### Password

1. Log in to your ClickPesa Merchant Dashboard.
2. Navigate to the settings tab, which is typically located at the bottom left corner of your dashboard. And then click security tab on settings page.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. Click on Security tab on settings page then click on "Change" button under "PASSWORD" card. It will open a drawer

<Frame>
  <img alt="Password 1" />
</Frame>

4. Enter your Old password and your new strong password to confirm changes and submit

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>


# Team
Source: https://docs.clickpesa.com/dashboard/settings/team

Invite team members and assign roles in the Merchant Dashboard

<Note>
  The Team tab is available to the **main account holder** on business accounts. Team management is step 6 of the [account setup checklist](/dashboard/setup-company-account).
</Note>

The team feature lets administrators add team members, assign roles, and invite collaborators by email.

## How to use Team

### How to access

Log in to [merchant.clickpesa.com](https://merchant.clickpesa.com), open **Settings**, and select **Team**.

<Frame>
  <img alt="Team settings page in Merchant Dashboard" />
</Frame>

### How to add a team member

<Steps>
  <Step title="Open the invite form">
    Click **Add Team Member**.

    <Frame>
      <img alt="Add Team Member button on Team settings" />
    </Frame>
  </Step>

  <Step title="Send the invitation">
    Fill in the required fields and send the invitation.

    <Frame>
      <img alt="Invite team member form" />
    </Frame>
  </Step>

  <Step title="Team member accepts the invite">
    The team member receives an email with an invitation link.

    <Frame>
      <img alt="Team member invitation email" />
    </Frame>

    They set a password to join the platform.

    <Frame>
      <img alt="Team member password setup screen" />
    </Frame>
  </Step>

  <Step title="Complete onboarding">
    The team member follows the standard [onboarding process](/home/onboarding). They do not submit KYC documents but complete login setup.
  </Step>

  <Step title="Manage existing members">
    From the Team table you can **Resend** expired invites, change **Role**, or **Deactivate** / **Activate** accounts. You are prompted for your password when changing team member access.

    <Frame>
      <img alt="Resend team invitation button" />
    </Frame>

    <Frame>
      <img alt="Team member role dropdown" />
    </Frame>

    <Frame>
      <img alt="Deactivate team member button" />
    </Frame>

    <Frame>
      <img alt="Activate team member button" />
    </Frame>
  </Step>
</Steps>

### Team member Roles

1. **Manager**\
   This role can be given to those members who are likely to be given higher roles in your account, i.e We have [payout roles](/dashboard/settings/disbursement#payout-roles) (Initiator and Authorizer). Only a member with Managerial Role can be an Authorizer for Payouts.
2. **Employee**\
   This role can be given to those members who are likely to be given lower roles in your account, i.e We have [payout roles](/dashboard/settings/disbursement#payout-roles) (Initiator and Authorizer). Employees can only be given Initiator roles for payouts.
3. **Developer**\
   Developer role is created to help speed up integration process for merchants with less technical ability. Developer will only be able to view payouts and payments. And They will be able to set anything associated with integration within the dashboard. [Open Here](https://developers.clickpesa.com) to View Developer documentation.

## Common Use Cases

1. **External** **Accountants** Collaborate with accountants by adding them as team members. Accountants can assist in managing financial records, but administrators retain control over authorizing payouts and fund withdrawals.
2. **Administration, Bookkeepers** **and other staff members** Collaborate with staff members to share data and do actions without giving them access to initiate payouts and withdrawals.


# Set Up Your Company Account
Source: https://docs.clickpesa.com/dashboard/setup-company-account

Complete the six-step account setup checklist in the Merchant Dashboard before collecting payments or sending payouts

<Note>
  After registration, open **Get Started** in the sidebar or go to [merchant.clickpesa.com/get-started/account-setup](https://merchant.clickpesa.com/get-started/account-setup) to track your progress. See the [Merchant Dashboard Overview](/dashboard/dashboard-overview) for the full picture.
</Note>

Complete these six steps in order. Each maps to a section under **Settings** in the Merchant Dashboard.

## 1. Complete Your Business Profile

Add your business information under **Settings → General**:

* Industry (business type is set at registration and cannot be changed from the dashboard)
* Business description
* Physical address and city
* TIN and VAT (if applicable)

These details appear on ClickPesa receipts, invoices, and payment pages. [General settings guide](/dashboard/settings/general)

## 2. Authorised Person

On the same **Settings → General** page, add the authorised contact person:

* Name
* Phone number
* Email

[General settings guide](/dashboard/settings/general)

## 3. Complete KYC Verification

Upload required documents under **Settings → KYC** to verify your business and unlock full features.

Document requirements depend on your business type. See [Get Started With ClickPesa — Complete KYC](/home/onboarding#step-2-complete-kyc) for the full list, or follow the in-dashboard KYC wizard. [KYC settings guide](/dashboard/settings/kyc)

<Note>
  KYC review typically takes 2–3 business days. Until approved, a **TZS 100,000 total** pre-KYC transaction limit applies across collections, payouts, deposits, and withdraws, and API access is limited to **100 calls per day** (resets at midnight EAT). See [limits before KYC approval](/home/onboarding#limits-before-kyc-approval).
</Note>

## 4. Activate Payment Methods

Enable the collection methods you want to accept under **Settings → Collection**:

* Online methods (mobile money, cards, TanQR/Lipa Namba, and more)
* Offline BillPay collection (control numbers)

You can also use the **Enable Payment Options** guide at [merchant.clickpesa.com/get-started/payment-methods](https://merchant.clickpesa.com/get-started/payment-methods). [Collection settings guide](/dashboard/settings/collection)

## 5. Set Up Withdraw Settlement Account

Add your company bank account under **Settings → Disbursement**. This is where funds are settled when you withdraw from your ClickPesa balance.

The account name must match your registered company name. [Disbursement settings guide](/dashboard/settings/disbursement)

## 6. Manage Team Members

Invite team members under **Settings → Team** and assign roles (Manager, Employee, or Developer).

<Note>
  The Team tab is available to the **main account holder** on business accounts.
</Note>

[Team settings guide](/dashboard/settings/team)

## Developer integration (optional)

If you plan to integrate via API, complete the developer checklist under **Get Started → Developer Resources** or see [Developers settings](/dashboard/settings/developers) and [API Integration Setup](/application/api-application-setup).


# Payments
Source: https://docs.clickpesa.com/dashboard/transactions/payments

Overseeing your payment transaction is essential for good financial management. Our dashboard simplifies this task by providing a clear view and tracking of...

## Introduction

Overseeing your payment transaction is essential for good financial management. Our dashboard simplifies this task by providing a clear view and tracking of all your payment transactions. This guide will assist you in accessing a holistic view of all payments, delving into specific transaction details, and exporting payment data when needed.

## How to use payments

### How to view all payment transactions

1. From your dashboard, navigate to the left-hand side and select "Transactions".

<Frame>
  <img alt="Payments 3" />
</Frame>

2. You will be presented with a couple of tabs, whereby the first tab are payment transactions which has the table that displaying all collected and received payments summary and table. Select this tab.
   * Payments will be shown with different status,
     * **PROCESSING** - Transaction was initiated successfully and funds are on the way
     * **SUCCESS** - Transaction was successfully, Funds will be settled to your balance shortly
     * **SETTLED** - Transaction was successfully and funds were settled to your balance.
     * **FAILED** - Transaction failed
     * **PENDING** - Transaction was initiated, waiting on customer complete the payment.
     * **REFUND** - Transaction was refunded after it was successful and haven't been settled to your account yet.
     * **REVERSE** - Transaction was reversed after it was successful settled to your account
     * **REVERSE WITH CHARGES** - Transactions was reversed after it was successful settled to merchant account, but with charges on merchant. This is due to cost incurred when reversing the payments.
3. This tab shows all the collected and received payment transactions. The transaction with the newest date starts as the first transaction top. When there are many transactions, you can use the below two options:
   1. Use the pagination on the right to go to the next pages.
   2. Make the number of rows per page larger on the far right (up to 100 transactions per page).
4. You will be able to filter payments summary and data by date, status, channels, order, currency and searching by reference, order id, channel or customer.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the page you should be able to see summary with payments count and value
6. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

7. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

8. You will also be able to sort payments in the table by amount and date

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### **How to view a single payment** **transaction**

1. In the payments table, locate the payment you wish to view. On the far right of its row, click the "View" button.

<Frame>
  <img alt="View Payment 4" />
</Frame>

2. A drawer will appear on the right, showcasing detailed information about the selected payment.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. You are able to copy ID and account number data from details drawer for this payment. For sharing it with clickpesa support team in case payment went wrong or sharing it with your customers.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to export payment transactions

1. In the Payment Table, locate and click the "Export" button at the far right. This will take you to [payments export page](/dashboard/data-export/payment-export).

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## **Common Use Cases**

1. This feature can be used mainly if you want to view your payment details
2. Also if you want to export your payment details and import them to another system

## Frequently Asked Questions (FAQ)

1. **Is it possible to export payment transaction data from the ClickPesa Merchant Dashboard to another system?**\
   Yes you can export all the transaction data from ClickPesa Merchant Dashboard and then import it manually within the other system if they allow for data import.
2. **Which file formats can data be exported from the ClickPesa Merchant Dashboard?**\
   ClickPesa Merchant Dashboard allows you to export data in CSV format.


# Payouts
Source: https://docs.clickpesa.com/dashboard/transactions/payouts

Overseeing your payout transactions is a crucial aspect of any business, and being able to track and review payouts is fundamental to maintaining...

## Introduction

Overseeing your payout transactions is a crucial aspect of any business, and being able to track and review payouts is fundamental to maintaining transparency and control over your finances. Our dashboard offers a streamlined and user-friendly interface to view all your payouts and even export this data for further analysis or record-keeping.

## How to use payouts

### How to view all payout transaction

1. From your dashboard, navigate to the left-hand side and select "Transactions" and the select Payouts tab.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

2. You will be able to filter payouts summary and data by date, status, channels (**MOBILE MONEY**, **BANK TRANSFER**, **LIPA NAMBA**), payout type, and searching by reference, account name, account number or Lipa Namba, channel, or channel provider.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

3. On the page you should be able to see summary with payouts count and value
4. You will also be able to see a graph section where data are measured by time or status.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

5. On the graph you will be able to change graph data by selecting Time, value or status. You should also be able to change data style between area chart and bar chart

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

6. You will also be able to sort payouts in the table by amount, date and fee actions, you can use the below two options:

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to view a single payout transaction

1. In the payouts table, locate the payout you wish to view. On the far right of its row, click the "View" button.

<Frame>
  <img alt="View Payout 6" />
</Frame>

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

* Payouts will be shown with different status,
  * **PROCESSING** – Transaction was initiated successfully and funds are on the way
  * **SUCCESS** – Transaction was successfully, Funds will be settled to recipient Mobile, Bank account, or Lipa Namba
  * **FAILED** – Transaction failed
  * **REFUNDED** - Transaction was refunded before it was successful.
  * **REVERSED** - Transaction was reversed after it was successful.
  * **UNAUTHORIZED** - Status for when a payout is initialized by an initializer but are yet to be approved. [Learn More](/dashboard/settings/disbursement)

2. You are able to copy ID and account number data from details drawer for this payout. For sharing it with clickpesa support team in case payout went wrong or sharing it with your customers.

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

### How to export payout transactions

1. In the Payouts Table, locate and click the "Export" button at the far right. This will take you to [payout export page](/dashboard/data-export/payout-export).

<Frame>
  <img alt="Merchant Dashboard screenshot" />
</Frame>

## Common Use Cases

1. This feature can be used mainly if you want to view your payout details
2. Also if you want to export your payout details and import them to another system

## Frequently Asked Questions (FAQ)

1. **Is it possible to export payout transaction data from the ClickPesa Merchant Dashboard to another system?**\
   Yes, you can export all the transaction data from ClickPesa Merchant Dashboard and then import it manually within the other system if they allow for data import.
2. **Which file formats can data be exported from the ClickPesa Merchant Dashboard?**\
   ClickPesa Merchant Dashboard allows you to export data in CSV format.
3. **What is the difference between payouts and withdraws?**\
   Payouts are transfers to third parties and withdraws are transfers to your own bank account.


# Checksum
Source: https://docs.clickpesa.com/home/checksum

Generate checksum for secure transactions via API

The payloads checksum ensures data integrity and consistency during API requests.

On incoming requests it ensures that the payment or payout request is from a valid merchant and that no one has tampered with it.

[Webhooks](/home/webhooks) payload are also signed using the same method as defined below. This allows merchants to ensure that the webhook request came from ClickPesa and that no one has tampered with it.

<Warning>
  **Important** <br /> When you change your checksum settings (turning on/off), you must [regenerate your API tokens](/api-reference/authorization/generate-token) to ensure continued access to the API. Existing tokens will become invalid when checksum settings are modified.
</Warning>

<Warning>
  **Important** <br />  When generating or validating a checksum, ensure the payload does **not** include the `checksumMethod` or `checksum` fields. These fields should be excluded from checksum computations.
</Warning>

## **Generating Payload Checksum**

1. **Canonicalize Payload** - Recursively sort all object keys alphabetically at every nesting level to ensure consistent ordering regardless of how the payload is structured.
2. **Serialize to JSON** - Convert the canonicalized payload to a compact JSON string (no extra whitespace).
3. **Generate HMAC-SHA256 Hash** - The JSON string is hashed using HMAC-SHA256 with the provided secret key.
4. **Return the Hex Digest** - The resulting hash is returned as a 64-character hexadecimal string.

<Note>
  * **Recursive sorting** ensures that nested objects maintain consistent key ordering at all levels.
  * The same checksum is generated **regardless of key order** in the original payload.
  * All data types (strings, numbers, objects, arrays) are properly handled through JSON serialization.
  * The checksum is **order-independent** - the same payload with keys in different orders will produce the same checksum.
</Note>

### **Examples**

<CodeGroup>
  ```javascript Javascript theme={null}
  const crypto = require("crypto");

  function canonicalize(obj) {
    if (obj === null || typeof obj !== 'object') return obj;
    if (Array.isArray(obj)) {
      return obj.map(canonicalize);
    }
    return Object.keys(obj)
      .sort()
      .reduce((acc, key) => {
        acc[key] = canonicalize(obj[key]);
        return acc;
      }, {});
  }

  const createPayloadChecksum = (checksumKey, payload) => {
    // Canonicalize the payload recursively for consistent ordering
    const canonicalPayload = canonicalize(payload);
    // Serialize the canonical payload
    const payloadString = JSON.stringify(canonicalPayload);
    // Create HMAC with SHA256
    const hmac = crypto.createHmac("sha256", checksumKey);
    hmac.update(payloadString);
    return hmac.digest("hex");
  };

  // Example usage:
  const payload = {
    amount: 100,
    currency: "USD",
    reference: "TX123",
    exchange: {
      fromCurrency: "TZS",
      toCurrency: "TZS",
      rate: "1",
      amount: "1000",
    },
    customer: {
      name: "John Doe",
      email: "john@example.com",
      phone: "+255123456789"
    }
  };
  const checksumKey = "secret-key";
  console.log(createPayloadChecksum(checksumKey, payload));
  ```

  ```python Python theme={null}
  import json
  import hmac
  import hashlib

  def canonicalize(obj):
      if obj is None or not isinstance(obj, (dict, list)):
          return obj

      if isinstance(obj, list):
          return [canonicalize(item) for item in obj]

      return {
          key: canonicalize(obj[key])
          for key in sorted(obj.keys())
      }

  def create_payload_checksum(checksum_key, payload):
      # Canonicalize the payload recursively for consistent ordering
      canonical_payload = canonicalize(payload)
      # Serialize the canonical payload
      payload_string = json.dumps(canonical_payload, separators=(',', ':'), sort_keys=False)
      # Create HMAC with SHA256
      hmac_obj = hmac.new(
          checksum_key.encode('utf-8'),
          payload_string.encode('utf-8'),
          hashlib.sha256
      )
      return hmac_obj.hexdigest()

  # Example usage:
  payload = {
      "amount": 100,
      "currency": "USD",
      "reference": "TX123",
      "exchange": {
          "fromCurrency": "TZS",
          "toCurrency": "TZS",
          "rate": "1",
          "amount": "1000",
      },
      "customer": {
          "name": "John Doe",
          "email": "john@example.com",
          "phone": "+255123456789"
      }
  }
  checksum_key = "secret-key"
  print(create_payload_checksum(checksum_key, payload))
  ```

  ```php PHP theme={null}
  <?php
  function canonicalize($obj) {
      if ($obj === null || !is_array($obj)) {
          return $obj;
      }

      // Check if array is a list (sequential numeric keys starting from 0)
      if (array_values($obj) === $obj) {
          return array_map('canonicalize', $obj);
      }

      ksort($obj);
      $result = [];
      foreach ($obj as $key => $value) {
          $result[$key] = canonicalize($value);
      }
      return $result;
  }

  function createPayloadChecksum($checksumKey, $payload) {
      // Canonicalize the payload recursively for consistent ordering
      $canonicalPayload = canonicalize($payload);
      // Serialize the canonical payload
      $payloadString = json_encode($canonicalPayload, JSON_UNESCAPED_SLASHES);
      // Create HMAC with SHA256
      return hash_hmac('sha256', $payloadString, $checksumKey);
  }

  // Example usage:
  $payload = [
      "amount" => 100,
      "currency" => "USD",
      "reference" => "TX123",
      "exchange" => [
          "fromCurrency" => "TZS",
          "toCurrency" => "TZS",
          "rate" => "1",
          "amount" => "1000",
      ],
      "customer" => [
          "name" => "John Doe",
          "email" => "john@example.com",
          "phone" => "+255123456789"
      ]
  ];
  $checksumKey = "secret-key";
  echo createPayloadChecksum($checksumKey, $payload);
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/hex"
  	"encoding/json"
  	"fmt"
  	"sort"
  )

  func canonicalize(obj interface{}) interface{} {
  	switch v := obj.(type) {
  	case nil:
  		return nil
  	case map[string]interface{}:
  		result := make(map[string]interface{})
  		keys := make([]string, 0, len(v))
  		for k := range v {
  			keys = append(keys, k)
  		}
  		sort.Strings(keys)
  		for _, k := range keys {
  			result[k] = canonicalize(v[k])
  		}
  		return result
  	case []interface{}:
  		result := make([]interface{}, len(v))
  		for i, item := range v {
  			result[i] = canonicalize(item)
  		}
  		return result
  	default:
  		return obj
  	}
  }

  func createPayloadChecksum(checksumKey string, payload map[string]interface{}) (string, error) {
  	// Canonicalize the payload recursively for consistent ordering
  	canonicalPayload := canonicalize(payload)

  	// Serialize the canonical payload
  	payloadBytes, err := json.Marshal(canonicalPayload)
  	if err != nil {
  		return "", err
  	}

  	// Create HMAC with SHA256
  	mac := hmac.New(sha256.New, []byte(checksumKey))
  	mac.Write(payloadBytes)
  	hashBytes := mac.Sum(nil)

  	// Convert to hexadecimal string
  	return hex.EncodeToString(hashBytes), nil
  }

  // Example usage:
  func main() {
  	payload := map[string]interface{}{
  		"amount":    100,
  		"currency":  "USD",
  		"reference": "TX123",
  		"exchange": map[string]interface{}{
  			"fromCurrency": "TZS",
  			"toCurrency":   "TZS",
  			"rate":         "1",
  			"amount":       "1000",
  		},
  		"customer": map[string]interface{}{
  			"name":  "John Doe",
  			"email": "john@example.com",
  			"phone": "+255123456789",
  		},
  	}
  	checksumKey := "secret-key"
  	checksum, _ := createPayloadChecksum(checksumKey, payload)
  	fmt.Println(checksum)
  }
  ```

  ```java Java theme={null}
  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.nio.charset.StandardCharsets;
  import java.security.InvalidKeyException;
  import java.security.NoSuchAlgorithmException;
  import java.util.Map;
  import java.util.TreeMap;

  public class Checksum {
      private static final Gson gson = new GsonBuilder()
              .disableHtmlEscaping()
              .create();

      @SuppressWarnings("unchecked")
      private static Object canonicalize(Object obj) {
          if (obj == null || !(obj instanceof Map)) {
              return obj;
          }

          Map<String, Object> map = (Map<String, Object>) obj;
          Map<String, Object> sortedMap = new TreeMap<>();

          for (Map.Entry<String, Object> entry : map.entrySet()) {
              sortedMap.put(entry.getKey(), canonicalize(entry.getValue()));
          }

          return sortedMap;
      }

      public static String createPayloadChecksum(String checksumKey, Map<String, Object> payload)
              throws NoSuchAlgorithmException, InvalidKeyException {
          // Canonicalize the payload recursively for consistent ordering
          Object canonicalPayload = canonicalize(payload);

          // Serialize the canonical payload
          String payloadString = gson.toJson(canonicalPayload);

          // Create HMAC with SHA256
          Mac mac = Mac.getInstance("HmacSHA256");
          SecretKeySpec secretKeySpec = new SecretKeySpec(
                  checksumKey.getBytes(StandardCharsets.UTF_8),
                  "HmacSHA256"
          );
          mac.init(secretKeySpec);
          byte[] hashBytes = mac.doFinal(payloadString.getBytes(StandardCharsets.UTF_8));

          // Convert to hexadecimal string
          StringBuilder hexString = new StringBuilder();
          for (byte b : hashBytes) {
              String hex = Integer.toHexString(0xff & b);
              if (hex.length() == 1) {
                  hexString.append('0');
              }
              hexString.append(hex);
          }

          return hexString.toString();
      }

      // Example usage:
      public static void main(String[] args) {
          try {
              Map<String, Object> payload = new java.util.HashMap<>();
              payload.put("amount", 100);
              payload.put("currency", "USD");
              payload.put("reference", "TX123");

              Map<String, Object> exchange = new java.util.HashMap<>();
              exchange.put("fromCurrency", "TZS");
              exchange.put("toCurrency", "TZS");
              exchange.put("rate", "1");
              exchange.put("amount", "1000");
              payload.put("exchange", exchange);

              Map<String, Object> customer = new java.util.HashMap<>();
              customer.put("name", "John Doe");
              customer.put("email", "john@example.com");
              customer.put("phone", "+255123456789");
              payload.put("customer", customer);

              String checksumKey = "secret-key";
              System.out.println(createPayloadChecksum(checksumKey, payload));
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  ```
</CodeGroup>

## Validating Payload Checksum

1. **Extract Checksum**  - Extract the checksum from the received request.

2. **Prepare Payload** - Before recomputing the checksum, **exclude** the `checksum` and `checksumMethod` fields from the payload.

3. **Recompute Checksum** - Using the same `createPayloadChecksum` function, recompute the checksum from the prepared payload using the checksum key.

4. **Compare the Computed and Received Checksum**
   * If both checksums match, the payload is valid and untampered.
   * If they do not match, reject the request as it may have been modified.

### **Examples**

<CodeGroup>
  ```javascript Javascript theme={null}
  const crypto = require("crypto");

  function canonicalize(obj) {
    if (obj === null || typeof obj !== 'object') return obj;
    if (Array.isArray(obj)) {
      return obj.map(canonicalize);
    }
    return Object.keys(obj)
      .sort()
      .reduce((acc, key) => {
        acc[key] = canonicalize(obj[key]);
        return acc;
      }, {});
  }

  const createPayloadChecksum = (checksumKey, payload) => {
    const canonicalPayload = canonicalize(payload);
    const payloadString = JSON.stringify(canonicalPayload);
    const hmac = crypto.createHmac("sha256", checksumKey);
    hmac.update(payloadString);
    return hmac.digest("hex");
  };

  const validateChecksum = (checksumKey, payload, receivedChecksum) => {
    // Extract checksumMethod before excluding it from payload
    const checksumMethod = payload.checksumMethod || 'canonical';
    // Exclude checksum and checksumMethod from payload before validation
    const payloadForValidation = { ...payload };
    delete payloadForValidation.checksum;
    delete payloadForValidation.checksumMethod;
    // Pass checksumMethod as option to support legacy method
    const computedChecksum = createPayloadChecksum(checksumKey, payloadForValidation, { checksumMethod });
    return computedChecksum === receivedChecksum;
  };

  // Example usage:
  const payload = {
    amount: 100,
    currency: "USD",
    reference: "TX123",
    exchange: {
      fromCurrency: "TZS",
      toCurrency: "TZS",
      rate: "1",
      amount: "1000",
    },
    customer: {
      name: "John Doe",
      email: "john@example.com",
      phone: "+255123456789"
    }
  };
  const checksumKey = "secret-key";
  const receivedChecksum = "some-checksum-from-request"; // Replace with actual received checksum

  console.log(validateChecksum(checksumKey, payload, receivedChecksum) ? "Valid" : "Invalid");
  ```

  ```python Python theme={null}
  import json
  import hmac
  import hashlib

  def canonicalize(obj):
      if obj is None or not isinstance(obj, (dict, list)):
          return obj

      if isinstance(obj, list):
          return [canonicalize(item) for item in obj]

      return {
          key: canonicalize(obj[key])
          for key in sorted(obj.keys())
      }

  def create_payload_checksum(checksum_key, payload):
      canonical_payload = canonicalize(payload)
      payload_string = json.dumps(canonical_payload, separators=(',', ':'), sort_keys=False)
      hmac_obj = hmac.new(
          checksum_key.encode('utf-8'),
          payload_string.encode('utf-8'),
          hashlib.sha256
      )
      return hmac_obj.hexdigest()

  def validate_checksum(checksum_key, payload, received_checksum):
      if not received_checksum:
          return False
      # Extract checksumMethod before excluding it from payload
      checksum_method = payload.get('checksumMethod', 'canonical')
      # Exclude checksum and checksumMethod from payload before validation
      payload_for_validation = {k: v for k, v in payload.items() if k not in ['checksum', 'checksumMethod']}
      # Pass checksumMethod as option to support legacy method
      computed_checksum = create_payload_checksum(checksum_key, payload_for_validation, {'checksumMethod': checksum_method})
      return computed_checksum == received_checksum

  # Example usage:
  payload = {
      "amount": 100,
      "currency": "USD",
      "reference": "TX123",
      "exchange": {
          "fromCurrency": "TZS",
          "toCurrency": "TZS",
          "rate": "1",
          "amount": "1000",
      },
      "customer": {
          "name": "John Doe",
          "email": "john@example.com",
          "phone": "+255123456789"
      }
  }
  checksum_key = "secret-key"
  received_checksum = "some-checksum-from-request"  # Replace with actual received checksum

  print("Valid" if validate_checksum(checksum_key, payload, received_checksum) else "Invalid")
  ```

  ```php PHP theme={null}
  <?php
  function canonicalize($obj) {
      if ($obj === null || !is_array($obj)) {
          return $obj;
      }

      if (array_values($obj) === $obj) {
          return array_map('canonicalize', $obj);
      }

      ksort($obj);
      $result = [];
      foreach ($obj as $key => $value) {
          $result[$key] = canonicalize($value);
      }
      return $result;
  }

  function createPayloadChecksum($checksumKey, $payload) {
      $canonicalPayload = canonicalize($payload);
      $payloadString = json_encode($canonicalPayload, JSON_UNESCAPED_SLASHES);
      return hash_hmac('sha256', $payloadString, $checksumKey);
  }

  function validateChecksum($checksumKey, $payload, $receivedChecksum) {
      if (empty($receivedChecksum)) {
          return false;
      }
      // Extract checksumMethod before excluding it from payload
      $checksumMethod = $payload['checksumMethod'] ?? 'canonical';
      // Exclude checksum and checksumMethod from payload before validation
      $payloadForValidation = $payload;
      unset($payloadForValidation['checksum']);
      unset($payloadForValidation['checksumMethod']);
      // Pass checksumMethod as option to support legacy method
      // Note: Your createPayloadChecksum function should accept options parameter
      $computedChecksum = createPayloadChecksum($checksumKey, $payloadForValidation, ['checksumMethod' => $checksumMethod]);
      return hash_equals($computedChecksum, $receivedChecksum); // Prevent timing attacks
  }

  // Example usage:
  $payload = [
      "amount" => 100,
      "currency" => "USD",
      "reference" => "TX123",
      "exchange" => [
          "fromCurrency" => "TZS",
          "toCurrency" => "TZS",
          "rate" => "1",
          "amount" => "1000",
      ],
      "customer" => [
          "name" => "John Doe",
          "email" => "john@example.com",
          "phone" => "+255123456789"
      ]
  ];
  $checksumKey = "secret-key";
  $receivedChecksum = "some-checksum-from-request"; // Replace with actual received checksum

  if (validateChecksum($checksumKey, $payload, $receivedChecksum)) {
      echo "Valid Checksum";
  } else {
      echo "Invalid Checksum";
  }
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/hex"
  	"encoding/json"
  	"fmt"
  	"sort"
  )

  func canonicalize(obj interface{}) interface{} {
  	switch v := obj.(type) {
  	case nil:
  		return nil
  	case map[string]interface{}:
  		result := make(map[string]interface{})
  		keys := make([]string, 0, len(v))
  		for k := range v {
  			keys = append(keys, k)
  		}
  		sort.Strings(keys)
  		for _, k := range keys {
  			result[k] = canonicalize(v[k])
  		}
  		return result
  	case []interface{}:
  		result := make([]interface{}, len(v))
  		for i, item := range v {
  			result[i] = canonicalize(item)
  		}
  		return result
  	default:
  		return obj
  	}
  }

  func createPayloadChecksum(checksumKey string, payload map[string]interface{}) (string, error) {
  	canonicalPayload := canonicalize(payload)
  	payloadBytes, err := json.Marshal(canonicalPayload)
  	if err != nil {
  		return "", err
  	}

  	mac := hmac.New(sha256.New, []byte(checksumKey))
  	mac.Write(payloadBytes)
  	hashBytes := mac.Sum(nil)

  	return hex.EncodeToString(hashBytes), nil
  }

  func validateChecksum(checksumKey string, payload map[string]interface{}, receivedChecksum string) (bool, error) {
  	if receivedChecksum == "" {
  		return false, nil
  	}
  	// Extract checksumMethod before excluding it from payload
  	checksumMethod := "canonical"
  	if method, ok := payload["checksumMethod"].(string); ok {
  		checksumMethod = method
  	}
  	// Exclude checksum and checksumMethod from payload before validation
  	payloadForValidation := make(map[string]interface{})
  	for k, v := range payload {
  		if k != "checksum" && k != "checksumMethod" {
  			payloadForValidation[k] = v
  		}
  	}
  	// Pass checksumMethod as option to support legacy method
  	// Note: Your createPayloadChecksum function should accept options parameter
  	computedChecksum, err := createPayloadChecksum(checksumKey, payloadForValidation, map[string]interface{}{"checksumMethod": checksumMethod})
  	if err != nil {
  		return false, err
  	}
  	return computedChecksum == receivedChecksum, nil
  }

  // Example usage:
  func main() {
  	payload := map[string]interface{}{
  		"amount":    100,
  		"currency":  "USD",
  		"reference": "TX123",
  		"exchange": map[string]interface{}{
  			"fromCurrency": "TZS",
  			"toCurrency":   "TZS",
  			"rate":         "1",
  			"amount":       "1000",
  		},
  		"customer": map[string]interface{}{
  			"name":  "John Doe",
  			"email": "john@example.com",
  			"phone": "+255123456789",
  		},
  	}
  	checksumKey := "secret-key"
  	receivedChecksum := "some-checksum-from-request" // Replace with actual received checksum

  	isValid, _ := validateChecksum(checksumKey, payload, receivedChecksum)
  	if isValid {
  		fmt.Println("Valid Checksum")
  	} else {
  		fmt.Println("Invalid Checksum")
  	}
  }
  ```

  ```java Java theme={null}
  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.nio.charset.StandardCharsets;
  import java.security.InvalidKeyException;
  import java.security.NoSuchAlgorithmException;
  import java.util.Map;
  import java.util.TreeMap;

  public class Checksum {
      private static final Gson gson = new GsonBuilder()
              .disableHtmlEscaping()
              .create();

      @SuppressWarnings("unchecked")
      private static Object canonicalize(Object obj) {
          if (obj == null || !(obj instanceof Map)) {
              return obj;
          }

          Map<String, Object> map = (Map<String, Object>) obj;
          Map<String, Object> sortedMap = new TreeMap<>();

          for (Map.Entry<String, Object> entry : map.entrySet()) {
              sortedMap.put(entry.getKey(), canonicalize(entry.getValue()));
          }

          return sortedMap;
      }

      public static String createPayloadChecksum(String checksumKey, Map<String, Object> payload)
              throws NoSuchAlgorithmException, InvalidKeyException {
          Object canonicalPayload = canonicalize(payload);
          String payloadString = gson.toJson(canonicalPayload);

          Mac mac = Mac.getInstance("HmacSHA256");
          SecretKeySpec secretKeySpec = new SecretKeySpec(
                  checksumKey.getBytes(StandardCharsets.UTF_8),
                  "HmacSHA256"
          );
          mac.init(secretKeySpec);
          byte[] hashBytes = mac.doFinal(payloadString.getBytes(StandardCharsets.UTF_8));

          StringBuilder hexString = new StringBuilder();
          for (byte b : hashBytes) {
              String hex = Integer.toHexString(0xff & b);
              if (hex.length() == 1) {
                  hexString.append('0');
              }
              hexString.append(hex);
          }

          return hexString.toString();
      }

      public static boolean validateChecksum(String checksumKey, Map<String, Object> payload, String receivedChecksum)
              throws NoSuchAlgorithmException, InvalidKeyException {
          // Extract checksumMethod before excluding it from payload
          String checksumMethod = (String) payload.getOrDefault("checksumMethod", "canonical");
          // Exclude checksum and checksumMethod from payload before validation
          Map<String, Object> payloadForValidation = new java.util.HashMap<>(payload);
          payloadForValidation.remove("checksum");
          payloadForValidation.remove("checksumMethod");
          // Pass checksumMethod as option to support legacy method
          // Note: Your createPayloadChecksum function should accept options parameter
          Map<String, Object> options = new java.util.HashMap<>();
          options.put("checksumMethod", checksumMethod);
          String computedChecksum = createPayloadChecksum(checksumKey, payloadForValidation, options);
          return computedChecksum.equals(receivedChecksum);
      }

      // Example usage:
      public static void main(String[] args) {
          try {
              Map<String, Object> payload = new java.util.HashMap<>();
              payload.put("amount", 100);
              payload.put("currency", "USD");
              payload.put("reference", "TX123");

              Map<String, Object> exchange = new java.util.HashMap<>();
              exchange.put("fromCurrency", "TZS");
              exchange.put("toCurrency", "TZS");
              exchange.put("rate", "1");
              exchange.put("amount", "1000");
              payload.put("exchange", exchange);

              Map<String, Object> customer = new java.util.HashMap<>();
              customer.put("name", "John Doe");
              customer.put("email", "john@example.com");
              customer.put("phone", "+255123456789");
              payload.put("customer", customer);

              String checksumKey = "secret-key";
              String receivedChecksum = "some-checksum-from-request"; // Replace with actual received checksum

              if (validateChecksum(checksumKey, payload, receivedChecksum)) {
                  System.out.println("Valid Checksum");
              } else {
                  System.out.println("Invalid Checksum");
              }
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  ```
</CodeGroup>

## **Demo**

[Checksum Demo Repository](https://github.com/ClickPesa/clickpesa-api-checksum-demo) - includes implementations in JavaScript, Python, PHP, Java, and Go, all verified for cross-language interoperability.


# Instant Web Access
Source: https://docs.clickpesa.com/home/instant-web-access

Install the ClickPesa Merchant Dashboard as an app on your phone or desktop for quick access without app store downloads

Install the Merchant Dashboard on your home screen or desktop for one-tap access — no app store download or manual updates required.

## Mobile

### Android

<Steps>
  <Step title="Open the dashboard in Chrome">
    Visit [merchant.clickpesa.com](https://merchant.clickpesa.com/) in Chrome.
  </Step>

  <Step title="Open the browser menu">
    Tap the three-dot menu at the top right of the address bar.

    <Frame>
      <img alt="Chrome three-dot menu on Android" />
    </Frame>
  </Step>

  <Step title="Install the app">
    Tap **Install App** at the bottom of the menu.

    <Frame>
      <img alt="Chrome Install App option" />
    </Frame>

    <Frame>
      <img alt="Chrome install confirmation prompt" />
    </Frame>
  </Step>

  <Step title="Open from your home screen">
    The ClickPesa icon appears in your app list for quick access.

    <Frame>
      <img alt="ClickPesa app icon on Android home screen" />
    </Frame>
  </Step>
</Steps>

### iPhone

<Steps>
  <Step title="Open the dashboard in Safari">
    Visit [merchant.clickpesa.com](https://merchant.clickpesa.com/) in Safari.
  </Step>

  <Step title="Open the Share menu">
    Tap the **Share** icon at the bottom center.

    <Frame>
      <img alt="Safari Share icon on iPhone" />
    </Frame>
  </Step>

  <Step title="Add to Home Screen">
    Tap **Add to Home Screen**.

    <Frame>
      <img alt="Safari Add to Home Screen option" />
    </Frame>

    <Frame>
      <img alt="Edit app name before adding to home screen" />
    </Frame>
  </Step>

  <Step title="Open from your home screen">
    The ClickPesa icon appears on your home screen.

    <Frame>
      <img alt="ClickPesa app icon on iPhone home screen" />
    </Frame>
  </Step>
</Steps>

## Desktop

### Windows, Linux, and Mac

<Steps>
  <Step title="Open the dashboard in Chrome">
    Visit [merchant.clickpesa.com](https://merchant.clickpesa.com/) in Chrome.
  </Step>

  <Step title="Install the app">
    Click the install icon in the address bar.

    <Frame>
      <img alt="Chrome install icon in address bar" />
    </Frame>

    <Frame>
      <img alt="Chrome desktop install confirmation" />
    </Frame>
  </Step>

  <Step title="Open from your desktop">
    The ClickPesa icon appears in your desktop app list.

    <Frame>
      <img alt="ClickPesa desktop app icon" />
    </Frame>
  </Step>
</Steps>


# Overview
Source: https://docs.clickpesa.com/home/integration-overview

Welcome! ClickPesa offers a robust and flexible integration suite that supports different business requirements. Whether you need full API control, a simple hosted checkout, or an embedded solution, these guidelines will help you get started

## Integration Options

<CardGroup>
  <Card title="Merchant Dashboard" icon="window-maximize" href="/dashboard/dashboard-overview">
    Manage collections, payouts, transactions, and settings from the web
    dashboard — no coding required.
  </Card>

  <Card title="API Integration Setup" icon="code" href="/application/api-application-setup">
    For businesses that require full control over their payment flow, ClickPesa
    provides API-based integration. This setup allows developers to connect
    directly to ClickPesa’s payment infrastructure using secure API endpoints.
  </Card>

  <Card title="Hosted Integration Setup" icon="globe" href="/application/hosted-application-setup">
    If you prefer a simpler approach, ClickPesa provides a hosted payment
    solution. This method allows businesses to redirect users to a
    ClickPesa-hosted page to complete transactions.
  </Card>

  <Card title="Embedded Integration Setup" icon="window-restore" href="/application/embedded-application-setup">
    For businesses that want to maintain a seamless user experience within their
    own platform, ClickPesa provides embedded integration options.
  </Card>
</CardGroup>

## Choose a Collection Product

|                            | **TanQR/Lipa Namba**                                             | **BillPay**                                                                                    | **USSD Push**                                                                            | **Card**                                                            | **CRDB Direct Debit**                                                                                 |
| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **What the customer uses** | Your QR code or Lipa Namba                                       | A BillPay control number                                                                       | Their mobile money wallet                                                                | Their Visa, Mastercard, Amex, or UnionPay card                      | Approves a mandate via their CRDB SIM-Banking App                                                     |
| **How they pay**           | Scan QR, or pay via USSD and bank channels using your Lipa Namba | Pay via mobile money USSD, SIM banking, or bank channels using the control number              | Approves a USSD push prompt on their phone with their wallet PIN                         | Enters card details on a hosted checkout session                    | Scheduled debits from their CRDB account after mandate approval                                       |
| **Best for**               | Store collections — physical and online                          | Deposits, order payments, invoices, and customer-specific references                           | In-app or online checkout where you send a payment request to the customer's phone       | Online card payments                                                | Installments, subscriptions, and recurring agreements                                                 |
| **Setup**                  | [Merchant Dashboard](/tan-qr/lipa-namba-setup)                   | [Merchant Dashboard](/bill-pay/billpay-namba) or [BillPay API](/bill-pay/billpay-api-overview) | [USSD Push API](/payment-api/mobile-money-payment-api/mobile-money-payment-api-overview) | [Card API](/payment-api/card-payment-api/card-payment-api-overview) | [Merchant Dashboard](/crdb-direct-debit/setup) or [Direct Debit API](/crdb-direct-debit/api-overview) |

* Use **[TanQR/Lipa Namba](/tan-qr/tan-qr-overview)** when you want customers to scan your QR code or pay using your Lipa Namba.
* Use **[BillPay](/bill-pay/bill-pay-overview)** when you need control numbers for deposits, orders, invoices, or customer-specific references.
* Use **[USSD Push](/payment-api/mobile-money-payment-api/mobile-money-payment-api-overview)** when you want to send a payment prompt to the customer's mobile money wallet.
* Use **[Card](/payment-api/card-payment-api/card-payment-api-overview)** when you want customers to pay with Visa, Mastercard, Amex, or UnionPay via a hosted checkout session.
* Use **[CRDB Direct Debit](/crdb-direct-debit/crdb-direct-debit-overview)** when you need mandate-based recurring collections from CRDB accounts.

## Additional Features & Considerations

<CardGroup>
  <Card title="Payment Statuses" icon="circle-info" href="/home/payment-status">
    Understanding different payment statuses is crucial for managing transactions
    effectively.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/home/webhooks">
    Webhooks allow you to receive real-time payment updates directly to your
    system. Make sure to configure and secure webhook endpoints properly to ensure
    seamless transaction tracking.
  </Card>

  <Card title="IP Whitelisting" icon="lock" href="/home/whitelisted-ip-address">
    Restrict API access to only approved IP addresses for enhanced security. Any
    API request from an unlisted IP will be denied.
  </Card>

  <Card title="Checksum Security" icon="lock" href="/home/checksum">
    For enhanced security, ClickPesa provides checksum validation to verify the
    integrity of transaction data. It is recommended to implement checksum
    verification in all API-based interactions.
  </Card>
</CardGroup>

## Resources

<CardGroup>
  <Card title="API Explorer" icon="compass" href="/api-reference">
    Explore and test ClickPesa's APIs with the API Explorer. It provides a
    user-friendly interface to interact with API endpoints and understand their
    functionality.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.clickpesa.com/home/introduction

ClickPesa makes accepting and disbursing payments easy, whether you know how to code or not - ClickPesa has the right solution for you

Leverage our hosted or embedded functionality to go to market with your payments business quickly and securely. Power every payment flow with a single API. From pay-ins to pay-outs and everything in between, manage payment operations with ease.

<CardGroup>
  <Card title="Get Started With ClickPesa" icon="circle-play" href="/home/onboarding">
    Learn how to open a ClickPesa account for your business and complete KYC
  </Card>

  <Card title="Changelog" icon="timer" href="/home/changelog">
    Product updates — new releases and improvements
  </Card>

  <Card title="Hosted Checkout" icon="cart-shopping" href="/checkout/checkout-overview">
    A ready-to-use payment solution supporting multiple methods with a single integration. Embed it on your site or redirect customers to Hosted Checkout
  </Card>

  <Card title="Merchant Dashboard" icon="window-maximize" href="/dashboard/dashboard-overview">
    Manage collections, payouts, transactions, and settings from the web dashboard — no coding required.
  </Card>

  <Card title="BillPay" icon="ballot-check" href="/bill-pay/bill-pay-overview">
    Streamline your billing process by creating unique control numbers for receiving payments via Mobile Money, Simbanking or Wakala
  </Card>

  <Card title="TanQR/Lipa Namba" icon="qrcode" href="/tan-qr/tan-qr-overview">
    Accept payments with a QR code and Lipa Namba powered by TIPS. Customers can pay via USSD, bank channels, or by scanning your QR code
  </Card>

  <Card title="Lipa Namba Payout API" icon="bolt" href="/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview">
    Send money to any Lipa Namba or TanQR, instantly — from a wallet you already run, or a new payout product
  </Card>

  <Card title="Mobile USSD-PUSH API" icon="mobile" href="/payment-api/mobile-money-payment-api/mobile-money-payment-api-overview">
    Collect payments from mobile money wallets such as M-Pesa, Mixx By Yas, Airtel Money and Halopesa using USSD-PUSH requests
  </Card>

  <Card title="Card API" icon="credit-card" href="/payment-api/card-payment-api/card-payment-api-overview">
    Accept card payments from Visa, MasterCard, American Express and UnionPay
  </Card>

  <Card title="Mobile Payouts API" icon="mobile" href="/payout-api/mobile-money-payout-api/mobile-money-payout-api-overview">
    Disburse funds to mobile money wallets such as M-Pesa, Mixx By Yas, Airtel Money and Halopesa
  </Card>

  <Card title="Bank Payout API" icon="building-columns" href="/payout-api/bank-payout-api/bank-payout-api-overview">
    Disburse funds to bank accounts such as NMB, CRDB and GTBank in Tanzania
  </Card>

  <Card title="Plugins and SDK" icon="puzzle-piece" href="/sdk-plugins/plugins-and-extensions">
    Official and community-built plugins and SDKs to integrate ClickPesa into WooCommerce, Laravel, Python, Node.js, and more
  </Card>
</CardGroup>


# Login and Password Reset
Source: https://docs.clickpesa.com/home/login-password-reset

How to log in to the ClickPesa Merchant Dashboard with OTP and reset your password

<Note>
  First-time registration, email verification, and OTP setup are covered in [Get Started With ClickPesa](/home/onboarding#step-1-sign-up).
</Note>

## Login

After your first login you do not need to verify your email or add your phone number again.

<Steps>
  <Step title="Open the login page">
    Go to [merchant.clickpesa.com](https://merchant.clickpesa.com/).
  </Step>

  <Step title="Enter your credentials">
    Enter your email and password, then click **Login**.
  </Step>

  <Step title="Enter your OTP">
    Enter the OTP sent to your phone number.
  </Step>
</Steps>

OTP is a 5-digit code sent via SMS to your phone number. Every time you sign in with your email and password you receive an OTP that you must enter to access your account. The OTP is unique and expires after a couple of minutes. If the OTP is incorrect, you cannot log in — use **Resend OTP** to receive a new code. You can also receive the OTP by email.

## Reset Password

<Steps>
  <Step title="Start password reset">
    On the login page, click **Forgot password** under the password field.

    <Frame>
      <img alt="Login page with Forgot password link" />
    </Frame>
  </Step>

  <Step title="Request a reset link">
    Enter your email and click submit to receive a password reset link.

    <Frame>
      <img alt="Password reset email entry form" />
    </Frame>
  </Step>

  <Step title="Open the email link">
    Check your email and click the **Reset Password** button.

    <Frame>
      <img alt="Password reset email with Reset Password button" />
    </Frame>
  </Step>

  <Step title="Set a new password">
    Enter your new password and confirm it, then click **Update Password**.

    <Frame>
      <img alt="New password entry form" />
    </Frame>

    <Frame>
      <img alt="Password updated confirmation screen" />
    </Frame>
  </Step>
</Steps>


# Get Started With ClickPesa
Source: https://docs.clickpesa.com/home/onboarding

Learn how open a ClicPesa account for your business and organizations in Tanzania

Registered businesses (Individual and Organizations) in Tanzania can create an account with ClickPesa.
**Registering an account is FREE**— No credit card required, No monthly or yearly fees! We charge on transaction, you make money we make money. Find our [fees and pricing](https://clickpesa.com/payment-gateway/pricing/).

## Step 1: Sign Up

* Visit [ClickPesa Dashboard](https://merchant.clickpesa.com/account-registration) and create an account.
* The signup process is quick and takes **less than 3 minutes**.
* Once signed up, you can explore and use the platform, but **usage limits apply until KYC is approved** (transaction caps, API daily limit, and some features).

### Registration walkthrough

<AccordionGroup>
  <Accordion title="Enter email and password">
    * Input your email and select a password for your ClickPesa merchant dashboard. To ensure a strong password is provided, a password should:
      * have at least 8 characters
      * include at least one capital letter
      * include at least one small letter
      * include at least one number
      * include at least one special character: `!@#$%^&*()_+-=[]{};':"\|,.<>/?~`
    * Check the box to agree with the terms of service and privacy policy.
    * Click the "Register" button to proceed.

    <Frame>
      <img alt="ClickPesa account registration form" />
    </Frame>
  </Accordion>

  <Accordion title="Email verification">
    1. An email will be sent to you containing a "Verify Your Email" button.
       <Frame>
         <img alt="Email verification message in inbox" />
       </Frame>
    2. Click on it to confirm your email address.
       <Frame>
         <img alt="Email verified confirmation screen" />
       </Frame>
    3. Congratulations! You are now successfully registered for the ClickPesa Merchant Dashboard.
  </Accordion>

  <Accordion title="First time login and OTP setup">
    1. After email verification, log in with your email and password at [merchant.clickpesa.com](https://merchant.clickpesa.com/).
       <Frame>
         <img alt="Merchant Dashboard login page" />
       </Frame>
    2. Set up OTP (One Time Password) — a 5-digit code sent via SMS to your phone number.
       * Enter your phone number in the **Phone Number** field.
         <Frame>
           <img alt="OTP phone number entry screen" />
         </Frame>
       * Enter the code from the SMS into the **OTP Code** field and click **Enable OTP**.
         <Frame>
           <img alt="OTP code verification screen" />
         </Frame>
       * If the code expires, click **Resend Code** to receive a new OTP.

    For subsequent logins, see [Login and Password Reset](/home/login-password-reset).
  </Accordion>

  <Accordion title="Add a business name">
    After verifying your OTP during your first login, you need to enter your Business Name. Then, click the "Get Started" button to proceed.

    <Frame>
      <img alt="Business name entry during first login" />
    </Frame>

    Afterward, you will be taken to the homepage of your ClickPesa Merchant Dashboard.

    <Frame>
      <img alt="Merchant Dashboard homepage after registration" />
    </Frame>

    Once you are at the homepage of your ClickPesa Merchant Dashboard, open **Get Started** in the sidebar or follow the [account setup checklist](/dashboard/setup-company-account). You can also [install the dashboard as an app](/home/instant-web-access) on your phone or desktop for quick access.
  </Accordion>
</AccordionGroup>

### Limits before KYC approval

Until your KYC is approved:

* **TZS 100,000 total** — combined across collections, payouts, deposits, and withdraws in Tanzanian Shillings. This is one shared limit, not a separate cap per transaction type.
* **USD** — a separate pre-KYC limit applies to USD activity.
* **Card collections** — card payment methods are not available until KYC is approved.
* **TanQR/Lipa Namba and CRDB Direct Debit** — these collection methods cannot be enabled until KYC is approved.
* **Online collection channels** — some additional channel activations (for example certain mobile money or bank collection options) also require KYC before they can be turned on.
* **API usage** — **100 API calls per day**, including token generation. The count resets every day at **midnight East Africa Time (EAT)**. This applies only while KYC is not yet approved.
* **When you reach your transaction limit** — you can still view your account and work on KYC submission, but payouts, collections, and other payment actions are paused until KYC is approved.
* You are notified when you reach **half** of your transaction limit.

Complete [KYC](/home/onboarding#step-2-complete-kyc) to remove transaction and API limits and unlock all features.

## Step 2: Complete KYC

* Log in to your account and go to **Settings → KYC**.
* Required documents and beneficial owners (UBOs) are shown in the dashboard based on the **business type** you selected during registration.
* Download sample templates from the KYC page where available.
* Upload all required business documents and UBO identity documents.
* Complete any required forms (including ClickPesa Terms and Conditions) with signatures, seal, and witness where stated.
* If prompted, complete **KYC search payment** before your submission is reviewed.

See also the [KYC settings guide](/dashboard/settings/kyc).

<Note>
  ClickPesa is a licensed financial institution. To open an account for your business we are mandated to perform Due Diligence through a KYC (Know Your Customer) process.
</Note>

<Warning>
  **I am not registered / Individual** cannot complete KYC. Register your business (for example as a Sole Proprietor), then email [support@clickpesa.com](mailto:support@clickpesa.com) to request a business type change before submitting documents. Business type changes can only be made by ClickPesa support.
</Warning>

### Document requirements by business type

Requirements below match what the Merchant Dashboard shows for each business type. **(Required)** documents must be uploaded. **(Optional)** documents apply when relevant. Each listed **UBO** requires identity documents (NIDA, Voter's ID, Driving Licence, or Passport).

<AccordionGroup>
  <Accordion title="Limited Company">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)** — provided by your registration body
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)** — TIN should show the business or company name
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)** — licence should show the business or company name
    7. Memorandum & Articles of Association **(Required)**
    8. Board Resolution **(Required)** — download the sample template from **Settings → KYC**
    9. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)** — signatures, seal, and witness required

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Director **(Required)**
    * Shareholder **(Required)**
  </Accordion>

  <Accordion title="Sole Proprietor">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)**
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)**
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)**
    7. Power of Attorney (optional) — if someone other than the sole proprietor opens and operates the account; template available in **Settings → KYC**
    8. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel (optional)
    * Business Owner **(Required)**
  </Accordion>

  <Accordion title="Partnership">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)**
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)**
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)**
    7. Partnership Deed **(Required)**
    8. Partner Resolution **(Required)** — template available in **Settings → KYC**
    9. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Director **(Required)**
    * Partner **(Required)**
  </Accordion>

  <Accordion title="Trust">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)**
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)**
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)**
    7. Trust Deed **(Required)**
    8. Board Resolution **(Required)** — Trust template available in **Settings → KYC**
    9. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Director **(Required)**
    * Trustee **(Required)**
  </Accordion>

  <Accordion title="Cooperatives">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)**
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)**
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)**
    7. Cooperatives By laws **(Required)**
    8. List of Cooperative members **(Required)**
    9. Board Resolution **(Required)** — template available in **Settings → KYC**
    10. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Director **(Required)**
  </Accordion>

  <Accordion title="Civil Society Organization / NGO">
    **Business documents**

    1. Extract from register / detailed information of the entity **(Required)**
    2. Certificate of Registration **(Required)**
    3. Regulatory License (optional)
    4. Certificate from Tax Revenue Authority (TIN) **(Required)**
    5. VAT Certificate (optional, if applicable)
    6. Business Licence Certificate **(Required)**
    7. Constitution **(Required)**
    8. Board Resolution **(Required)** — template available in **Settings → KYC**
    9. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Director **(Required)**
    * Founder Member **(Required)**
  </Accordion>

  <Accordion title="Community Management Groups (VICOBA)">
    **Business documents**

    1. Hati Ya Usajili **(Required)**
    2. Barua ya utambulisho wa Serikali ya Mtaa **(Required)**
    3. Katiba Ya Kikundi **(Required)**
    4. Azimio la kufungua akaunti ClickPesa **(Required)** — template available in **Settings → KYC**
    5. VAT Certificate (optional)
    6. Regulatory License (optional)
    7. ClickPesa Customer Service Level Agreement (Terms and Conditions) **(Required)**

    **Beneficial owners (UBOs)**

    * Authorized Personnel **(Required)**
    * Kiongozi wa kikundi (Group leader) **(Required)**
  </Accordion>
</AccordionGroup>

Make sure all documents are current and match your registered business name.

## Step 3: KYC Approval

* Our compliance team will review your submission.
* You’ll receive an email notification once your KYC is **approved or if more information is needed**.
* After approval, **pre-KYC transaction and API limits are removed**, giving you full access to the platform.

## Need Help?

If you have any questions at any stage, feel free to reach out to [compliance@clickpesa.com](mailto:compliance@clickpesa.com) for assistance.


# Payment Statuses
Source: https://docs.clickpesa.com/home/payment-status

Understand the different payment statuses and how to receive them

## Status Overview

| Status       | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `SUCCESS`    | Received payment that has not been settled to the merchant account yet.              |
| `SETTLED`    | Funds are already settled to the merchant account.                                   |
| `PROCESSING` | Payment is currently being processed.                                                |
| `PENDING`    | Payment is pending and awaiting further action from the customer.                    |
| `FAILED`     | Payment was not successful.                                                          |
| `ON-HOLD`    | Payment is on hold and requires further action from the merchant.                    |
| `REFUNDED`   | Payment was not settled to merchant account and funds returned to the customer       |
| `REVERSED`   | Payment was settled to merchant account and then funds were returned to the customer |

## Payment Status in the ClickPesa Dashboard

* You can view the payment status in the [ClickPesa Dashboard](https://merchant.clickpesa.com) under the [Transactions](https://merchant.clickpesa.com/transactions) section.
* The payment statuses are updated in real-time as the payment progresses through different stages.

## Payment Status In Your Application

There are two ways to receive payment statuses in your application:

1. [Webhooks](/home/webhooks) - ClickPesa sends real-time updates to your server when a payment status changes. You can use webhooks to receive these updates.
2. **Querying** - Alternatively, you can make API calls periodically to the [query payment endpoint](/api-reference/collection/querying-for-payments/querying-for-payments).

## Payment Status for Customers

* In Checkout, payment status is displayed to the customer in real-time.
* Additionally, the final payment notificationSuccessfully made payment is sent to the customer via their registered email or mobile phone number.


# Payout Statuses
Source: https://docs.clickpesa.com/home/payout-status

Understand the different payout statuses and how to receive them

## Status Overview

| Status       | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `AUTHORIZED` | Payout process is about to begin.                                         |
| `SUCCESS`    | Payout was initiated successfully.                                        |
| `REFUNDED`   | Payout failed and funds has been returned due to ClickPesa system errors. |
| `REVERSED`   | Payout failed and funds has been returned due to Provider errors.         |
| `PROCESSING` | Payout is currently being processed.                                      |

<Note>
  [Lipa Namba payouts](/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview) are asynchronous. Treat `AUTHORIZED` as **accepted**, not settled. Send a final notification only when status is `SUCCESS` or `REFUNDED`.
</Note>

## Payment Status in the ClickPesa Dashboard

* You can view the payment status in the [ClickPesa Dashboard](https://merchant.clickpesa.com) under the [Transactions](https://merchant.clickpesa.com/transactions) section.
* The payment statuses are updated in real-time as the payment progresses through different stages.

## Payment Status In Your Application

There are two ways to receive payment statuses in your application:

1. [Webhooks](/home/webhooks) - ClickPesa sends real-time updates to your server when a payment status changes. You can use webhooks to receive these updates.
2. **Querying** - Alternatively, you can make API calls periodically to the [query payout endpoint](/api-reference/disbursement/mno-payout/querying-for-payouts).

## Payment Status for Customers

* In Checkout, payment status is displayed to the customer in real-time.
* Additionally, the final payment notification successfully made payment is sent to the customer via their registered email or mobile phone number.


# Webhooks
Source: https://docs.clickpesa.com/home/webhooks

Understand ClickPesa Webhooks (Callbacks) and how to integrate them in your application

Webhooks are HTTP `POST` callbacks that deliver notification messages for events.

ClickPesa uses webhooks to inform your systems when transactional events occur. This way, your servers are always up to date with transaction information.

<Note>Webhook events are published from actions in any of the ClickPesa products, including the ClickPesa Dashboard, Hosted Integrations, Embedded Solutions and APIs.</Note>

## Webhook Levels

ClickPesa supports webhooks at two levels:

| Level                    | Scope                                   | When Used                                                                                                                                                                           |
| ------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Merchant webhooks**    | All transactions for the merchant       | Dashboard payments and other activity not linked to a specific application                                                                                                          |
| **Application webhooks** | Transactions for a specific application | Collection API, Disbursement API, [BillPay API](/bill-pay/billpay-api-overview), [CRDB Direct Debit](/crdb-direct-debit/api-overview) payments, and hosted checkout or payout links |

<Info>
  For payments and payouts tied to an application (including [USSD push](/api-reference/collection/ussd-push-requests/initiate-ussd-push-request) and card payments via the Collection API, [BillPay](/bill-pay/billpay-api-overview) control numbers created via API, [CRDB Direct Debit](/crdb-direct-debit/api-overview) installments, and [Hosted Checkout](/checkout/checkout-overview) links), if the application has a webhook URL configured for the event, the callback is sent to the **application webhook only** — the merchant webhook is not used. If the application has no webhook for the event, the merchant webhook is used instead.
</Info>

## Webhook Events

### `PAYMENT RECEIVED`

When a payment is received successfully, this event is triggered. This event provides you with key information about the payment, including identifiers, amounts, and customer details.

* **Description** - This event is triggered whenever a customer makes a successful payment. The webhook will send details of the transaction, including the amount, payer information, and transaction status.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "PAYMENT RECEIVED",
  "data": {
    "id": "ORD123456LCP7890",
    "status": "SUCCESS",
    "paymentReference": "abc123def456ghi789",
    "orderReference": "ORD123456",
    "collectedAmount": "10000",
    "collectedCurrency": "TZS",
    "message": "success",
    "channel": "CRDB DIRECT DEBIT MANDATE",
    "updatedAt": "2024-04-10T18:22:56.153Z",
    "createdAt": "2024-04-10T18:22:16.949Z",
    "customer": {
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "customerPhoneNumber": "255700000000"
    }
  }
}
```

<Note>
  For `PAYMENT RECEIVED` webhooks, the `collectedAmount` field is always zero or more. If our internal calculation ever ends up with a negative value, we send `"0"` instead so that you never receive a negative collected amount.
</Note>

### `PAYMENT FAILED`

* **Description** - This event is triggered when a payment attempt fails. The webhook will include information about the failure reason, the attempted transaction, and any relevant error codes.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "PAYMENT FAILED",
  "data": {
    "id": "ORD123456LCP7890",
    "status": "FAILED",
    "channel": "CRDB DIRECT DEBIT MANDATE",
    "orderReference": "ORD123456",
    "message": "Insufficient balance",
    "updatedAt": "2024-04-11T04:58:31.036Z",
    "createdAt": "2024-04-11T04:58:31.036Z",
    "clientId": "ID1234XHYAJK"
  }
}
```

<Note>
  For **CRDB Direct Debit** installments, `channel` is `CRDB DIRECT DEBIT MANDATE` and `orderReference` is the **mandate reference** from CRDB (also returned on mandate status callbacks as `mandateReference`). Mandate status changes (**ACTIVE**, **REJECTED**, **CANCELLED**) are sent to the `mandateCallbackUrl` you provide when requesting mandate approval — not to these payment webhook URLs. See the [CRDB Direct Debit API overview](/crdb-direct-debit/api-overview#mandate-status-callbacks).
</Note>

### `PAYOUT INITIATED`

* **Description** - This event is triggered when a payout process is initiated. The webhook will provide details such as the payout amount, recipient information, and the initial status of the payout.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "PAYOUT INITIATED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "SUCCESS",
    "channel": "BANK TRANSFER", // or MOBILE MONEY or TIPS LIPA NAMBA
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}
```

### `PAYOUT REFUNDED`

* **Description** - This event occurs when a payout is refunded, due to an issue with the payout process. The webhook will include the refund details and the original payout information.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "PAYOUT REFUNDED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "REFUNDED",
    "channel": "BANK TRANSFER", // or MOBILE MONEY or TIPS LIPA NAMBA
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "refund": {
      // reverse details
      "message": "The payout was refunded due to insufficient balance.",
      "refundedAt": "2024-09-02T09:30:00.000Z"
    },
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}
```

### `PAYOUT REVERSED`

* **Description**: This event is triggered when a payout is reversed, typically due to an error or a dispute. The webhook will contain details about the reversal, the original payout, and any related information.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "PAYOUT REVERSED",
  "data": {
    "updatedAt": "2024-09-02T10:15:30.000Z",
    "createdAt": "2024-09-01T14:22:10.000Z",
    "id": "PAY17072CD",
    "orderReference": "order_123456",
    "amount": "20000.00",
    "currency": "TZS",
    "fee": "2360.00",
    "status": "REVERSED",
    "channel": "BANK TRANSFER", // or MOBILE MONEY or TIPS LIPA NAMBA
    "channelProvider": "Equity Bank Tanzania Limited",
    "transferType": "ACH", // or RTGS // if available
    "notes": "Payment for invoice no. 123456", // if available
    "reverse": {
      // reverse details
      "message": "The payout was reversed due to invalid account information.",
      "reversedAt": "2024-09-02T09:30:00.000Z",
      "reversedWithFee": true // whether funds were returned with fee or not
    },
    "beneficiary": {
      "accountNumber": "123456789",
      "accountName": "John Doe",
      "swiftNumber": "ABC1234XYZ", // if available
      "routingNumber": "110000000", // if available
      "beneficiaryMobileNumber": "255600000000", // if available
      "beneficiaryEmail": "johndoe@example.com" // if available
    },
    "clientId": "ID1234XHYAJK"
  }
}
```

### `DEPOSIT RECEIVED`

* **Description**: This event is triggered when a deposit is received. The webhook will contain details about the deposit and any related information.

* **Sample Payload Data**

```json [expandable] theme={null}
{
  "event": "DEPOSIT RECEIVED",
  "data": {
    "id": "DEP17C9LPL",
    "status": "SUCCESS",
    "paymentReference": "1982813f15938863",
    "orderReference": "DEP17C9LPL",
    "depositAmount": "2000",
    "depositCurrency": "TZS",
    "channel": "CRDB COLLECTION",
    "updatedAt": "2025-07-20T13:44:22.902Z",
    "createdAt": "2025-07-20T13:44:13.893Z",
    "message": "Payment from Payclick Co Ltd",
  }
}
```

## Setting Up Webhooks

### Merchant-Level Webhooks

Merchant webhooks apply to all transactions unless an application webhook is used (see below).

1. **Access webhook settings**
   * Log in to your [ClickPesa Dashboard](https://merchant.clickpesa.com)
   * Navigate to **Settings** → **Developers**
   * Locate the **Webhooks** section

2. **Add webhook URLs**
   * Select event types: `PAYOUT INITIATED`, `PAYOUT REVERSED`, `PAYOUT REFUNDED`, `PAYMENT RECEIVED`, `PAYMENT FAILED`, or `DEPOSIT RECEIVED`
   * Set the webhook URL for each event

### Application-Level Webhooks

Application webhooks let you receive events per application for transactions tied to that application. This includes:

* **Collection API** — USSD push, card, and other payments you initiate through the API
* **Disbursement API** — mobile money and bank payouts you create through the API
* **BillPay API** — when a customer pays against an [order or customer control number](/bill-pay/billpay-api-overview) you created through the API
* **Hosted integrations** — payments and payouts through hosted links for your application, such as [Hosted Checkout](/checkout/checkout-overview)

Use application webhooks when you have multiple applications (e.g. different apps or environments) and want separate webhook endpoints per application.

<Note>
  Application webhooks do **not** apply to offline BillPay references that were not created through the BillPay API. Payments made only from the dashboard use merchant webhooks instead.
</Note>

<Note>
  An optional `callbackUrl` on [Generate Checkout Link](/api-reference/collection/generate-checkout-link/generate-checkout-link) is separate from application webhooks. Application webhooks are configured in the dashboard and apply to all qualifying payments for that application, whether or not you also set `callbackUrl` on a link.
</Note>

**Supported events:** `PAYMENT RECEIVED`, `PAYMENT FAILED`, `PAYOUT INITIATED`, `PAYOUT REFUNDED`, `PAYOUT REVERSED`

<Note>`DEPOSIT RECEIVED` is only available at the merchant level.</Note>

1. **Access application settings**
   * Log in to your [ClickPesa Dashboard](https://merchant.clickpesa.com)
   * Navigate to **Settings** → **Developers**
   * Click on an application to open its details

2. **Configure application webhooks**
   * In the **Application Webhooks** section, add webhook URLs for the events you need
   * Each application can have its own URLs per event

### Receiving Webhook Calls

* The gateway sends HTTP POST requests to the provided URL upon an event
* Your system should respond with a **2xx HTTP status code** to acknowledge receipt
* Payloads can include a `checksum` and `checksumMethod` for verification (see [Checksum documentation](/home/checksum))

<Note>This status code only indicates receipt, not successful processing.<br />Extra data in the response is ignored.</Note>


# Whitelist IP
Source: https://docs.clickpesa.com/home/whitelisted-ip-address

Whitelisting IP Address for secure API calls

To help keep your data and API usage secure, ClickPesa allows you to restrict access to your APIs by whitelisting specific IP addresses. This ensures only requests from trusted sources can interact with your account.

<Tip>
  Whitelisting IPs is an added layer of security to protect your data and your business. We highly recommend enabling this feature when you're using the APIs in production.
</Tip>

## Accessing Whitelisting IP Settings

To access your whitelisted IPs:

1. Log in to your [ClickPesa Dashboard](https://merchant.clickpesa.com).
2. Navigate to **Settings** → **Developers**.
3. Scroll to the **Whitelisted IP** section.

## Managing IP Addresses

* **Add an IP Address**: Enter the IP address you want to allow. Only requests from this address will be able to access your APIs.
* **Remove an IP Address**: Deleting an IP from the list will immediately revoke its ability to access your APIs.

<Warning>
  If **no** IP addresses are added, your API will accept requests from **any** IP address. - As soon as **one or more IPs** are added, requests from **all other IPs** will be automatically **blocked**.
</Warning>

<Warning>
  Once IP Whitelisting is enabled, the **API Explorer will no longer work for your account**. To test API requests, you must either make calls directly from a whitelisted IP address or remove all IPs from the whitelist.
</Warning>


# Card API
Source: https://docs.clickpesa.com/payment-api/card-payment-api/card-payment-api-overview

Accept card payments from all major card processors including Visa, MasterCard, American Express and UnionPay

## Prerequisites

1. **API Keys** -
   [Generate API Keys](/application/embedded-application-setup) for Hosted Checkout integration

2. **Authorization Token** -
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token)

## How It Works

**Step 1** - Validate Card Payment details

<Card title="Preview Card Payment" icon="brackets-curly" href="/api-reference/collection/card-payment/preview-card-payment">
  This endpoint validates payment details like **Amount**, **Order Reference** and
  verifies **Method** availability
</Card>

**Step 2** - Initiate card payment

<Card title="Initiate Card Payment" icon="brackets-curly" href="/api-reference/collection/card-payment/initiate-card-payment">
  This endpoint initiate a card payment and returns a link of session for hosted mastercard checkout widget.
</Card>

**Step 3** - Open the hosted link in a new tab or window to prompt user to enter their card information and the complete payment.

<Note>
  We do not collect or store customer card information
</Note>

**Step 4** - Check payment status

<Card title="Check Payment Status" icon="brackets-curly" href="/api-reference/collection/card-payment/querying-for-payments">
  This endpoint queries for the payment status using payment's **Order
  Reference**
</Card>


# Mobile USSD-PUSH API
Source: https://docs.clickpesa.com/payment-api/mobile-money-payment-api/mobile-money-payment-api-overview

Collect payments from customers' mobile money wallets using USSD-PUSH requests

## Prerequisites

1. **API Keys** -
   [Create an Application](/application/api-application-setup) to generate **Client ID** and **API Keys** for API acces

2. **Authorization Token** -
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token)

## How It Works

**Step 1** - Validate push request details

<Card title="Preview USSD-PUSH Request" icon="brackets-curly" href="/api-reference/collection/ussd-push-requests/preview-ussd-push-request">
  This endpoint validates payment details like **Mobile Number**, **Amount**, **Order Reference** and verifies **Payment Methods** availability
</Card>

**Step 2** -  Send push request

<Card title="Initiate USSD-PUSH Request" icon="brackets-curly" href="/api-reference/collection/ussd-push-requests/initiate-ussd-push-request">
  This endpoint sends the **USSD-PUSH** request to customer's mobile device.
  The customer will be prompted to enter their mobile money wallet PIN/password to complete the transaction
</Card>

**Step 3** -  Check payment status

<Card title="Check Payment Status" icon="brackets-curly" href="/api-reference/collection/querying-for-payments/querying-for-payments">
  This endpoint queries for the payment status using payment's **Order Reference**
</Card>


# Bank Payout API
Source: https://docs.clickpesa.com/payout-api/bank-payout-api/bank-payout-api-overview

The Bank Payout API enables you to send payouts directly to recipients' bank accounts in Tanzania.

Preview a bank payout to confirm fees, settlement, estimated arrival, and — when the bank supports it — the beneficiary account name. Then create the payout to send funds to the recipient's Tanzanian bank account.

Pay from **TZS** or **USD** (`currency`). Recipients receive **TZS**. When the source currency differs from the receiving currency, preview and create responses include `exchanged` and `exchange`.

<Warning>
  [Create Bank Payout](/api-reference/disbursement/bank-payout/create-bank-payout) allows one create request every **60 seconds** per merchant. Creating another payout before the cooldown ends returns an error with the remaining wait time. Preview is not affected.
</Warning>

## Prerequisites

1. **API Keys** -
   [Generate API Keys](/application/api-application-setup) for Hosted Checkout integration.

2. **Authorization Token** -
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token).

## Settlement

ClickPesa uses the best available route for each bank payout. Request `transferType` is optional — existing integrations can keep sending `ACH` or `RTGS`, but it does not select the rail. Use the response `transferType` for the value that was or will be applied.

Typical settlement:

* TZS up to **20,000,000 TZS**: ACH
* TZS above that: RTGS
* USD: RTGS

Preview and create also return `estimatedArrival` (`Instant` or `1-3 Working Days`).

## Beneficiary name lookup

[Preview Bank Payout](/api-reference/disbursement/bank-payout/preview-bank-payout) may include the account holder name when lookup succeeds for the selected bank.

* `nameLookupStatus` is `RESOLVED` when `receiver.accountName` is present
* `nameLookupStatus` is `UNAVAILABLE` when lookup did not return a name — `receiver.accountName` is omitted. Pass your own verified name on [Create Bank Payout](/api-reference/disbursement/bank-payout/create-bank-payout)

## How It Works

**Step 1** - Retrieve Account Balance

<Card title="Retrieve Account Balance" icon="brackets-curly" href="/api-reference/account/get-account-balance">
  Retrieve your available account balance to ensure sufficient funds for
  processing payouts.
</Card>

**Step 2** - Retrieve Bank List

<Card title="Retrieve Banks List" icon="brackets-curly" href="/api-reference/list/get-bank-list">
  Retrieve the list of supported banks and their BICs to use when previewing
  and creating a payout.
</Card>

**Step 3** - Validate Payout Details

<Card title="Preview Bank Payout" icon="brackets-curly" href="/api-reference/disbursement/bank-payout/preview-bank-payout">
  Validates bank payout details like **bank name**, **amount**, **order
  reference**, and **fee** before processing the payout. May include the
  beneficiary account name when lookup is available.
</Card>

**Step 4** - Initiate Bank Payout

<Card title="Create Bank Payout" icon="brackets-curly" href="/api-reference/disbursement/bank-payout/create-bank-payout">
  Initiate a bank payout by sending a request to the API. The specified amount
  will be transferred to the recipient’s bank account.
</Card>

**Step 5** - Check Payout Status

<Card title="Check Payout Status" icon="brackets-curly" href="/api-reference/disbursement/bank-payout/querying-for-payouts">
  Query the payout status using the **Order Reference** to track whether the
  transaction was successful.
</Card>


# Lipa Namba Payout API
Source: https://docs.clickpesa.com/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview

Send money to any Lipa Namba or TanQR in Tanzania, instantly.

You can now send money to any Lipa Namba or TanQR in Tanzania, instantly.

<Note>
  This API **pays out to** someone else's Lipa Namba or TanQR. Collecting payments **via** your own TanQR/Lipa Namba is a separate product — see [TanQR/Lipa Namba](/tan-qr/tan-qr-overview).
</Note>

To send a Lipa Namba payout without code, use [Single Payout](/dashboard/disbursement/single-payout) in the Merchant Dashboard (Lipa Namba + provider, with **Verify Name**). Dashboard payouts do not support TanQR scan — use this API for `qrCode`.

Preview checks the destination, the recipient's name, the fee, and your balance. Then create sends the payout.

Pay from **TZS** or **USD** (`currency`). Recipients always receive **TZS**. When you pay from USD, preview and create responses include `exchanged` and `exchange`.

Provide **exactly one** destination:

* `lipaNamba` + `providerCode` (from the providers list), or
* `qrCode` (full TanQR string containing `tz.go.bot.tips`)

Preview runs a name lookup. If the beneficiary name cannot be resolved, preview fails — do not create until preview succeeds.

<Warning>
  [Create Lipa Namba Payout](/api-reference/disbursement/lipa-namba-payout/create-lipa-namba-payout) allows one create request every **60 seconds** per merchant. Creating another payout before the cooldown ends returns an error with the remaining wait time. Preview is not affected.
</Warning>

<Note>
  Lipa Namba payouts are asynchronous. Treat create `AUTHORIZED` as **accepted**, not settled. Notify on acceptance, then send a **second** notification when status is `SUCCESS` or `REFUNDED`. See [Payout statuses](/home/payout-status).
</Note>

## Prerequisites

1. **API Keys** -
   [Generate API Keys](/application/api-application-setup) for Hosted Checkout integration.

2. **Authorization Token** -
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token).

## How It Works

**Step 1** - Retrieve Account Balance

<Card title="Retrieve Account Balance" icon="brackets-curly" href="/api-reference/account/get-account-balance">
  Retrieve your available account balance to ensure sufficient funds for
  processing payouts.
</Card>

**Step 2** - Retrieve Lipa Namba Providers

<Card title="Retrieve Lipa Namba Providers" icon="brackets-curly" href="/api-reference/disbursement/lipa-namba-payout/list-lipa-namba-providers">
  Retrieve supported providers and their `providerCode` values. Required when
  paying with `lipaNamba`.
</Card>

**Step 3** - Validate Payout Details

<Card title="Preview Lipa Namba Payout" icon="brackets-curly" href="/api-reference/disbursement/lipa-namba-payout/preview-lipa-namba-payout">
  Validates the Lipa Namba or TanQR, resolves the beneficiary name, and
  returns fee and balance impact.
</Card>

**Step 4** - Initiate Lipa Namba Payout

<Card title="Create Lipa Namba Payout" icon="brackets-curly" href="/api-reference/disbursement/lipa-namba-payout/create-lipa-namba-payout">
  Initiate the payout. The specified amount is transferred to the recipient’s
  Lipa Namba.
</Card>

**Step 5** - Check Payout Status

<Card title="Check Payout Status" icon="brackets-curly" href="/api-reference/disbursement/lipa-namba-payout/querying-for-payouts">
  Query the payout status using the **Order Reference**. Filter all payouts
  with `channel=TIPS LIPA NAMBA`.
</Card>


# Mobile Payouts API
Source: https://docs.clickpesa.com/payout-api/mobile-money-payout-api/mobile-money-payout-api-overview

Send payouts directly to recipients' mobile money wallets.

Preview a mobile money payout to confirm the phone number, amount, fee, and available balance. Then create the payout to send funds to the recipient's mobile wallet.

Pay from **TZS** or **USD** (`currency`). Recipients always receive **TZS** — mobile wallets cannot hold USD. When you pay from USD, preview and create responses include `exchanged` and `exchange`.

<Warning>
  [Create Mobile Money Payout](/api-reference/disbursement/mno-payout/create-mno-payout) allows one create request every **60 seconds** per merchant. Creating another payout before the cooldown ends returns an error with the remaining wait time. Preview is not affected.
</Warning>

## Prerequisites

1. **API Keys** -
   [Generate API Keys](/application/api-application-setup) for Hosted Checkout integration

2. **Authorization Token** -
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token)

## How It Works

**Step 1** - Retrieve Account Balance

<Card title="Retrieve account balance" icon="brackets-curly" href="/api-reference/account/get-account-balance">
  This endpoint retrieves account balance that can help check if merchant has
  enough funds to perform a payout
</Card>

**Step 2** - Validate payout details

<Card title="Preview Mobile Money Payout" icon="brackets-curly" href="/api-reference/disbursement/mno-payout/preview-mno-payout">
  Validates mobile money payout details like **phone number**, amount,
  order-reference, fee
</Card>

**Step 3** - Initiate Mobile Money Payout

<Card title="Create Mobile Money Payout" icon="brackets-curly" href="/api-reference/disbursement/mno-payout/create-mno-payout">
  Initiate a mobile money payout by sending a request to the API. The specified
  amount will be transferred to the recipient’s mobile wallet.
</Card>

**Step 4** - Check payout status

<Card title="Check Payout Status" icon="brackets-curly" href="/api-reference/disbursement/mno-payout/querying-for-payouts">
  This endpoint queries for the payout status using payout's **Order Reference**
</Card>


# Plugins and Extensions
Source: https://docs.clickpesa.com/sdk-plugins/plugins-and-extensions

Official and community-built plugins, SDKs, and extensions for ClickPesa integration

<Note>
  Have you built a plugin or SDK for ClickPesa? We'd love to showcase it! Contact us at [tech@clickpesa.com](mailto:tech@clickpesa.com) to have your community-built plugin or SDK featured on this list.
</Note>

## Official Plugins and SDK

Official plugins and SDKs are developed and maintained by the ClickPesa team. These plugins and SDKs are fully tested, regularly updated, and come with official support.

<CardGroup>
  <Card title="WooCommerce Plugin" icon="shopping-cart" href="https://github.com/ClickPesa/ClickPesa-WooCommerce-Plugin-Release/releases">
    Official ClickPesa payment gateway plugin for WooCommerce. Accept mobile money and card payments directly in your WordPress store.
  </Card>
</CardGroup>

## Community Plugins and SDK

Community plugins and SDKs are developed by the ClickPesa community and can be useful for specific use cases.

<Warning>
  Community plugins and SDKs are provided as-is and may not be officially supported or tested by ClickPesa. Use them at your own discretion. If you encounter any issues, please contact the plugin author directly.
</Warning>

<CardGroup>
  <Card title="Laravel Package" icon="code" href="https://packagist.org/packages/emilkitua/clickpesa">
    Laravel integration package for ClickPesa API. Supports token authorization, USSD checkout, card payments, payment status queries, and wallet balance retrieval.

    **Built by:** Emil Kitua
  </Card>

  <Card title="Python SDK" icon="code" href="https://github.com/JAXPARROW/clickpesa-python-sdk">
    Production-grade Python SDK for the ClickPesa API. Sync & async support, collections, payouts, BillPay, webhooks, auto token management, checksum injection, and retry logic.

    **Built by:** Jackson Linus
  </Card>

  <Card title="Node.js SDK" icon="code" href="https://www.npmjs.com/package/clickpesa-nodejs-sdk">
    TypeScript-first Node.js SDK for the ClickPesa API. Collections, disbursements, BillPay, hosted links, account, and exchange rates, with auto token management, checksum injection, retries, and webhook verification.

    **Built by:** Deogratius Denis Mbombwe
  </Card>
</CardGroup>


# Accepting Payments with Lipa Namba
Source: https://docs.clickpesa.com/tan-qr/accepting-payments

How customers pay using your TanQR/Lipa Namba QR code or Lipa Namba

Once your **Lipa Namba** is active, customers can pay in two ways:

* **Scan your QR code** — From a mobile money or bank app that supports QR payments.
* **Pay with your Lipa Namba** — Through mobile money USSD menus or bank channels, without needing an app.

All MNOs and banks integrated with **TIPS** can be used to pay you.

## Paying by QR Code

1. **Scan your QR code** — Using a phone camera or the scan feature in a mobile money or bank app.
2. **Enter the amount** — The customer types in how much they want to pay.
3. **Confirm the payment** — They review the merchant details and authorize with their PIN or biometric.
4. **Receive confirmation** — Both you and the customer get a payment confirmation.

## Paying with Lipa Namba

Customers can also pay using your **Lipa Namba** directly:

1. **Open USSD or bank channel** — Dial the mobile money USSD code or use SIM banking, internet banking, or a bank branch channel.
2. **Enter your Lipa Namba** — Use your Lipa Namba as the payment reference.
3. **Enter the amount** — The customer types in how much they want to pay.
4. **Confirm the payment** — They authorize with their PIN and receive confirmation.

No app is required for USSD and bank channel payments.

## What You See as a Merchant

* Payments appear **instantly** in your [Merchant Dashboard](https://merchant.clickpesa.com) under transactions.
* You receive **dashboard notifications** for successful payments.
* If you use [webhooks](/home/webhooks), payment events can be sent to your system automatically.

## Tips for a Smooth Checkout

* **Display or share clearly** — Show your QR code and Lipa Namba at a counter, receipt desk, website, checkout page, invoice, or customer message.
* **Confirm the amount** — Customers enter the amount before authorizing payment.
* **Verify on your dashboard** — Confirm payment in your dashboard before handing over goods or completing a service.
* **Use the branded poster** — Download your poster from Collection settings for a clear, professional display.


# Set Up Lipa Namba
Source: https://docs.clickpesa.com/tan-qr/lipa-namba-setup

Activate TanQR/Lipa Namba in the ClickPesa Merchant Dashboard

<Note>
  Learn what TanQR/Lipa Namba is in the [TanQR/Lipa Namba Overview](/tan-qr/tan-qr-overview). Collection settings are also documented in [Collection Settings](/dashboard/settings/collection).
</Note>

## Before You Start

Make sure you have:

* A **verified ClickPesa merchant account** with completed KYC
* Your **business profile** filled in (business name, email, and phone)
* The **TanQR/Lipa Namba activation fee** (250,000 TZS) ready to pay when prompted

<Tip>
  TanQR/Lipa Namba is being rolled out to merchants in phases. If you do not see the option in your dashboard, email [support@clickpesa.com](mailto:support@clickpesa.com) to request access.
</Tip>

## Activation Steps

### 1. Open Collection Settings

1. Log in to your [Merchant Dashboard](https://merchant.clickpesa.com).
2. Go to **Settings → Collection**.
3. Under **Checkout and In-Store Collection**, find **TANQR - Lipa Namba**.

### 2. Complete KYC (if not already done)

If your account is not yet verified, complete KYC under **Settings → KYC** before activation.

### 3. Pay the Activation Fee

Toggle on **TANQR - Lipa Namba** and complete the one-time activation payment of **250,000 TZS** when prompted.

### 4. Register Your Business Details

After payment, complete the registration form:

| Field                    | Description                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **Store type**           | Choose **Physical Store** (in-person location) or **Online Store** (website or app) |
| **Business category**    | Select the category that best describes your business                               |
| **Business description** | A short description of what you sell or the services you offer                      |
| **Location**             | Required for physical stores — select your business location                        |
| **Store URL**            | Required for online stores — enter your website or checkout URL                     |

Your business name, email, and phone are taken from your ClickPesa profile.

### 5. Activate and Receive Your Lipa Namba

Submit the form to register. Once successful:

* Your **Lipa Namba** (merchant code) appears in Collection settings
* Your **QR code** is generated and ready to use
* You can open **View Details & QR Code** to preview your branded poster

## Download Your TanQR Poster

1. In **Settings → Collection**, open **View Details & QR Code** on your active TanQR method.
2. Review your Lipa Namba, store details, and QR preview.
3. Click **Download TanQR Poster** to save a print-ready image.

Display the poster at your counter, entrance, or payment desk, or share your QR code and Lipa Namba online so customers can pay.

## Managing Your Lipa Namba

* **View your Lipa Namba** anytime under **Settings → Collection**.
* **Toggle the method** on or off using the switch next to TANQR - Lipa Namba.
* **Track payments** in your dashboard transactions list like any other ClickPesa collection.

## Need Help?

Contact [support@clickpesa.com](mailto:support@clickpesa.com) for activation issues, pilot access, or questions about your Lipa Namba registration.


# TanQR/Lipa Namba FAQ
Source: https://docs.clickpesa.com/tan-qr/tan-qr-faq

Frequently asked questions about TanQR/Lipa Namba

[What is TanQR/Lipa Namba?](#)

**A:** TanQR/Lipa Namba gives your business a Lipa Namba and QR code for collecting payments. Customers can scan your QR code or pay using your Lipa Namba through mobile money USSD menus and bank channels. It is powered by **TIPS**, with all MNOs and banks integrated.

***

[Is TanQR/Lipa Namba the same as BillPay?](#)

**A:** No. Use **TanQR/Lipa Namba** when customers scan your QR code or pay using your Lipa Namba through USSD and bank channels. Use **[BillPay](/bill-pay/bill-pay-overview)** when customers pay with control numbers for deposits, orders, invoices, or customer-specific references. See the [Integration Guides](/home/integration-overview#tanqr-lipa-namba-vs-billpay) for a full comparison.

***

[Do customers need an app to pay?](#)

**A:** No. Customers can pay using your Lipa Namba through mobile money USSD menus and bank channels without an app. They can also scan your QR code from a mobile money or bank app if they prefer.

***

[Do I need a separate QR code for each MNO or bank?](#)

**A:** No. Your Lipa Namba and QR code work across all MNOs and banks integrated with TIPS.

***

[Does the customer enter the amount?](#)

**A:** Yes. The customer enters the amount and confirms the payment. For amount-specific or automated QR flows, contact [support@clickpesa.com](mailto:support@clickpesa.com).

***

[Where do I find my Lipa Namba after activation?](#)

**A:** Log in to the [Merchant Dashboard](https://merchant.clickpesa.com), go to **Settings → Collection**, and look under **TANQR - Lipa Namba**. Your Lipa Namba is shown when the method is active. You can also open **View Details & QR Code** to see your full registration details and poster.

***

[How do I print or display my QR code?](#)

**A:** After activation, use **View Details & QR Code** in Collection settings and click **Download TanQR Poster**. You can print it for a physical store or share the QR code and Lipa Namba online.

***

[How fast do I receive the money?](#)

**A:** Lipa Namba payments are processed in real time. Successful payments show up immediately in your ClickPesa dashboard and trigger notifications.

***

[What do I need before I can activate Lipa Namba?](#)

**A:** You need completed **KYC**, a filled-in business profile, and payment of the **250,000 TZS activation fee**. See the full [setup guide](/tan-qr/lipa-namba-setup) for step-by-step instructions.

***

[I don't see TanQR in my dashboard. What should I do?](#)

**A:** TanQR/Lipa Namba is available to selected merchants during the rollout. Email [support@clickpesa.com](mailto:support@clickpesa.com) to request access or ask about availability for your account.

***

[Can I use Lipa Namba for online sales?](#)

**A:** Yes. During registration you can choose **Online Store** and provide your store URL. Your Lipa Namba and QR code can be displayed on your website, checkout page, invoice, or shared digitally. For checkout flows that need a fixed amount per order, contact ClickPesa support.


# TanQR/Lipa Namba Overview
Source: https://docs.clickpesa.com/tan-qr/tan-qr-overview

Accept payments with a QR code and Lipa Namba powered by TIPS

**TanQR/Lipa Namba** gives your business one QR code and Lipa Namba for collecting payments. Customers do not need a specific app — they can scan your QR code or pay using your Lipa Namba through mobile money USSD menus and bank channels.

It is powered by **TIPS**, with all MNOs and banks integrated. Customers can pay from any mobile money wallet or bank connected to TIPS. It works for both **physical stores** and **online stores**.

<Note>
  TanQR/Lipa Namba **collection** is paying *you*. To send funds *to* someone else's Lipa Namba or TanQR, use the [Lipa Namba Payout API](/payout-api/lipa-namba-payout-api/lipa-namba-payout-api-overview).
</Note>

<Tip>
  TanQR/Lipa Namba payments are **instant**. Successful payments appear in your [Merchant Dashboard](https://merchant.clickpesa.com) and can trigger [webhook notifications](/home/webhooks) if configured.
</Tip>

## When To Use It

* **Store collections:** Display a QR code or share your Lipa Namba at your counter, kiosk, restaurant, office, or service point.
* **Online collections:** Display or share your QR code and Lipa Namba on your website, checkout page, invoice, or customer message.
* **Simple payments:** Customers enter the amount themselves before confirming payment.
* **Easy setup:** Activate it from the Merchant Dashboard and download a branded poster.

<Info>
  For amount-specific or automated QR flows, contact [support@clickpesa.com](mailto:support@clickpesa.com).
</Info>

## How It Works

1. **Activate** — Enable TanQR/Lipa Namba in your [Merchant Dashboard](https://merchant.clickpesa.com) under **Settings → Collection**.
2. **Display or share** — Print your poster, show your QR code, or share your Lipa Namba.
3. **Customer pays** — The customer scans your QR code or pays using your Lipa Namba through USSD or bank channels, enters the amount, and confirms.
4. **You get paid** — The payment is recorded instantly in your ClickPesa account.

## In the Merchant Dashboard

<CardGroup>
  <Card title="Collection Settings" icon="gear" href="/dashboard/settings/collection">
    Activate TanQR/Lipa Namba and download your QR poster.
  </Card>

  <Card title="Payment Transactions" icon="list" href="/dashboard/transactions/payments">
    View TanQR/Lipa Namba payments in the dashboard.
  </Card>
</CardGroup>

<br />

<CardGroup>
  <Card title="Set Up Lipa Namba" icon="store" href="/tan-qr/lipa-namba-setup">
    Step-by-step guide to activate TanQR/Lipa Namba in the Merchant Dashboard.
  </Card>

  <Card title="Accepting Payments" icon="qrcode" href="/tan-qr/accepting-payments">
    How customers pay using your QR code and Lipa Namba.
  </Card>

  <Card title="TanQR/Lipa Namba FAQ" icon="circle-question" href="/tan-qr/tan-qr-faq">
    Answers to common questions about TanQR/Lipa Namba.
  </Card>
</CardGroup>