ClickPesa Tech

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

neicore's photo
neicore
·

2 min read

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: https://sandbox.clickpesa.com/webshop/generate-checkout-url

Payload:

{
  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: 'https://your_callback_url.com', //OPTIONAL
}

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

Example:

curl --request POST \
  --url https://sandbox.clickpesa.com/webshop/generate-checkout-url \
  --header 'Content-Type: application/json' \
  --data '{
    "orderItems": [
        {
            "name": "Very cool ebook",
            "product_type": "DIGITAL_PRODUCT",
            "download_file_key": "uploads/c0f5a69d-28e8-434c-93ae-0e9dab972bb0.zip", //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":"http://hertha.biz" //OPTIONAL
}'

The above request will return the following response, which is a unique URL for the order's checkout page:

https://demo.checkout.clickpesa.com/checkout?serviceID=88&cartItemsCount=2&items=%5B%7B%22name%22:%22DIGITAL%20product%20THis%20Is%20a%20long%20lng%20test%20Maybe%20it%20is%22,%22product_type%22:%22DIGITAL_PRODUCT%22,%22download_file_key%22:%22uploads/c0f5a69d-28e8-434c-93ae-0e9dab972bb0.zip%22,%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

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

PRO TIP:
You can use services like https://www.shorturl.at 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.

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:

{
  status: 'SUCCESS' | 'PROCESSING' | 'FAILED' | 'CANCELED',
  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'
}

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.

ClickPesacheckouttanzaniatanzania