Pilon Recharge Api V1.0

Introduction

Pilon works with partners to digitalise their business processes and enhance their financing with technology. Pilon has
since developed a suite of products for the banks, supply chain operators (logistics sector) and now to companies who
like to provide salary advancement to their staff.

Understanding that lending is both art and science, we enhance the lending process with science by providing a more
secure and faster turn time around for companies to unlock their invoices for cash that has been held back by
contractual credit terms.

This Api documentation will help developers to integrate our api to their own platform who already have their existing login
process for their users or employees.

For safe integration please follow this Api Connection Diagram.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd"  
  -H 'Content-Type: application/json'

Recharge uses API keys to allow access to the API.

Recharge expects for the API key to be included in all API requests to the server in a header that looks like the
following:

API-KEY: MY-API-KEY

You must replace MY-API-KEY with your personal Api Key provided by Pilon.

Employee

Create Employee

Pilon Recharge needs to white list or pre-approved the employees in the system before they can login using the Pilon
Recharge App.

curl --location --request POST 'URL_BASE/recharge/employee' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd'  --header 'Content-Type: application/json'   --data-raw '{"full_name": "Robertson Downy", "national_id_number": "23123123", "mobile_cc" : "+65", "mobile_no": "12345679", "email_address" : "[email protected]", "date_of_birth" : "2000-01-01", "current_position" : "Developer", "employment_date": "2021-01-01", "employment_type": "1", "payout": 1, "current_salary" : "10000", "net_salary" : "7000", "advancement_ratio": "50%", "bank_name" : "OCBC", "bank_account_no" : "123215123", "bank_account_type" : "Savings", "status" : 1 }'

Response:

{
    "success": true,
    "status": 200,
    "data": {
        "id": "uiD4DR2L477W6PDDJ6PQM8Q",
        "full_name": "Robertson Downy",
        "mobile_cc": "+65",
        "mobile_no": "12345679",
        "email_address": "[email protected]",
        "date_of_birth": "2000-01-01",
        "national_id_number": "23123123",
        "employment_date": "2021-01-01",
        "employment_type": "1",
        "current_position": "Developer",
        "payout": 1,
        "current_salary": "10000",
        "net_salary": "7000",
        "advancement_ratio": 50,
        "credit_limit": 3500,
        "bank_name": "OCBC",
        "bank_account_no": "123215123",
        "bank_account_type": "Savings",
        "status": 1,
        "status_label": "Active"
    }
}

POST /recharge/employee

Request Body

Parameter	Type	Required	Description
full_name	string	true
national_id_number	string	true
mobile_cc	string	true	Allowed: +65
mobile_no	string	true
email_address	string	false
date_of_birth	string	true	Format: YYYY-MM-DD
current_position	string	true
employment_date	string	true	Format: YYYY-MM-DD
employment_type	number	true	1 = Full time, 2 = Part time
payout	number	true	1 = Monthly, 2 = Weekly, 3 = Fortnightly, 4 = Daily
current_salary	string	true	Monthly salary
net_salary	string	true	After all deductions
advancement_ratio	string	true	example: 50%, means max loan will be 50% of `net_salary`
bank_name	string	true
bank_account_no	string	true
bank_account_type	string	true
status	string	true	1 = Active, 2 = Suspended

Get List

curl --location --request GET 'URL_BASE/recharge/employee' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json'

GET /recharge/employee

Response:

{
    "success": true,
    "status": 200,
    "data": {
        "rows": [
            {
                  "id": "uiD4DR2L477W6PDDJ6PQM8Q",
                  "full_name": "Robertson Downy",
                  "mobile_cc": "+65",
                  "mobile_no": "12345679",
                  "email_address": "[email protected]",
                  "date_of_birth": "2000-01-01",
                  "national_id_number": "23123123",
                  "employment_date": "2021-01-01",
                  "employment_type": 1,
                  "current_position": "Developer",
                  "payout": 1,
                  "current_salary": "10000.00",
                  "net_salary": "7000.00",
                  "advancement_ratio": 50,
                  "credit_limit": "3500.00",
                  "bank_name": "OCBC",
                  "bank_account_no": "123215123",
                  "bank_account_type": "Savings",
                  "status": 1,
                  "status_label": "Active"
            } 
        ],
        "pagination": {
            "pageParam": "page",
            "pageSizeParam": "per_page",
            "params": [],
            "totalCount": 1,
            "defaultPageSize": 100,
            "pageSizeLimit": [
                10,
                50,
                100
            ],
            "firstRowNo": 1
        }
    }
}

This endpoint retrieves all employees.

Get Employee

GET /recharge/employee/:ID

curl --location --request GET 'URL_BASE/recharge/employee/uiDY78EZGYYMGYKQGV7K18D' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json'

Response:

{
"success": true,
"status": 200,
"data": {
        "id": "uiD4DR2L477W6PDDJ6PQM8Q",
        "full_name": "Robertson Downy",
        "mobile_cc": "+65",
        "mobile_no": "12345679",
        "email_address": "[email protected]",
        "date_of_birth": "2000-01-01",
        "national_id_number": "23123123",
        "employment_date": "2021-01-01",
        "employment_type": 1,
        "current_position": "Developer",
        "payout": 1,
        "current_salary": "10000.00",
        "net_salary": "7000.00",
        "advancement_ratio": 50,
        "credit_limit": "3500.00",
        "bank_name": "OCBC",
        "bank_account_no": "123215123",
        "bank_account_type": "Savings",
        "status": 1,
        "status_label": "Active"
    }
}

This endpoint retrieve the specific employee

Draw Out Request

Overview

Draw out request is basically the employee’s submitted desired amount for advance payment.

Below diagram must be the flow to safely integrate with the user’s or employee’s app.

Initialize Draw Out Request

curl --location --request POST 'BASE_URL/recharge/request' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json' --data-raw ' { "employee_id": "uiD4DR2L4779K5Y1ZLKMG8Q", "amount" : 100, "transfer_method" : 1 }'

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "id": "uiDE589K2XX1Z43KYL9YL86",
    "created_at": "2022-03-25 16:06:55",
    "updated_at": "2022-03-25 16:06:55",
    "amount": 100,
    "status": 0,
    "status_label": "Draft",
    "transfer_fee_amount": 0.5,
    "platform_fee_rate": "2%",
    "platform_fee_amount": 2,
    "disbursement_amount": 97.5,
    "transfer_method": 1,
    "transfer_method_label": "Fast"
  }
}

POST /recharge/request

Create a draft request to Pilon Recharge that will be submitted later for confirmation

This endpoint will perform validations, and if there are no errors on the submitted values or if the amount is still allowed by credit limit, it will return Request ID and calculated values that needs to be displayed to be confirmed by the employee.

Request Body

Parameter	Type	Required	Description
employee_id	string	true
amount	number	true
transfer_method	number	true	1=Fast, 2=Giro

Update Draw Out Request

curl --location --request PUT 'BASE_URL/recharge/request/uiDE589K2XX1Z43KYL9YL86' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json' --data-raw ' {  "amount" : 100, "transfer_method" : 1 }'

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "id": "uiDE589K2XX1Z43KYL9YL86",
    "created_at": "2022-03-25 16:06:55",
    "updated_at": "2022-03-25 16:46:14",
    "status": 0,
    "status_label": "Draft",
    "transfer_fee_amount": 0.5,
    "platform_fee_rate": "2%",
    "platform_fee_amount": "2.00",
    "disbursement_amount": 117.5,
    "transfer_method": 1,
    "transfer_method_label": "Fast"
  }
}

PUT /recharge/request/:ID

To update the request currently in draft mode. But if the request has been confirmed the request cannot be updated.

Params

Parameter	Type	Required	Description
ID	number	true

Request Body

Parameter	Type	Required	Description
amount	number	true
transfer_method	number	true	1=Fast, 2=Giro

Confirm Draw Out Request

Generate OTP

curl --location --request POST 'URL_BASE/recharge/request/uiDE589K2XX1Z43KYL9YL86/generate-otp' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json'

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "otp_token": "15643651295d36ad6270bc7"
  }
}

POST /recharge/request/:ID/generate-otp

After the employee viewed the calculated details, the client app must provide a Confirm button that should generate an OTP code to be sent to employee’s registered mobile number.

Params

Parameter	Type	Required	Description
ID	number	true	This value must be supplied from the created request.

Confirm

curl --location --request POST 'URL_BASE/recharge/request/uiDE589K2XX1Z43KYL9YL86/confirm' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json'

Example response


{
    "success": true,
    "status": 200,
    "data": {
        "id": "uiDE589K2XX1Z43KYL9YL86",
        "created_at": "2022-03-25 16:06:55",
        "updated_at": "2022-03-25 18:02:50",
        "amount": "120.00",
        "status": 105,
        "status_label": "Processing",
        "transfer_fee_amount": "0.50",
        "platform_fee_rate": "2%",
        "platform_fee_amount": "2.00",
        "disbursement_amount": 117.5,
        "transfer_method": 1,
        "transfer_method_label": "Fast"
    }
}

POST /recharge/request/:ID/confirm

This endpoint will verify the OTP code and update this request to confirmed status, this action will forward the request to Pilon Recharge and be funded immediately.

Params

Parameter	Type	Required	Description
ID	number	true	This value must be supplied from the created request.

Request Body

Parameter	Type	Required	Description
otp_code	number	true
otp_token	number	true	pass the otp_token response from generate otp endpoint.

Get List

curl --location --request GET 'URL_BASE/recharge/request?employee_id=uiD4DR2L477W6PDDJ6PQM8Q' --header 'API-KEY: f8b78ec2-d6e9-4b7f-8c4c-1770f4e733fd' --header 'Content-Type: application/json'

GET /recharge/request

Get the list of requests submitted by the employees.

Query Params

Parameter	Type	Required	Description
employee_id	string	false

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "rows": [
      {
        "id": "uiDJ50N32VWK7XV311VWY0W",
        "created_at": "2022-03-16 18:17:55",
        "submitted_at": "2022-03-16 18:17:57",
        "user_id": "uiDOG85DQ26JXLWK6E4M685",
        "amount": "50.00",
        "tenure": 1,
        "reference_no": "202203161831061",
        "type": 3,
        "type_label": "Recharge Program",
        "status": 106,
        "status_label": "Funded",
        "transfer_fee_amount": "0.50",
        "platform_fee_rate": "2%",
        "platform_fee_amount": "1.00",
        "disbursement_amount": 48.5,
        "transfer_method": 1,
        "transfer_method_label": "Fast"
      }
    ],
    "pagination": {
      "pageParam": "page",
      "pageSizeParam": "per_page",
      "params": [],
      "totalCount": 1,
      "defaultPageSize": 20,
      "pageSizeLimit": [
        10,
        50,
        100
      ],
      "firstRowNo": 1
    }
  }
}

Get Draw Out Request

GET /recharge/request/:ID

Params

Parameter	Type	Required	Description
ID	number	true

Repayment Reports

Retrieve the repayment reports due for payment. This Repayment reports is strictly for admin staff only to view. Do not show to user’s or employee’s app.

Get List

GET /recharge/repayment

Download Statement

GET /recharge/repayment/:ID/download

Params

Parameter	Type	Required	Description
ID	number	true