Payment Link as API – Jenga Docs

Create Payment Link API

Merchants using Jenga services can create payment links programmatically via API. This API allows merchants to generate payment links and send them to customers via specified notification methods such as SMS or email.

Test URL

POSThttps://uat.finserve.africa/api-checkout/api/v1/create/payment-link

Live URL

POSThttps://api.finserve.africa/api-checkout/api/v1/create/payment-link

Description of the sequence:

Merchant generates a JWT token from Jenga using credentials provided on Jenga HQ (Merchant Portal).
Merchant calls Jenga's API Checkout Service (api-checkout-service) to create the payment link and specify notification options.
api-checkout-service sends an email or SMS to the customer based on the specified notification method.
The customer receives an SMS or email containing the payment link.
The customer clicks the payment link and is redirected to a payment form to confirm details.
Upon confirming payment details, the customer proceeds with the payment.
Upon successful or failed payment, the IPN service sends a callback to the merchant via the registered URL on Jenga HQ.

Interface Definition

Interface ID	paymentAsAPis
Version	1.0
Interface Type	REST/JSON
Mode	Synchronous
Method	POST
Endpoint	/api/v1/create/payment-link
Description	Create Payment Link using API

Data Architecture

Field Name	Type	Description	Mandatory
customers[0].firstName	String	First Name of the customer	Yes
customers[0].lastName	String	Last Name of the customer	Yes
customers[0].email	String	Customer Email	Yes
customers[0].firstAddress	String	Physical Address (Optional)	No
customers[0].countryCode	String	Alpha-2-country code (e.g., KE for Kenya)	Yes
customers[0].postalOrZipCode	String	Postal or Zip Code (Optional)	No
customers[0].customerExternalRef	String	Unique identifier for customer	No
paymentLink.expiryDate	String	Link Expiry date format (yyyy-MM-dd)	Yes
paymentLink.saleDate	String	Date service or product offered (yyyy-MM-dd)	Yes
paymentLink.saleType	String	Type of sale: SERVICE or PRODUCT	Yes
paymentLink.paymentLinkType	String	Either SINGLE or BULK	Yes
paymentLink.name	String	Name of product or Service	Yes
paymentLink.description	String	Description of service or product	Yes
paymentLink.externalRef	String	Third Party reference	Yes
paymentLink.paymentLinkRef	String	Link reference (used for updating link details)	No
paymentLink.redirectURL	String	Website URL to redirect to on successful payment	No
paymentLink.amountOption	String	OPEN (allow change amount) or RESTRICTED (disallow change)	Yes
paymentLink.amount	Double	Payment Link amount	Yes
notifications[]	Array of Strings	Modes for customer to receive payment link: SMS or EMAIL	No

Sample Requests

Example HTTP Headers Request

⚠️

In the example below, replace placeholders like {{ access_token }}, {{callBackUrl}}, and other variables with actual values.

Http Headers Example Request

POST /v3-apis/payment-api/v3.0/payment-link/create
Content-Type: application/json
Authorization: Bearer {{access_token}}
Signature: paymentLink.expiryDate, paymentLink.amount, paymentLink.currency, paymentLink.amountOption, paymentLink.externalRef

Single Payment Link Sample Body Request

{
    "customers": [
        {
            "firstName": "John",
            "lastName": "Doe",
            "email": "johndoe902@gmail.com",
            "phoneNumber": "254764848636",
            "firstAddress": "",
            "countryCode": "KE",
            "postalOrZipCode": "00100",
            "customerExternalRef": "575657788779"
        }
    ],
    "paymentLink": {
        "expiryDate": "2024-03-22",
        "saleDate": "2024-02-20",
        "paymentLinkType": "SINGLE",
        "saleType": "SERVICE",
        "name": "Hotel Reservation",
        "description": "Hotel Reservation",
        "externalRef": "575657788779",
        "paymentLinkRef": "",
        "redirectURL": "https://v3.jengahq.io",
        "amountOption": "OPEN",
        "amount": 400,
        "currency": "KES"
    },
    "notifications": [
        "EMAIL",
        "SMS"
    ]
}

Bulk Payment Link Sample Request

{
    "customers": [
        {
            "firstName": "John",
            "lastName": "Doe",
            "email": "johndoe902@gmail.com",
            "phoneNumber": "254764848636",
            "firstAddress": "",
            "countryCode": "KE",
            "postalOrZipCode": "00100",
            "customerExternalRef": "8398932700111222"
        },
        {
            "firstName": "Cliff",
            "lastName": "Sed",
            "email": "cliff.sed@equitybank.co.ke",
            "phoneNumber": "254722577556",
            "firstAddress": "",
            "countryCode": "KE",
            "postalOrZipCode": "00100",
            "customerExternalRef": "839893272262515252"
        }
    ],
    "paymentLink": {
        "expiryDate": "2024-03-22",
        "saleDate": "2024-02-20",
        "paymentLinkType": "BULK",
        "saleType": "SERVICE",
        "name": "Finserve Hotel Reservations",
        "description": "Finserve Hotel Reservations",
        "externalRef": "46276268228728722",
        "paymentLinkRef": "",
        "redirectURL": "https://v3.jengahq.io",
        "amountOption": "OPEN",
        "amount": 500,
        "currency": "KES"
    },
    "notifications": [
        "EMAIL",
        "SMS"
    ]
}

Responses

Success Response

{
    "status": true,
    "code": 200,
    "message": "Payment link successfully generated",
    "metadata": {},
    "data": {
        "dateCreated": 1709277210697,
        "paymentLinkRef": "456175577507808",
        "externalRef": "565657788779",
        "status": {
            "code": "PEND",
            "name": "Pending"
        }
    }
}

Error Response

{
    "status": false,
    "code": 400,
    "message": "Payment already completed for this Link, editing of this payment link is not allowed",
    "metadata": {}
}

Error Codes

Error Code	Error Description
400	Payment already completed for this Link, editing of this payment link is not allowed.

Equitel Stk Ussd Push Eazzy Pay Merchants