1. INTRODUCTION

The FLEXPAY API is organised around REST. Our API has predictable resource-oriented URLs,
accepts form-encoded request bodies, returns JSON-encoded responses, uses standard HTTP response
codes, authentication and verbs.
You can use the FLEXPAY API in test mode(https://staging.flexpay.co.ke), which does not affect
your live data or interact with the internal payment networks. The API key you use to authenticate
the request determines whether it is in X live mode or test mode.
The FLEXPAY API may differ for every account as we release new versions and tailor functionality.
This document defines the Service request and response data formats for client requests to Flexpay
servers.

1.1 Overview

Service HTTP – This provides the functionality to push the request to Flexpay Servers by applying
input data over HTTP channel.
This section provides a guide for using the service to post a successful booking, payment checkout
over Http Service Integration

1.2 Transaction Push HTTP-JSON Interface

Request Service – Http Plain Text (SSL SECURED) Response Service –JSON data
Interface Response Error Codes .Troubleshooting

1.3 Push Interfaces

This interface provides a pathway to create {product, customer, booking}, checkout (Store Front
POS and Website) to Flexpay Platform via third party service. It describes the required parameters
and the resource URL for communication.

2. BOOKING A PRODUCT (ONLINE)

Product booking is triggered by an action button that is expected to be added to product details or
product list. It should be an easy way of allowing customers to create a booking (Target) via Flexpay
Platform.
The website developer will need to create a form to capture the parameters that Flexpay Platform
requires to create a successful booking. See the Sample form Below

The following are the parameters required.

Sample Booking Request

Sample Booking Request
curl –location –request POST ‘https://www.flexpay.co.ke/3Api/api/v1/book/flexpay/endpoint’ \
–form ‘apiKey=a511864d-6982-3096-998b-e1a39370111c’ \
–form ‘apiSecret=b0g1WnZNbFVzbWFQOE5ZSHVi’ \
–form ‘productName=Washing Machine’ \
–form ‘productPrice=2’ \
–form ‘phoneNumber=+254729436198’ \
–form ‘productDeposit=1’ \
–form ‘bookingDays=45’ \
–form ‘paymentType=MPESA’ \
–form ’[email protected]’ \
–form ‘firstName=John’ \
–form ‘lastName=Doe’

Upon submission of these parameter via the Flexpay API Transport Link. This will achieve the following.
1. Create Customer: The phone number is the most critical variable since it determines if the customer
will be created or reuse the detail.
2. Create Product: Every request to make a booking generates a new product to Flexpay Platform.
3. Create Booking: The booking will be created/scheduled to accept payments. Bookings made
per day can be viewed from the Flexpay Merchant dashboard.
4. Create Payment Request: A payment request will be made to the payment processor depending
on the payment type selected. Upon payment confirmation, the booking is valid since it has the initial
deposit.
Flexpay will respond to the third-party website with either a Success or Failure message.

The response parameters are as follows.

Sample response JSON Data for inter transactional reference.
{ “data”: {
“message”: “M-PESA initiated successfully. Please input you M-PESA PIN”,
“code”: 200
},
“booking”: {
“Internal_id”: 60334,
“booking_reference”: “ANKY355716”,
“created_date”: “2021-02-24 14:00:53”,
“deadline_date”: “2021-04-10”}}

3. PRODUCT CHECKOUT

Product checkout happens when the customer intends to collect the item he/she has been paying for
from a merchant.
Checkout can be made at the POS or USSD or via Online integration. Implementation is required
for the POS and ONLINE checkout.

3.1 Offline POS (Must have an online connection)

Flexpay has the following critical parameters that your Programmer will provide.

Sample Mock Api
curl –location –request POST ‘https://staging.flexpay.co.ke/3Api/api/v1/booking/validation’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘Cookie: __cfduid=dcfacde0dc9b7ac76267a768437a3dbd21613470170’ \
–form ‘receiptNumber=FROGQHL6330’ \
–form ‘checkoutAmount=25000’ \
–form ‘cashierID=12’ \
–form ‘terminalId=10’ \
–form ‘branchCode=223’ \
–form ‘apiKey=a511864d-6982-3096-998b-e1a39370111c’ \
–form ‘apiSecret=b0g1WnZNbFVzbWFQOE5ZSHVi’

The response to completing the transaction will have the following payload data variables.

{
“status”: 200,
“message”: “Processed Checkout Successfully”,
“data”: {
“customer_name”: “JOSEPHINE”,
“customer_phone_number”: 254729436198,
“available_amount”: 22495,
“required_topup_amount”: 2505,
“receipt_number”: “FROGQHL6330”
}

3.2 Online Checkout (Integration to the website checkout)

This is a new feature that allows the customers to checkout directly online from the payment page
of the e-commerce.
It is authenticated using SMS OTP to confirm the customer who is validating the receipt online.
It has two requests to ensure the phone number passes the auth stage.

3.2.1 1. Request Checkout (Validation of customer).

For a merchant website to request validation checkout, the customer must input the Flexpay Valid
Receipt and the Phone Number Known by Flexpay Platform.
The requirements are as listed below

Sample Online Checkout Request
curl –location –request POST ‘https://staging.flexpay.co.ke/3Api/api/v1/booking/validation/online’
\
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘Cookie: __cfduid=dcfacde0dc9b7ac76267a768437a3dbd21613470170’ \
–form ‘receiptNumber=FROGQHL6330’ \
–form ‘apiKey=a511864d-6982-3096-998b-e1a39370111c’ \
–form ‘apiSecret=b0g1WnZNbFVzbWFQOE5ZSHVi’ \
–form ‘phoneNumber=254729436198’ \
–form ‘checkoutAmount=20000’
The response to the validation request is an OK message with an instruction to access OTP from the
phone. If the number and receipt code match is not found, variable data will be false.

{
“status”: 200,
“message”: “We have initiated an OTP/SMS to 254729XXXXXX”,
“data”: true
}

3.2.2 2.Request Checkout (Confirmation via OTP).

curl –location –request POST ‘https://staging.flexpay.co.ke/3Api/api/v1/booking/validation/otp’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘Cookie: __cfduid=dcfacde0dc9b7ac76267a768437a3dbd21613470170’ \
–form ‘otp=6875’ \
–form ‘apiKey=a511864d-6982-3096-998b-e1a39370111c’ \
–form ‘apiSecret=b0g1WnZNbFVzbWFQOE5ZSHVi’ \
–form ‘phoneNumber=254729436198’

The customer is expected to input the ONE TIME PIN sent to the mobile phone via SMS. This will
be authenticated to confirm the settlement to the Merchant Website.

The successful response will be as follows.

{
“status”: 200,
“message”: “Processed Checkout Successfully”,
“data”: {
“customer_name”: “JOSEPHINE”,
“customer_phone_number”: 254729436198,
“available_amount”: “20000”,
“required_topup_amount”: 0,
“receipt_number”: “FROGQHL6330”
}
}

4. CHECKOUT INVOICE REQUEST.

Checkout Invoice listener is a request made by merchant website or offline POS to give Flexpay the
last communication, thereby sharing the invoice number or Slip Number. This is important as it
provides the finance team with the product receipt
number required for payment reconciliation and settlement.
The request confirmation has the following parameters.

Sample Request
curl –location –request POST ‘https://staging.flexpay.co.ke/3Api/api/v1/booking/validation/ipn’ \
–header ‘Content-Type: application/x-www-form-urlencoded’ \
–header ‘Cookie: __cfduid=dcfacde0dc9b7ac76267a768437a3dbd21613470170’ \
–form ‘receiptNumber=FROGQHL6330’ \
–form ‘slipNumber=Slip_004544_2021’ \
–form ‘apiKey=a511864d-6982-3096-998b-e1a39370111c’ \
–form ‘apiSecret=b0g1WnZNbFVzbWFQOE5ZSHVi’

To close this conversation, Flexpay Platform will always issue an OK response (code 200). The
variable data can be true for success or False for failure.

{
“status”: 200,
“message”: “OK”,
“data”: false
}

5. COMPLETION LISTENER (WEB HOOK)

Some Online Merchants prefer to get feedback on the Completion of the products to arrange the
products’ delivery.
This can only be monitored if the merchant website stored the booking request as an order. Flexpay
will broadcast asynchronous notification to the provided delivery URL;
NB: You are required to share the web Hook URL with our technical team for registration.
The parameters provided include customer details, payment details, and booking details. They are
segmented as Independent JSON objects for quick understanding and processing by the developer.

Sent Data example

{
“booking_id”:1002,
“booking_code”:”PD22332PO”,
“booking_amount”:”2000″,
“product_name”:”Lenovo Laptop”,
“booking_date”:”2021-02-25″,
“booking_receipt”:”FK233333TM”,
“merchant”:”MRS JANE SHOP”,
“merchant_outlet”:”ONLINE STORE”,
“customer”:{
“customer_name1”:”JOHN “,
“customer_name2″:”DOE”,
“customer_phone”:”254700000000″
},
“payment”:{
“totalPaidAmount”:2000,
“lastPaymentPaid”:20,
“payment_date”:”2021-02-25″
}
}

END

6. QUESTIONS

FLEXPAY TECHNOLOGIES
P.O. BOX 43844 – 00100
NAIROBI
[email protected]
www.flexpay.co.ke
0736 588800
FLEXPAY flexpay_ke flexpayTechnologies