MPGS - Web

Getting Started

This documentation helps you to integrate with Jenga and process payments for your customers. MPGS - Web offers a single mode of payment integration:

  • Hosted – Redirection

To implement MPGS - Web, follow the following steps;

Step 1: Get an Access token
Step 2: Create a bill
Step 3: Collect customer information
Step 4: Payment Response
Step 5: Verify transaction

Step 1: Get an Access Token

This is the first step before interacting with MPGS - Web. The token generated at this step is used for subsequent interactions. In order to obtain access token, proceed with the API call to the URL /identity/v2/token.

For Example:

POST /identity/v2/token HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
Host: uat.jengahq.io

username=0582910862&password=ce0NHpa7ZaxmOFkbEbULABpu412fS4NQa

Headers

Header

Meaning

Default

Sample

Mandatory

Authorization

Your Jenga API Key

n/a

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

YES

Content-Type

Payload Content Type

application/x-www-form-urlencoded

application/x-www-form-urlencoded

NO

Parameters

Parameter

Meaning

Default

Sample

Mandatory

username

Username, obtained after successful onboarding on the Jenga

n/a

0582910862

YES

password

Password, obtained after successful onboarding on the Jenga

n/a

ce0NHpa7ZaxmOFkbEbULABpu412fS4NQa

YES

200 OK

{
    "token_type": "bearer",
    "issued_at": "1443102144106",
    "expires_in": 3600,
    "access_token": "ceTo5RCpluTfGn9B3OZXnnQkDVKM"
}

Parameters

Parameter

Description

token_type

Access token type

issued_at

Time when token was issued

expires_in

expiration of access token in seconds

access_token

Access token to access other APIs

Step 2: Create Bill

On this step the partner needs to create a bill in order to get a bill reference. The create bill request parameters should include mandatory order info.
Order info has to be passed to Finserve each time a partner uses “MPGS - Web” for receive money operation.

For Example:

POST /payment/v2/bills HTTP/1.1
Authorization: Bearer 67ew8n31me
Content-Type: application/json
Host: uat.jengahq.io

{
  "customer": {
    "name": "A N Other"
  },
  "order": {
    "reference": "14071950",
    "amount": "100",
    "currency": "KES",
    "channel": "CARD",
    "description": "This is an order. A test order",
    "outlet": "0579679314",
    "billerCode": "900900"
  }
}

Headers

Headers

Meaning

Default

Sample

Mandatory

Authorization

The Bearer token used to access the API

n/a

Bearer 67ew8n31me

YES

Content-Type

The content type of the payload

application/json

application/json

NO

Parameters

Parameter

Meaning

Default

Sample

Mandatory

Comments

customer.name

Customer Name

n/a

Joe Doe

YES

  • NO Special Charscters
  • Length Max - 50 Chars

order.billerCode

Biller Code

n/a

900900

YES

order.reference

Order Reference (Bill Number)

n/a

C3453545ED0

YES

  • Length Max -20 characters.
  • Must be unique for each request.
  • NO Special Characters allowed.

order.amount

Order Amount

n/a

1000.00

YES

order.currency

Order Amount currency

n/a

KES

YES

ISO_4217

order.description

Order Description

n/a

Test order

YES

  • Max Length - 70
  • NO Special Characters

order.channel

Channel

n/a

CARD

YES

order.outlet

Outlet code

n/a

0579679314

YES

200 OK

{
    "reference":"AOA7BS",
    "amount":"1020.00",
    "serviceId":"900900",
    "status":"1",
    "orderRef":"C3453545ED0",
    "channel":"CARD",
    "remarks":"Invoice created successfully",
  "systemCode": "0766555065"
}

Parameters

Parameter

Meaning

Comments

reference

Bill reference

amount

Bill amount

serviceId

Paybill number

status

Create Bill Status

  • 1 === Success
  • false === Failure

orderRef

Order reference

channel

Order channel

Will always be CARD in this case

remarks

Order

systemCode

Till Number

Step 3: Collect customer information

To charge the customer, first collect information such as email, amount, etc.

You can pass this information from a database or user session if customers are already signed up. Otherwise you can display a HTML form which collects user information to start card processing. MPGS – Web automatically processes the request, then sends the response back to you via the callback URL specified in your initial request.

Payment Parameters

Parameter

Meaning

token

The Bearer token

outletCode

This is generated with merchant code. It identifies the merchant outlet.

merchantCode

The merchant code provided at registration. Use the merchant code provided during token generation.

amount

Bill amount returned in Step 3: Create Bill response

orderReference

The merchant order reference used in Step 2: Create Bill.

  • it has to be less 30 characters
  • It has to be alphanumeric

billReference

Bill reference retuned in Step 2: Create Bill response

productType

Product type/ product id

productDescription

A brief summary of the product. max 200 characters

serviceDate

Transaction Date

customerFirstName

The customer's First Name

customerLastName

The customer's Last Name

cardNumber

Card Number

cardSecurity

cvv

cardExpiryYear

Card expiry year

cardExpiryMonth

Card expiry month

country

The customer’s country

mobileNumber

mobileNumber format:::
The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:
‘+’
country code (1, 2 or 3 digits)
‘space’
national number.

emailAddress

Email address of customer

postalcodeZip

The customer’s postal code

address

The customer’s address

city

The customer’s city

callbackUrl

A fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters.

The form field names used are as described above in the payment parameters. Implement the hidden form exactly as the sample code below demonstrates.

Endpoint

Base Path

Dependencies

Functionality

Method

  • Get Authorization Token

  • Create Bill

Integrate the payment widget

POST

<form id="id="cardPaymentForm" action="https://test-pay.jengahq.io/cardPay" method="POST" ">
    <input type="hidden" id="token" name="token">
    <input type="hidden" id="outletCode" name="outletCode">
    <input type="hidden" id="merchantCode" name="merchantCode">
    <input type="hidden" id="amount" name="amount">
    <input type="hidden" id="orderReference" name="orderReference">
    <input type="hidden" id="billReference" name="billReference">
    <input type="hidden" id="productType" name="productType">
    <input type="hidden" id="productDescription" name="productDescription">
    <input type="hidden" id="serviceDate" name="serviceDate">
    <input type="hidden" id="cardFirstName" name="cardFirstName">
    <input type="hidden" id="cardLastName" name="cardLastName">
    <input type="hidden" id="cardNumber" name="cardNumber">
    <input type="hidden" id="cardSecurity" name="cardSecurity">
    <input type="hidden" id="cardExpiryYear" name="cardExpiryYear" >
    <input type="hidden" id="cardExpiryMonth" name="cardExpiryMonth">
    <input type="hidden" id="customerFirstName" name="customerFirstName">
    <input type="hidden" id="customerLastName" name="customerLastName">
    <input type="hidden" id="country" name="country">
    <input type="hidden" id="mobileNumber" name="mobileNumber">
    <input type="hidden" id="emailAddress" name="emailAddress">
    <input type="hidden" id="postalcodeZip" name="postalcodeZip">
    <input type="hidden" id="address" name="address">
    <input type="hidden" id="city" name="city">
    <input type="hidden" id="ipAddress" name="ipAddress">
    <input type="hidden" id="callbackUrl" name="callbackUrl">
</form>

Step 4: Implement transaction callback

Once the payment is complete the user is redirected to the callbackUrl specified by you. A set of parameters is passed in response (using POST).

POST field name

Data type

Description

orderAmount

string

Order Amount

orderReference

string

Oder Reference

orderStatus

string

Possible values:
• Transaction Failed
• Transaction Successfull

message

string

Payment Successful or appropriate message in case of failure

dateTime

string

Transaction date time in yyyy-MM-ddZ format

billReference

string

Bill reference

transactionRef

string

Mastercard Transaction Reference. Will be empty if payment was not successful

Step 5: Verify the transaction

When a payment is completed, you need a way to check that the transaction was successful before providing value to the customer.

Verification happens on the backend and makes use of the bearer token.

For example:

GET  /payment/v2/query?billReference={orderRef} HTTP/1.1
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Host: uat.jengahq.io

Headers

Header

Meaning

Default

Sample

Mandatory

Authorization

The Bearer token used to access the API

n/a

Bearer 67ew8n31me

Generated using Get Authorization Token

200 OK

{ 
   "orderRef": "E5U6JS",
   "transactionId": "917813217246",
   "amount": "3105.0",
   "status": "true",
   "date": "2019-06-27T09:12:17.000-04:00",
   "narration": "Bill Pay"
}

Parameter

Meaning

orderRef

Order reference

transactionId

Transaction ID

amount

Amount Paid

status

Payment status

Possible values:

  • true
  • false

date

Transaction Date

narration

Transaction Remarks