Jeel Pay Integration

Jeel Pay

Jeel Pay is a “Study Now Pay Later” platform that allows educational entities to offer its services in installments for parents and other beneficiaries making it easy to pay and track tuition fees. Jeel Pay allows schools to focus on the educational and academic domain while the collection and of fees is handled by Jeel. The platform provides APIs for schools and school marketplace platforms to utilize the features thus increasing growth and expand business operations completely hassle-free.

Each academic semester is split into 4 payments for the parent and the school will receive the full seat cost at the start of the semester.

Features

Inquire about a customer’s eligibility, cost breakdown, number of installments and last payment date.
Request an installment request for a customer.
Redirects to merchant websites after confirmation with result.
Webhooks “Notifications” when the request status changes (Approved, Rejected) by customer.
Webhooks to block the beneficiary certificate in case of defaulted payments.
View the details of a specific installment request.

Checkout Types

There are two types of checkouts in Jeel Pay:

API Checkout
Dashboard Checkout

API Checkout

The API checkout is a checkout initiated from the API integration. API checkouts receive webhooks for the whole cycle of the installment request.

In the webhook body, the checkoutType property will have the value of: API.

Business Flow

This section explains the sequence and business flow between the systems in the API checkout phase:

Merchant website inquire about the customer’s eligibility, cost breakdown from Jeel.
Merchant website will display the cost breakdown and installment details to the customer if they wish to choose Jeel as an installment provider.
The customer selects Jeel then the merchant server create a checkout with Jeel.
The merchant site redirects the customer to Jeel checkout platform to finish the KYC and completes the downpayment.
Jeel Site will redirect the customer to the merchant site with the result.
Jeel Server will also send a webhook to merchant server to confirm the same result.

Below is a sequence diagram that illustrates the above

Dashboard Checkout

Dashboard checkouts are checkouts initiated from the entity dashboard directly and not using the API. Unlike the API Checkout, you'll receive a webhook only for SUCCEEDED checkouts only.

After you receive the webhook, you can get the details of installment request using the endpoint /v1/installment-requests/{id} - Get an installment request by ID.

Installment Request Statuses

The status of the installment request changes throughout the lifetime of the request. The below diagrams explains the statuses installment requests go through.

SUBMITTED: This is the status of a newly created installment request.
CUSTOMER_APPROVED: Once the user accepts our agreement, the status of the installment request will change to CUSTOMER_APPROVED.
CUSTOMER_REJECTED: When the user rejects our agreement, we close the request with the status of CUSTOMER_REJECTED.
CUSTOMER_CANCELLED: When the user cancels the request through the cancel button when he gets directed to our checkout page, we close the request with the status of CUSTOMER_CANCELLED.
EXPIRED: When the installment request is created and left without any action on it for more than 30 minutes, we close it with the status of EXPIRED.
SUCCEEDED: When the user accepts our agreement and pays the down payment, we create an installment plan for the user and the installment request get closed with the status of SUCCEEDED.

API Authentication

Jeel APIs follows OAuth 2.1 for API authentication and authorization. Client Credentials flow will be used to authenticate by providing the authorization server with client id and secret to obtain a token for API usage.

The diagram below explains the flow

A sample HTTP request to get an access token:

Sandbox:

POST /oauth2/token HTTP/1.1
Host: auth.sandbox.jeel.co
Content-Type: application/x-www-form-urlencoded
 
client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=client_credentials

Production:

POST /oauth2/token HTTP/1.1
Host: auth.jeel.co
Content-Type: application/x-www-form-urlencoded
 
client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=client_credentials

A sample response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{"access_token":"eyJraWQiOiJkMWZhOWEwOS0wOGIxLTRlMTktYWUzNC1kZGU0OWQ2MmNlNzkiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwNDJkMzAzYy1kZGVlLTQ1YjgtYTNmNy1kZDc1ZWUyMjY0ZjciLCJhdWQiOiJFQ1dzdUtXWkh2ZFNZQnlVdFp3NGI2YjNRNVlJSjVSQ2RyXzdsTFFra0g4IiwibmJmIjoxNjkyNDgyMDcyLCJtb2JpbGVOdW1iZXIiOiJTeXN0ZW0iLCJyb2xlcyI6WyJFWFRFUk5BTF9BUEkiXSwiaXNzIjoiaHR0cHM6Ly9hdXRoLnNhbmRib3guamVlbC5jbyIsImNsaWVudCI6IkplZWwgZGVtbyIsImV4cCI6MTY5MjQ4MjM3MiwiaWF0IjoxNjkyNDgyMDcyfQ.smuItOKuE-pR5AO8xhXc8E9tTmJA0rq4y3lyc7vIJKgsaNGatX4nUDAY3nc-5jHS0VQjUHzVAG0nagxsgVMnwWcMDwsCqJKoKW0GcBO0P3ZxXmrSRahvgY2oUivCGzXpNbypwmK9N8WdaBb_9saH9k2dZWsCxkcXxNAkOdEpJWg1ZG12OI_o2bJ9ziQYzuPz4ExpqN6A0SW4vfiwb8ST3O6ib8cioUIIeUpoPedtWTgkehxJSLJ6DVhs3nyBCNhgfKeX7U3F5iSfXSlN7T0VgDC4oJ_HokeoBDgINzp1mH6CMpEJFCS-WpzJI1rLyCeVEd6PLytJnzR-Qp557KwVRQ","token_type":"Bearer","expires_in":299}

Webhooks Signature

The X-Jeel-Signature header is a security measure used in webhook responses to guarantee that the data received is from our platform and has not been tampered with during transit. It is created using the HMAC (Hash-based Message Authentication Code) algorithm with base64 encoding, using the clientSecretKey as the secret key and the webhook body json as the message. The header is then added to each webhook request, allowing you to verify the integrity of the received data.

Webhook Body

The webhook body you'll receive contains the installment request ID and the new status of it.

Checkout types: API and DASHBOARD

{
  "id": "9e79d502-231d-449b-b419-a674b687df51",
  "status": "SUCCEEDED",
  "checkoutType": "DASHBOARD"
}

Examples on Calculating the Signature:

Java:

private String calculateSignature(String clientSecretKey, WebhookDto webhookBody) {
  Gson gson = new Gson();
  return Base64Utils.encodeToString(
      new HmacUtils(HmacAlgorithms.HMAC_SHA_256, clientSecretKey).hmac(gson.toJson(webhookBody))
    );
}

PHP:

function calculateSignature($clientSecretKey, $webhookBody) {
  $jsonData = json_encode($webhookBody);
  $signature = base64_encode(hash_hmac('sha256', $jsonData, $clientSecretKey, true));
  return $signature;
}

JavaScript:

function calculateSignature(clientSecretKey, webhookBody) {
  const hmac = crypto.createHmac('sha256', clientSecretKey);
  hmac.update(JSON.stringify(webhookBody));
  return Base64.encode(hmac.digest());
}