HBMCN API Guide 1.0
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 19
| Download | |
| Open PDF In Browser | View PDF |
DOCUMENT SUMMARY
This document contains all the relevant Technical
Information required for 3rd Party Heritage
TouchPoints to integrate with the MultiChoice
Payment Gateway for Payment and Fulfilment of
DSTV and GOTv subscriptions
Bola Adekoya
Solution Architect
HERITAGE BANK
MULTICHOICE PAYMENT
GATEWAY
As-Built by Quetzal Consults
CONTENTS
1.0 Version History ............................................................................................................................ 2
2.0 PURPOSE....................................................................................................................................... 3
3.0 INTENDED AUDIENCE................................................................................................................ 3
3.1 Distribution............................................................................................................................... 3
4.0 AUTH END POINT........................................................................................................................ 4
4.1 {{BaseURL}}/api/auth .............................................................................................................. 4
4.2 {{BaseURL}}/api/auth/reset ................................................................................................... 5
5.0 OPERATIONS END POINT ......................................................................................................... 6
5.1 {{BaseURL}}/api/types ............................................................................................................ 6
5.2 {{BaseURL}}/api/{type}/bouquet .......................................................................................... 7
5.3 {{BaseURL}}/api/{type}/accounts/{smartcardnumber} .................................................... 8
5.4 {{BaseURL}}/api/{type}/details /{smartcardnumber} ....................................................... 9
5.5 {{BaseURL}}/api/{type}/payment/{productkey}/{customernumber}/{basketId}} .... 11
5.6 {{BaseURL}}/api/{type}/payment/{productkey}/{smartcardnumber}} ....................... 13
6.0 TRANSACTION INQUIRIES END POINTS ............................................................................. 16
6.1 {{BaseURL}}/api/transactions/{id} ...................................................................................... 16
6.2 {{BaseURL}}/api/Confirmation/{id} .................................................................................... 17
1
1.0 Version History
Document
Date
Description
Prepared By
March, 2018
Initial Version
Bola Adekoya
Comments
Version
V1.0
2
2.0 PURPOSE
The purpose of this document is to serve as a reference point for any Application that may be
required to Integrate to the HBMCN API for Heritage Bank; the document contains the
Methods, End-Points and all other technical related information required for the API
integration.
The document contains the below End-Points required for Integration
•
•
•
Authorization End-Point
Operations End-Point
Transaction End-Point
3.0 INTENDED AUDIENCE
This document is intended for the Technical Resource for any Heritage Bank Application
(Proprietary or Other-Wise) needing to integrate with MultiChoice via the Heritage Bank MCN
Middleware.
3.1 Distribution
This Document was created by Quetzal Consults for Heritage Bank and can only be distributed
by Heritage Bank except where stated otherwise.
3
4.0 AUTH END POINT
The Auth endpoint category manages the security of the API.
4.1 {{BaseURL}}/api/auth
Sensitive endpoints of the application are protected and API clients would have to be
authenticated before they can consume these endpoints; the system uses JWT to protect these
sensitive endpoints.
This endpoint validates the credentials supplied by the API client and generates a bearer token.
The API Client must send, as part of the header section of any request, the bearer token;
generated token lifespan is 24hours.
Sample Request
url: {{BaseURL}}/api/auth
type: POST
body: {
"clientId": "string",
"password": "string"
}
content-type: application/json
Sample Response
{
"accessToken":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIzIiwidW5pcXVlX25hbWUiOiJIQ
lBhZGllIiwiZW1haWwiOiJib2xhLmFkZWtveWFAcXVldHphbGNvbnN1bHRzLmNvbSIsImp0aS
I6ImVlNjIxMWE4LTJhMzYtNDg4ZC05OTgzLTk0Y2QyZTU2ZjhmZSIsIkJhbmtJbmNvbWVBY2
NvdW50IjoiIiwiQ2xpZW50SW5jb21lQWNjb3VudCI6IiIsIkNsaWVudFBlcmNlbnQiOiIwLjQwIi
wiZXhwIjoxNTIxMzIxNjI3LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjM4MTA2LyIsImF1ZCI6I
mh0dHA6Ly9sb2NhbGhvc3Q6MzgxMDYvIn0.h8mZklsvUJnOxwHA72KXAd1HvIjLI1QTdTU6
wcXA3Vo",
"expirationDate": "2018-03-17T17:20:27.2900156-04:00",
4
"clientAppName": "Heritage Bank Mobile App (HBPadie)"
}
HTTP Response Code In Use
#
Code
Description
Content (datatype returned and example)
1
200
Success
{
}
2
400
Bad Request
"accessToken": "string",
"expirationDate": "2018-03-20T17:44:14.900Z",
"clientAppName": "string"
String – “Invalid APIClientId”
4.2 {{BaseURL}}/api/auth/reset
This endpoint resets the client's password and sends the newly generated password to the
APIClient's email address.
Sample Request
url: {{BaseURL}}/api/auth/reset
type: POST
body: "hbmobile"
content-type: application/json
Sample Response
"Password reset and notification sent successfully."
5
HTTP Response Code In Use
#
Code Description
Content (datatype returned and example)
1
200
Success
String – “Password reset and notification sent successfully.”
2
400
Bad Request
String – “API ClientId was not properly supplied”
3
403
Forbidden
String – “Client has been deactivated”
4
404
Not Found
String – “Unknown ClientId”
5
500
Internal Server Error
String – “Password reset failed”
6
503
Service Unavailable
String- “Password reset, mail could not be sent. Please
contact IT support”
5.0 OPERATIONS END POINT
Manages of the operations and interaction of the API
5.1 {{BaseURL}}/api/types
This endpoint returns available Multichoice options.
Sample Request
url: {{BaseURL}}/api/types
type: GET
content-type: application/json
Sample Response
[
{
},
{
]
}
"name": "GoTV",
"bouquetUrl": "/api/gotv/bouquet"
"name": "DSTV",
"bouquetUrl": "/api/dstv/bouquet"
6
HTTP Response Code In Use
#
Code Description
1
200
Content (datatype returned and example)
Success
5.2 {{BaseURL}}/api/{type}/bouquet
This endpoint returns the bouquet available for the type (DSTV or GoTV) supplied. This
endpoint can also be reached directly from the categories endpoint bouquetUrl.
Sample Request
url: {{BaseURL}}/api/gotv/bouquet
type: GET
content-type: application/json
*Parameters: {type} is parameter is either GoTV or DSTV
Sample Response
[
{
"code": "GOLITE",
"name": "GOtv Lite (Quarterly)",
"description": "GOtv Lite is a one stop digital TV solution for which you pay a quarterly admin
fee.",
"currency": "NGN",
"subscription": 1050,
"nameAndPrice": "GOtv Lite (Quarterly) (NGN1,050.00)",
"transFee": 50,
"paymentUrl": "/api/gotv/payment/GOLITE"
},
{
"code": "GOTVPLS",
"name": "GOtv Plus",
"description": "One month subscription is included in the package price",
"currency": "NGN",
"subscription": 1900,
"nameAndPrice": "GOtv Plus (NGN1,900.00)",
"transFee": 50,
"paymentUrl": "/api/gotv/payment/GOTVPLS"
},…]
7
HTTP Response Code In Use
#
Code Description
Content (datatype returned and example)
1
200
Success
2
400
Bad Request
String – “Unknown package name smtv”
3
500
Internal Server Error
String – “service unavailable”
5.3 {{BaseURL}}/api/{type}/accounts/{smartcardnumber}
This endpoint returns all the accounts attached to the customer.
Sample Request
url: {{BaseURL}}/api/dstv/accounts/4119205482
type: GET
content-type: application/json
*Parameters:
•
{type}: either GoTV or DSTV or Comm
•
{smartcardnumber}: first 10 digits of the smart card number or device number in case
of GoTV.
Sample Response
{
"auditReferenceNo": "28f80afc-2c9c-4b57-84cc-cb7433928faa",
"customer": {
"lastName": "ADEKOYA JAMIU",
"firstName": "A",
"initial": "A",
"customerNumber": 265739840,
"accountNo": 0,
"title": "Mr.",
"mobileNo": "2348023851364",
"emailAddress": "debolakoya@yahoo.com",
"hasBoxOffice": false,
"invoicePeriod": 0,
"totalBalance": 0
},
"accounts": [
8
{
}
]
}
"isPrimary": true,
"accountType": "DStv Normal",
"currency": "NGN",
"amount": 0,
"methodOfPayment": "Cash",
"customerNumber": 24892731,
"status": "Suspended",
"paymentDueDate": "2001-01-01T00:00:00",
"lastInvoiceDate": "2017-06-24T09:51:43",
"invoicePeriod": 1,
"hasBoxOffice": false,
"isCommercial": false
HTTP Response Code In Use
#
Code Description
1
200
Success
2
400
Bad Request
Content (datatype returned and example)
String – “One or more errors occurred. (An error occurred
while sending the request.)”
3
500
Internal Server Error
String – “service unavailable”
5.4 {{BaseURL}}/api/{type}/details /{smartcardnumber}
This endpoint returns the customer information alongside the accounts attached to the
customer.
Sample Request
url: {{BaseURL}}/api/dstv/details/4119205482
type: GET
content-type: application/json
*Parameters:
•
{type}: either GoTV or DSTV or Comm
9
•
{smartcardnumber}: first 10 digits of the smart card number or device number in case
of GoTV.
Sample Response
{
"customer": {
"lastName": "JACKSON",
"firstName": "E",
"initial": "E",
"customerNumber": 313467282,
"accountNo": 71704942,
"accountStatus": "Open",
"hasBoxOffice": false,
"invoicePeriod": 1,
"totalBalance": -301
},
"products": [
{
"currency": "NGN",
"subscription": 14700,
"productKey": "PRWE36",
"productName": "DStv Premium W/Afr E36",
"nameAndPrice": "DStv Premium W/Afr E36 (NGN14,700.00)",
"activeOnAccount": true,
"transFee": 50,
"paymentUrl": "/api/dstv/payment/PRWE36/4288705565"
},
{
"currency": "NGN",
"subscription": 16530,
"productKey": "PRWASIE36",
"productName": "DStv Premium W/Afr + Asian Bouquet E36",
"nameAndPrice": "DStv Premium W/Afr + Asian Bouquet E36 (NGN16,530.00)",
"activeOnAccount": false,
"transFee": 50,
"paymentUrl": "/api/dstv/payment/PRWASIE36/4288705565"
},
{
"currency": "NGN",
"subscription": 19680,
"productKey": "PRWFRNSE36",
"productName": "DStv Premium W/Afr + French Bonus Bouquet E36",
"nameAndPrice": "DStv Premium W/Afr + French Bonus Bouquet E36 (NGN19,680.00)",
"activeOnAccount": false,
10
}
]
}
"transFee": 50,
"paymentUrl": "/api/dstv/payment/PRWFRNSE36/4288705565"
HTTP Response Code In Use
#
Code Description
1
200
Success
2
400
Bad Request
Content (datatype returned and example)
String – “One or more errors occurred. (An error occurred
while sending the request.)”
3
500
Internal Server Error
String – “service unavailable”
5.5 {{BaseURL}}/api/{type}/payment/{productkey}/{customernumber}/{basketId}}
This endpoint is used to make payment with the customer number.
Sample Request
url: {{BaseURL}}/api/dstv/payment/COMPLE36/265739840/
type: POST
content-type: application/json
header:
Authorization: bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIzIiwidW5pcXVlX25hbWUiOiJIQl
BhZGllIiwiZW1haWwiOiJib2xhLmFkZWtveWFAcXVldHphbGNvbnN1bHRzLmNvbSIsImp0aSI
6ImVlNjIxMWE4LTJhMzYtNDg4ZC05OTgzLTk0Y2QyZTU2ZjhmZSIsIkJhbmtJbmNvbWVBY2
NvdW50IjoiIiwiQ2xpZW50SW5jb21lQWNjb3VudCI6IiIsIkNsaWVudFBlcmNlbnQiOiIwLjQwIi
wiZXhwIjoxNTIxMzIxNjI3LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjM4MTA2LyIsImF1ZCI6I
mh0dHA6Ly9sb2NhbGhvc3Q6MzgxMDYvIn0.h8mZklsvUJnOxwHA72KXAd1HvIjLI1QTdTU6
wcXA3Vo
body:
{
"amount": 9900,
"invoicePeriod": 1,
11
"emailAddress": "a@b.com",
"accountNumber": "1234567890",
"mobileNumber": "08012345678",
"paymentMode": "cash"
}
*Parameters:
•
{type}: either GoTV or DSTV or Comm
•
{productkey}: the bouquet code retrieved by {{BaseURL}}/api/{type}/bouquet.
•
{Customernumber}: the customer number, supplied by the customer or retrieved by
{{BaseURL}}/api/{type}/number/{smartcardnumber} or {{BaseURL}}/api/{type}/details
/{smartcardnumber}
•
{BasketId}: basketId as retrieved from {{BaseURL}}/api/{type}/details
/{smartcardnumber}. This field is nullable
Sample Response
….
Location à {{url}}/api/confirmation/100000016
….
Body
{
}
"auditReferenceNo": "6f290440-f800-47e7-9066-d5b3d932f743",
"transactionNumber": "100000016",
"receiptNumber": "4567895244",
"date": "2018-03-24T18:00:00-04:00",
"message": "",
"success": true
HTTP Response Code In Use
#
Code Description
Content (datatype returned and example)
1
201
Success
2
400
Bad Request
String – “Bad Request”
3
400
Bad Request
Dictionary - {
"additionalProp1": "string",
12
"additionalProp2": "string",
"additionalProp3": "string"
}
4
401
Unauthorized
5
500
Internal Server Error
6
500
String – “Server Error”
Response – {
"referenceNumber": "string",
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
7
503
Response– {
"referenceNumber": "string",
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
8
503
String – {
"referenceNumber": "string",
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
5.6 {{BaseURL}}/api/{type}/payment/{productkey}/{smartcardnumber}}
This endpoint is used to make payment with the smart card number.
Sample Request
url: {{BaseURL}}/api/dstv/payment/COMPLE36/4119205482
type: POST
13
content-type: application/json
header:
Authorization: bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIzIiwidW5pcXVlX25hbWUiOiJIQl
BhZGllIiwiZW1haWwiOiJib2xhLmFkZWtveWFAcXVldHphbGNvbnN1bHRzLmNvbSIsImp0aSI
6ImVlNjIxMWE4LTJhMzYtNDg4ZC05OTgzLTk0Y2QyZTU2ZjhmZSIsIkJhbmtJbmNvbWVBY2
NvdW50IjoiIiwiQ2xpZW50SW5jb21lQWNjb3VudCI6IiIsIkNsaWVudFBlcmNlbnQiOiIwLjQwIi
wiZXhwIjoxNTIxMzIxNjI3LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjM4MTA2LyIsImF1ZCI6I
mh0dHA6Ly9sb2NhbGhvc3Q6MzgxMDYvIn0.h8mZklsvUJnOxwHA72KXAd1HvIjLI1QTdTU6
wcXA3Vo
body:
{
"amount": 9900,
"invoicePeriod": 1,
"emailAddress": "a@b.com",
"accountNumber": "1234567890",
"mobileNumber": "08012345678",
"paymentDescription": "dstv payment",
"paymentMode": "cash"
}
*Parameters:
•
{type}: either GoTV or DSTV or Comm
•
{productkey}: the bouquet code retrieved by {{BaseURL}}/api/{type}/bouquet.
•
{Customernumber}: the customer number, supplied by the customer or retrieved by
{{BaseURL}}/api/{type}/number/{smartcardnumber} or {{BaseURL}}/api/{type}/details
/{smartcardnumber}
Sample Response
Headers
….
Location à {{url}}/api/confirmation/100000016
….
Body
{
14
}
"auditReferenceNo": "6f290440-f800-47e7-9066-d5b3d932f743",
"transactionNumber": "100000016",
"receiptNumber": "4567895244",
"date": "2018-03-24T18:00:00-04:00",
"message": "",
"success": true
HTTP Response Code In Use
#
Code Description
Content (datatype returned and example)
1
201
Success
2
400
Bad Request
String – “Bad Request”
3
400
Bad Request
Dictionary - {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
4
401
Unauthorized
5
500
Internal Server Error
6
500
String – “Server Error”
Response – {
"referenceNumber": "string",
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
7
503
Response– {
"referenceNumber": "string",
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
8
503
String – {
"referenceNumber": "string",
15
"code": "string",
"message": "string",
"developerMessage": "string",
"moreInfo": "string"
}
6.0 TRANSACTION INQUIRIES END POINTS
This group of endpoints are used to query the system for payment transactions
6.1 {{BaseURL}}/api/transactions/{id}
This endpoint retrieves transaction information from the application log.
Sample Request
url: {{BaseURL}}/api/confirmation/100102303
type: GET
content-type: application/json
*Parameters: {id} transaction number returned when payment was consummated
Sample Response
{
"id": 100000001,
"accountNumber": "0013331239",
"transactionDate": "2018-03-18T09:49:14.333315",
"apiClientId": "HBPadie",
"customerNumber": "",
"deviceNumber": "265739840",
"packageCode": "PRWASIE36",
"businessType": "dstv",
"emailAddress": "debolakoya@eatwest.com",
"mobileNumber": "08012345678",
"amount": 12000,
"transFees": 50,
16
"posted": false,
"auditReferenceNo": "00000000-0000-0000-0000-000000000000",
"success": false,
"url": "/api/confirmation/100000001"
}
HTTP Response Code In Use
#
Code Description
Content (datatype returned and example)
1
200
Success
2
400
Bad Request
String – “Unknown package name smtv”
3
500
Internal Server Error
String – “service unavailable”
6.2 {{BaseURL}}/api/confirmation/{id}
This endpoint returns the bouquet available for the type (DSTV or GoTV) supplied. This
endpoint can also be reached directly from the categories endpoint bouquetUrl.
Sample Request
url: {{BaseURL}}/api/confirmation/100000001
type: GET
content-type: application/json
*Parameters: {id} transaction number
Sample Response
{
}
"transactionNumber": 100000000,
"receiptNumber": 2345678,
"date": "2018-03-24T18:00:00-04:00",
"message": "Transaction not found",
"sucess": false,
"auditReferenceNo": "6f290440-f800-47e7-9066-d5b3d932f743"
HTTP Response Code In Use
17
#
Code Description
Content (datatype returned and example)
1
200
Success
2
40
Bad Request
String – “Unknown package name smtv”
3
500
Internal Server Error
String – “service unavailable”
18
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf Linearized : No Page Count : 19 PDF Version : 1.4 Title : Microsoft Word - HBMCN API Guide 1.2.docx Producer : Mac OS X 10.13 Quartz PDFContext Creator : Word Create Date : 2018:03:26 15:00:23Z Modify Date : 2018:03:26 15:00:23ZEXIF Metadata provided by EXIF.tools