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: 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 [e-mail] to get started. Takes a day max.