ClickPesa

Simplyfing payments

Checkout Link

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. 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. 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 transactions is processed, with all transactions easily viewable in the ClickPesa dashboard.

Common Use Cases #

  • 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.

How to Use the Feature #

To use this feature, a merchant has to make sure that they have an account registered at ClickPesa that has full KYC, and that they have activated the checkout link feature in the settings. For testing purposes, merchants can also have a sandbox account that they can use to test and integrate the platform while finalizing registration and KYC with ClickPesa’s compliance team. Once KYC is finalized and the merchant is ready to go live, they can change the URLs and use the live ones.

This guide assumes that you have already set up your ClickPesa account, whether sandbox or live. Here you will see a walkthrough on how to activate the checkout link feature in the settings and how to create a checkout link via the API.

Activating Checkout Link #

Once logged into your ClickPesa dashboard, on the bottom left, there is a Settings, you can click that to open settings page and then select the Checkout Settings tab.

After clicking on the checkout settings, you will be navigated to a page called Checkout Settings which has payment options and if you scroll at the bottom you will see a section about activating the checkout link which you will click.

After activating the Checkout Link feature, you will see a status of active and your merchant ID. You can copy that merchant ID and share it with your developer because it is needed to generate the checkout link. The merchant ID will be available for you to copy anytime you visit this section of Checkout Settings.

Technical Documentation #

Generating Checkout Link #

Endpoint #

  • Method: POST
  • Dev URL: https://sandbox.clickpesa.com/webshop/generate-checkout-url
  • Production URL: https://api.clickpesa.com/webshop/generate-checkout-url

Headers #

  • Content-Type: application/json

Request Body #

The request body should be in JSON format and include the following parameters:

ValueDataDescription
orderItemsArray of Objects
(optional)An array of order items representing products. This property is optional because not every checkout link needs to have orderItems. If you add it then each order item should include the following properties:
  • name (string): The name of the product.
  • product_type (string): The type of product (i.e., PRODUCT).
  • unit (string): The unit of the product (e.g., “pc(s), box(s), kg etc.”).
  • price (number): The price of the product.
  • quantity (number): The quantity of the product. | | totalPrice | Number (not needed if orderItems is available) | Total cost of your product. You don’t need to pass this if you have passed orderItems. It is only required if orderItems is not available. | | orderReference | String | A unique reference or identifier for the order generated by your system. You will need this later to retrieve order information. | | merchantId | String | Your merchant’s ID. It can be found in the Clickpesa dashboard under settings > checkout settings > checkout link | | callbackURL | String (optional) | Callback URL that will receive updates if there is any failed or successful payments. Method should be POST. |

Body Example 1: Checkout link with orderItems

{
	"orderItems": [
		{
			"name": "A very good book",
			"product_type": "PRODUCT",
			"unit": "Book",
			"price": 15000,
			"quantity": 1
		}
	],
	"orderReference": "DOCSTEST1234",
	"merchantId": "your merchant id"
}

Body Example 2: Checkout link without orderItems

{
	"totalPrice": 1500,
	"orderReference": "DOCSTEST1234",
	"merchantId": "your merchant id"
}

Body Example 3: Checkout link with callbackURL

{
	"totalPrice": 1500,
	"orderReference": "DOCSTEST1234",
	"merchantId": "your merchant id",
	"callbackURL": "https:example.com/callback-endpoint" (POST)
}

Callback #

Request when payment is successful #

Expected body for a successful transaction in the callback endpoint

PropertyTypeDescription
idStringService transaction reference. It is a reference ID generated by our system.
statusStringStatus of the payment. We have two states; ‘SUCCESS’ or ‘FAILED’, in this case, it will be ‘SUCCESS’
paymentReferenceStringPayment reference generated by a third-party system that processed the payment, eg. Bank, TIGOPESA, MPESA, etc.
orderReferenceStringOrder reference you submitted during checkout creation.
collectedAmountStringAmount collected
collectedCurrencyStringCurrency of the amount collected
messageStringDescription of the payment status.
customerObjectCustomer object that carries information about the customer who made the payment. The information is name, email, and phone number.

“customer”: { “customerName”: “test”, “customerEmail”: “test@test.com“, “customerPhoneNumber”: “255678000000” } |

JSON Example

{
  "id": "TESTID",
  "status": "SUCCESS",
  "paymentReference": "TESTING",
  "orderReference": "DOCSTEST1234",
  "collectedAmount": "1500",
  "collectedCurrency": "TZS",
  "message": "Payment received successfully.",
  "customer": {
    "customerName": "test",
    "customerEmail": "test@test.com",
    "customerPhoneNumber": "255678000000"
  }
}

Frequently Asked Questions (FAQ) #

Question
I am getting a “Merchant does not exist” error

{
	"message": "Merchant does not exist"
}

Answer
This is likely because you are using a merchant ID with a wrong endpoint. You need to make sure that if the merchant ID you are using is of a live account then the base URL for the checkout generation endpoint should be https://api.clickpesa.com and if it is of a staging/sandbox environment then the base URL should be https://sandbox.clickpesa.com.