# Jeel Pay Integration - V2 (deprecated soon)

## Jeel Pay <a href="#jeelintegration-jeelpay" id="jeelintegration-jeelpay"></a>

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 <a href="#jeelintegration-features" id="jeelintegration-features"></a>

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

## Checkout Types <a href="#jeelintegration-directintegration" id="jeelintegration-directintegration"></a>

There are two types of checkouts in Jeel Pay:

1. API Checkout
2. 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 <a href="#jeelintegration-businessflow" id="jeelintegration-businessflow"></a>

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

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

Below is a sequence diagram that illustrates the above

<figure><img src="/files/WGnyWt3lXfuKjsJwiKUX" alt=""><figcaption><p>API Checkout</p></figcaption></figure>

### 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.`

<figure><img src="/files/GTy935Ug9BorSPIcsWBD" alt=""><figcaption><p>Dashboard Checkout</p></figcaption></figure>

## Installment Request Statuses  <a href="#jeelintegration-installmentrequeststatusdiagram" id="jeelintegration-installmentrequeststatusdiagram"></a>

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

<figure><img src="/files/MTqOk8llkdAyZqqrsegi" alt=""><figcaption><p>Statuses with a red and green backgrounds are final statuses.</p></figcaption></figure>

* `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 <a href="#jeelintegration-apiauthentication" id="jeelintegration-apiauthentication"></a>

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

<figure><img src="/files/M78v4CQCYX6vSlbPphqR" alt=""><figcaption></figcaption></figure>

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`

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

### **Examples on Calculating the Signature:**

#### Java:

<pre class="language-java"><code class="lang-java"><strong>private String calculateSignature(String clientSecretKey, WebhookDto webhookBody) {
</strong>  Gson gson = new Gson();
  return Base64Utils.encodeToString(
      new HmacUtils(HmacAlgorithms.HMAC_SHA_256, clientSecretKey).hmac(gson.toJson(webhookBody))
    );
}
</code></pre>

#### PHP:

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

#### JavaScript:

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

## Checkout

### Testing Card

<table><thead><tr><th> </th><th width="216">Card Number</th><th>Date</th><th>CVV</th></tr></thead><tbody><tr><td>Visa</td><td>4111111111111111</td><td>05/28</td><td>123</td></tr></tbody></table>

### Note: The credentials used as a phone number and national ID must be valid. <a href="#jeelintegration-examples" id="jeelintegration-examples"></a>

## API Documentation <a href="#jeelintegration-examples" id="jeelintegration-examples"></a>

{% embed url="<https://api.sandbox.jeel.co/docs>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jeel.co/deprecating-soon/jeel-pay-integration-v2-deprecated-soon.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.