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