Sell your products online with one API call; A technical guide to ClickPesa checkout link integration
Tags: javascript, webdev, tutorial
Published: 2023-06-14 17:17:35

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

Payload:

```jsx
{
  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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1686763419975/25aff0e7-4205-4638-8ba9-427a713a408d.png align="center")

Example:

```bash
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:

```bash
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](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.

![Sreenshot of ClickPesa Checkout Page](https://cdn.hashnode.com/res/hashnode/image/upload/v1686906996755/75af6119-0c4a-41a0-a6f1-c1450c76f3cb.png)

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:

```typescript
{
  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 info@clickpesa.com to get started. Takes a day max.