Jambopay

JamboPay uses bearer token authentication for API requests. All API communication must include an Authorization header with a valid bearer token.

Obtaining Bearer Token

# Request a token from the Token endpoint
curl -X POST https://api.checkoutv3.jambopay.com/Token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

API Request Headers

Include the bearer token in all API requests:

curl -X POST https://api.checkoutv3.jambopay.com/payment/request \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Environment-Specific URLs

Merchant Credentials

You'll need the following credentials from your JamboPay merchant account:

• ClientKey: Unique identifier for your merchant application
• BusinessEmail: Email address registered with JamboPay
• Bearer Token: Obtained via the Token endpoint (see above)

Core API Reference

1. Initiate Payment / Payment Request

Initiate a payment transaction that can be processed via Express Checkout or Redirect Checkout.

Endpoint: POST /payment/request

Request Body:

{
  "orderId": "ORDER-12345",
  "customerEmail": "[email protected]",
  "customerPhone": "+254712345678",
  "currency": "KES",
  "orderAmount": 5000.00,
  "businessEmail": "[email protected]",
  "clientKey": "YOUR_CLIENT_KEY",
  "callbackUrl": "https://yoursite.com/payment/callback",
  "cancelledUrl": "https://yoursite.com/payment/cancelled",
  "description": "Purchase of Product XYZ",
  "storeName": "Your Store Name",
  "supportEmail": "[email protected]",
  "supportPhone": "+254712345678",
  "useJPLogo": true
}

Response:

{
  "orderId": "ORDER-12345",
  "checkoutUrl": "https://checkout.jambopay.com/pay/ORDER-12345",
  "merchantReference": "JAMBOPAY-ORDER-12345",
  "status": "PENDING",
  "amount": 5000.00,
  "currency": "KES"
}

2. Query Payment Status

Check the status of a previously initiated payment.

Endpoint: GET /payment/query/{merchantReference}

Request:

curl -X GET "https://api.checkoutv3.jambopay.com/payment/query/JAMBOPAY-ORDER-12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "merchantReference": "JAMBOPAY-ORDER-12345",
  "orderId": "ORDER-12345",
  "status": "COMPLETED",
  "amount": 5000.00,
  "currency": "KES",
  "paymentMethod": "MPESA",
  "transactionId": "MPESA-TRANS-123456",
  "processedDate": "2024-02-24T14:30:00Z",
  "customerPhone": "+254712345678"
}

3. Refund Transaction

Refund a completed payment transaction.

Endpoint: POST /payment/refund

Request Body:

{
  "merchantReference": "JAMBOPAY-ORDER-12345",
  "refundAmount": 5000.00,
  "reason": "Customer requested cancellation",
  "refundReference": "REFUND-12345"
}

Response:

{
  "refundReference": "REFUND-12345",
  "merchantReference": "JAMBOPAY-ORDER-12345",
  "refundAmount": 5000.00,
  "status": "PROCESSING",
  "processedDate": "2024-02-24T14:35:00Z"
}

Integration Methods

Express Checkout (Embedded)

Customer completes payment within your website using an embedded form or iframe. Requires additional frontend integration with JamboPay's payment widgets.

Advantages:

• Better conversion rates (no redirect)
• Full UI control
• Faster checkout experience

Implementation:

<!-- Include JamboPay checkout script -->
<script src="https://checkout.jambopay.com/js/checkout.js"></script>

<!-- Checkout container -->
<div id="jambopay-checkout"></div>

<script>
  var checkout = new JamboPay({
    merchantKey: "YOUR_CLIENT_KEY",
    orderId: "ORDER-12345",
    amount: 5000,
    email: "[email protected]",
    phone: "+254712345678",
    currency: "KES",
    onSuccess: function(data) {
      console.log("Payment successful:", data);
    },
    onError: function(error) {
      console.error("Payment failed:", error);
    }
  });

  checkout.render("#jambopay-checkout");
</script>

Redirect Checkout

Customer is redirected to JamboPay's hosted payment page. Simpler integration with minimal frontend requirements.

Advantages:

• Simplest integration
• PCI-DSS compliance handled by JamboPay
• No custom payment form needed

Implementation:

// After initiating payment via API and receiving checkoutUrl
window.location.href = response.checkoutUrl;

Webhooks and Callbacks

JamboPay sends payment notifications to your callback URL via Instant Payment Notification (IPN).

Callback Configuration

Configure your callback URL in the JamboPay merchant dashboard:

1. Log in to JamboPay Client Portal
2. Navigate to Settings/Integrations
3. Set your Callback URL and Cancel URL

IPN Callback Payload

JamboPay sends a POST request to your callback URL with the following structure:

{
  "merchantReference": "JAMBOPAY-ORDER-12345",
  "orderId": "ORDER-12345",
  "status": "COMPLETED",
  "amount": 5000.00,
  "currency": "KES",
  "paymentMethod": "MPESA",
  "transactionId": "MPESA-TXN-123456789",
  "customerPhone": "+254712345678",
  "customerEmail": "[email protected]",
  "processedDate": "2024-02-24T14:30:00Z",
  "description": "Purchase of Product XYZ",
  "metadata": {
    "customField1": "value1"
  }
}

Handling Callbacks Securely

Best Practices:

1. Always validate the callback is from JamboPay (implement signature verification if available)
2. Log all callbacks for auditing
3. Return HTTP 200 immediately upon receipt
4. Process payment asynchronously (don't hold the callback response)
5. Implement idempotency to handle duplicate callbacks
6. Never rely solely on callbacks—always query the payment status

Example Node.js Handler:

app.post('/payment/callback', (req, res) => {
  const payload = req.body;

  // Log for auditing
  console.log('Callback received:', payload);

  // Return 200 immediately
  res.status(200).json({ status: 'received' });

  // Process payment asynchronously
  processPayment(payload).catch(error => {
    console.error('Callback processing error:', error);
    // Retry logic here
  });
});

async function processPayment(payload) {
  // Verify payment with query endpoint
  const status = await queryPaymentStatus(payload.merchantReference);

  if (status === 'COMPLETED') {
    // Update order in your database
    await updateOrderStatus(payload.orderId, 'PAID');
    // Send confirmation email
    await sendConfirmationEmail(payload.customerEmail);
  }
}

Cancelled Payment Callback

When a customer cancels a transaction, JamboPay redirects to the cancelledUrl with parameters: