Guides & Tutorials
Jenga API
Receive Money
Payment Link as API

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:

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

Interface Definition

Interface IDpaymentAsAPis
Version1.0
Interface TypeREST/JSON
ModeSynchronous
MethodPOST
Endpoint/api/v1/create/payment-link
DescriptionCreate Payment Link using API

Data Architecture

Field NameTypeDescriptionMandatory
customers[0].firstNameStringFirst Name of the customerYes
customers[0].lastNameStringLast Name of the customerYes
customers[0].emailStringCustomer EmailYes
customers[0].firstAddressStringPhysical Address (Optional)No
customers[0].countryCodeStringAlpha-2-country code (e.g., KE for Kenya)Yes
customers[0].postalOrZipCodeStringPostal or Zip Code (Optional)No
customers[0].customerExternalRefStringUnique identifier for customerNo
paymentLink.expiryDateStringLink Expiry date format (yyyy-MM-dd)Yes
paymentLink.saleDateStringDate service or product offered (yyyy-MM-dd)Yes
paymentLink.saleTypeStringType of sale: SERVICE or PRODUCTYes
paymentLink.paymentLinkTypeStringEither SINGLE or BULKYes
paymentLink.nameStringName of product or ServiceYes
paymentLink.descriptionStringDescription of service or productYes
paymentLink.externalRefStringThird Party referenceYes
paymentLink.paymentLinkRefStringLink reference (used for updating link details)No
paymentLink.redirectURLStringWebsite URL to redirect to on successful paymentNo
paymentLink.amountOptionStringOPEN (allow change amount) or RESTRICTED (disallow change)Yes
paymentLink.amountDoublePayment Link amountYes
notifications[]Array of StringsModes for customer to receive payment link: SMS or EMAILNo

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
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 CodeError Description
400Payment already completed for this Link, editing of this payment link is not allowed.