DEV Community

Neema Adam for ClickPesa

Posted on • Updated on

Sell your products online with one API call; A technical guide to ClickPesa checkout link integration

One of the newest features that we offer at ClickPesa is a checkout page.

ClickPesa's checkout page allows users to create a checkout page from their website or application for their customers to pay for products or services.

Creating a checkout page only takes one API call to ClickPesa and you will receive a checkout URL that can be shared with the customer to collect payments.

Here is what you need...

Base URL:


  orderItems: [
      name: 'Name of your product',
      product_type: 'DIGITAL_PRODUCT or PRODUCT',
      download_file_key: 'URL to file download', //OPTIONAL
      unit: 'unit of this item eg 1pc',
      price: 'price of the product',
      quantity: 'quantity of the product, eg 10',
  orderReference: 'your order reference',
  merchantId: 'your merchant id',
  callbackURL: '', //OPTIONAL
Enter fullscreen mode Exit fullscreen mode

Here is a table to further explain each field that is added to the payload for checkout URL creation


curl --request POST \
  --url \
  --header 'Content-Type: application/json' \
  --data '{
    "orderItems": [
            "name": "Very cool ebook",
            "product_type": "DIGITAL_PRODUCT",
            "download_file_key": "uploads/", //optional
            "unit": "1 pc(s)",
            "price": 25000,
            "quantity": 1
            "name": "Very cool book hardcopy",
            "product_type": "PRODUCT",
            "unit": "1 pc(s)",
            "price": 40000,
            "quantity": 1
    "orderReference": "SHOP0.273114256151528d",
    "merchantId": "5f9beaa89c8d037a9b4f795d",
    "callbackURL":"" //OPTIONAL
Enter fullscreen mode Exit fullscreen mode

The above request will return the following response, which is a unique URL for the order's checkout page:,%22product_type%22:%22DIGITAL_PRODUCT%22,%22download_file_key%22:%22uploads/,%22unit%22:%221%20pc(s)%22,%22price%22:25000,%22quantity%22:1%7D,%7B%22name%22:%22TEST%20Cylinder%22,%22product_type%22:%22PRODUCT%22,%22unit%22:%22100%20pc(s)%22,%22price%22:50000,%22quantity%22:1%7D%5D&merchantID=5f9beaa89c8d037a9b4f795d&subtotal=75000&totalPrice=75000&discount=0&referenceID=SHOP0.273114256151528d
Enter fullscreen mode Exit fullscreen mode

You can then share the URL with a customer via SMS/Email/WhatsApp or any other communication channel you have in place.


You can use services like to shorten the URL before sharing it with your customer. It's free.

When a customer opens the URL, they will get to the checkout page with all the details of the order.

Sreenshot of ClickPesa Checkout Page

Once a customer completes the payment, a notification will be shared via the callback URL added early on the request. The payload to the callback URL will have the following data:

  paymentReference: string, // Payment reference ID in our system
  orderReference: string, // Order reference ID you provided during checkout page creation
  collectedAmount: string, // Amount collected if the transaction is successful
  collectedCurrency: string, // Currency, currently TZS | USD
  message: string, // eg. 'Payment received'
Enter fullscreen mode Exit fullscreen mode

If you don't have a callback URL in place, ClickPesa also provides an administration dashboard that you can use to track all your orders and their payment statuses. It's free!

Contact ClickPesa at to get started. Takes a day max.

Top comments (0)