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

Live URL

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

Data Architecture

Sample Requests

Example HTTP Headers Request

Signature

paymentLink.expiryDate+paymentLink.amount+paymentLink.currency+paymentLink.amountOption+paymentLink.externalRef

POST /v3-apis/payment-api/v3.0/payment-link/create
Content-Type: application/json
Authorization: Bearer {{access_token}}
Signature: {{ generated_signature }}

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": "Kliff",
            "lastName": "Sed",
            "email": "kliff.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

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

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

Error Codes

Error Responses

400 Bad Request

Missing or invalid parameters in the request body.

{
  "status": false,
  "code": 400,
  "message": "Invalid request parameters",
  "error_code": "INVALID_REQUEST"
}

401 Unauthorized

Invalid or expired access token.

{
  "status": false,
  "code": 401,
  "message": "Invalid or expired access token",
  "error_code": "UNAUTHORIZED"
}

403 Forbidden

Valid credentials but invalid signature or insufficient permissions.

{
  "status": false,
  "code": 403,
  "message": "Invalid signature or insufficient permissions",
  "error_code": "FORBIDDEN"
}

404 Not Found

Account not found or invalid account number.

{
  "status": false,
  "code": 404,
  "message": "Source or destination account not found",
  "error_code": "ACCOUNT_NOT_FOUND"
}

Transaction Status Errors

📖 Step-by-Step Guide

Step 1: 🔑 Set Up Security Keys

Generate your private and public key pair and share your public key with Finserve. See the Security & Signatures Documentation (opens in a new tab) for detailed instructions.

Step 2: 🎫 Authenticate

Obtain an access token using the authentication endpoint. See the Authentication API documentation (opens in a new tab) for details.

Step 3: 📋 Prepare Transaction Details

Gather all required information.

Step 4: ✍️ Generate Signature

Create the signature string by concatenating in this exact order:

paymentLink.expiryDate+paymentLink.amount+paymentLink.currency+paymentLink.amountOption+paymentLink.externalRef

Sign this string using your private key, then Base64 encode the result.

Step 5: 📝 Set Up Headers

Include the following headers in your request:

• Content-Type: application/json
• Authorization: Bearer [your_access_token]
• Signature: [your_base64_encoded_signature]

Step 6: 🔧 Construct Request Body

Create a JSON object with all required fields following the structure shown in the example request.

Step 7: 🚀 Send POST Request

Make a POST request to the internal bank transfer endpoint with your headers and body.

🌍 Supported Countries & Currencies

Best Practices

1. ** Security**

   • Store your private key securely and never expose it in client-side code or version control
   • Always use HTTPS for API requests
   • Store access tokens securely
   • Regenerate signatures for each request

2. ** Signature Generation**

   • Ensure exact string concatenation order: paymentLink.expiryDate+paymentLink.amount+paymentLink.currency+paymentLink.amountOption+paymentLink.externalRef
   • Do not include spaces, separators, or special characters in the concatenated string
   • Always Base64 encode the signature before including it in headers
   • Verify the values in the signature match exactly with the request body values

3. ** Transaction Reference**

   • Use unique reference numbers for each transaction
   • Implement a reference generation system to avoid duplicates
   • Store reference numbers for reconciliation and audit purposes
   • Never reuse reference numbers, even for failed transactions

4. Amount Formatting

   • Always use decimal format with two decimal places (e.g., "500.00")
   • Pass amounts as strings, not numbers
   • Ensure the amount is positive and within allowed limits
   • Verify amount matches exactly in signature and request body

5. Error Handling

   • Implement retry logic with exponential backoff for transient errors
   • Log transaction attempts and responses for audit purposes
   • Handle signature validation errors by regenerating the signature

6. Testing

   • Always test with the UAT endpoint before using the live endpoint
   • Use test account numbers provided in the documentation
   • Verify signature generation with sample data first
   • Test error scenarios to ensure proper handling

7. Data Validation

   • Validate all account numbers match the expected format
   • Verify country codes are valid and supported
   • Ensure transfer dates are in the correct format (YYYY-MM-DD)
   • Validate currency codes match the destination country

Troubleshooting

Invalid Signature Error (403)

If you receive a 403 error with "Invalid signature":

1. Verify the concatenation order: paymentLink.expiryDate+paymentLink.amount+paymentLink.currency+paymentLink.amountOption+paymentLink.externalRef
2. Ensure no spaces or separators are included in the concatenated string
3. Check that the signature is Base64 encoded
4. Verify your public key is correctly registered with us
5. Ensure the values in the signature match exactly with the request body values

Common Signature Mistakes

• Using wrong concatenation order
• Adding spaces or separators between values
• Not Base64 encoding the final signature
• Values in signature don't match request body values

Support

For questions or issues with this API:

• Email: support@finserve.africa