`

ABSTRACT
The purpose of this document is to guide the online
ecommerce merchant to integrate with HBL’s payment
gateway HBLPay. Started with a brief overview of the
service followed by the pre-requisites of the technical

HBLPAY integration. The integration section describes the step

by step procedure of initiating payment. HBL also
offers plugins for renowned ecommerce platform;
setup details of woo-commerce and magento are given
Integration Guide in the Plugin Support section. Annexure of the
document covers sample codes, test data and response
code list.

Revisions
Version Issue Date Author Changes
1.0 10-June-2020 Shahid Rafique Draft
1.1 16-Sep-2020 Saad Rasheed Tokenization
Contents
HBLPay Overview .......................................................................................................................................... 2
Pre-Requisites ............................................................................................................................................... 2
Integration .................................................................................................................................................... 3
Step 1: Merchant Configuration to access HBLPay ................................................................................... 3
Step 2: RSA Key Generation Process ......................................................................................................... 3
XML Format........................................................................................................................................... 3
PEM Format .......................................................................................................................................... 4
Step 3: Calling HBLPAY API for Authentication ......................................................................................... 4
Tokenization................................................................................................................................................ 10
Step 4: HBLPay Page for Transaction Processing .................................................................................... 10
Plugin Support............................................................................................................................................. 19
Woo-Commerce Setup............................................................................................................................ 19
Magento Setup ....................................................................................................................................... 20
Annexures ................................................................................................................................................... 21
.Net Sample Code.................................................................................................................................... 21
PHP Sample Code .................................................................................................................................... 23
Test Accounts (for Direct Transfer) ** .................................................................................................... 24
Test Cards................................................................................................................................................ 24
Response Codes ...................................................................................................................................... 25

HBLPay Implementation Guide 1

HBLPay Overview
HBLPay is simple checkout platform that enables ecommerce merchants to accept online payments from
its VISA, Master and Union Pay credit/debit cards customers. Besides this it also enables cardless payment
through direct through HBL account. HBLPay is an efficient, secure and a single platform for multiple
schemes.

Pre-Requisites
Your web site must meet the following requirements:

 It must have a shopping –cart, customer order creation software, or an application for initiating
disbursement to send funds to payment accounts.
 The IT infrastructure must be Public Key infrastructure (PKI) enabled to use SSL-based form POST
submission.
 The IT infrastructure must be capable of digitally signing customer data prior to submission to
HBLPAY.

HBLPay Implementation Guide 2

Integration
Step 1: Merchant Configuration to access HBLPay

HBL team will share the following detail with merchant in order to integrate with HBLPay.

 Merchant MID
 Merchant Password
 HBL Public Key in XML/PEM format for Encryption (RSA 4096)

Merchant technical team will provide following detail to HBL team.

 Merchant will share their public key (RSA 4096) with IPG team
 Key generation process can be found in Step II

Note: A public key is a large value that is used to encrypt data. As per our system it must be RSA 4096.

Step 2: RSA Key Generation Process

Merchant can generate RSA Key using .net library Cryptography. Besides that, there are many online tool
available over the internet for RSA 4096 key generation and encryption assistance.

Sample Key Generation online tool URL: https://travistidwell.com/jsencrypt/demo/ (Please be noted that
it’s an example and there are many more available over the internet).

XML Format
<RSAKeyValue>

<Modulus>3wE6KkfUfW5ptmqA6pNGnNQ59HZ8uRK3T5eq4e4Vhlalc+RLb6zVQIrCAeTbMN5AeM9Drq3VP4r5cU5B
9h+7XlREO9i8E1a2+qgRpoB5W1PjCFaAkm/BEYHMcIeCv92aPgNB7/kxXgCksUsH6KdNQugFpxARJPOEKA1ue3m6f
AZMyX3DsrEXoMki9/XsOITXNR4BHM8+DvdgGItKuHgP4J9XPqD1C65yhKLEWSWSAHpOyRRhghLFCKrNFePXZxefFG
gGVF4Y5gqELbm8Y2Mjw6lWFwkzWRzWExHs7D26QH7OY04hGOd8mvJF71QbrNuCwtH7t7l2VYuljMssG3nHxqJ5aZT
nv0kWZUp7x9ioYB1RGUMfjFdQ32QUWPg2fUbg1Un0+y0GAD3Bx6CbSnqXVwQQLoNDsXpVDgSEGkblxJNxl1rXLNcL
4MPx//ep21UQU26kZdghkFUHaGt9+iddW05vbt9gm9AUCximaRHf4S5W/anCp86FE8faSJqBZvbBNQnSNu4OWnVHN
20Z9WGin8DSao4GKgHJG0TgE3iu+UrdLxbC0gF8G+zF/+doJP1n6cjO9K4foV4VAiFkRYZcFUPOEmDUIWXU5Xcp+M
XGiZNKoFrozG8V3IPHhYk4RBP7Ubwv+TCZgfvrq0a8vH7EmLMQ28785qtEVNTWQn8BhtE=</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>

HBLPay Implementation Guide 3

PEM Format
-----BEGIN PUBLIC KEY-----

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA3wE6KkfUfW5ptmqA6pNG

nNQ59HZ8uRK3T5eq4e4Vhlalc+RLb6zVQIrCAeTbMN5AeM9Drq3VP4r5cU5B9h+7

XlREO9i8E1a2+qgRpoB5W1PjCFaAkm/BEYHMcIeCv92aPgNB7/kxXgCksUsH6KdN

QugFpxARJPOEKA1ue3m6fAZMyX3DsrEXoMki9/XsOITXNR4BHM8+DvdgGItKuHgP

4J9XPqD1C65yhKLEWSWSAHpOyRRhghLFCKrNFePXZxefFGgGVF4Y5gqELbm8Y2Mj

w6lWFwkzWRzWExHs7D26QH7OY04hGOd8mvJF71QbrNuCwtH7t7l2VYuljMssG3nH

xqJ5aZTnv0kWZUp7x9ioYB1RGUMfjFdQ32QUWPg2fUbg1Un0+y0GAD3Bx6CbSnqX

VwQQLoNDsXpVDgSEGkblxJNxl1rXLNcL4MPx//ep21UQU26kZdghkFUHaGt9+idd

W05vbt9gm9AUCximaRHf4S5W/anCp86FE8faSJqBZvbBNQnSNu4OWnVHN20Z9WGi

n8DSao4GKgHJG0TgE3iu+UrdLxbC0gF8G+zF/+doJP1n6cjO9K4foV4VAiFkRYZc

FUPOEmDUIWXU5Xcp+MXGiZNKoFrozG8V3IPHhYk4RBP7Ubwv+TCZgfvrq0a8vH7E

mLMQ28785qtEVNTWQn8BhtECAwEAAQ==

-----END PUBLIC KEY-----

Step 3: Calling HBLPAY API for Authentication

Merchant will post the following detail on HBLPay API.

Sandbox Endpoint

https://testpaymentapi.hbl.com/hblpay/api/checkout

Production Endpoint

https://digitalbankingportal.hbl.com/hostedcheckout/api/checkout

HBLPAY support following scripting languages and you can download the sample script code for the
scripting language that you use:

 .NET Sample Code

 PHP Sample Code

NOTE: Sample code Download link define in Annexure section

 Order Detail
 Billing & Shipping Detail

HBLPay Implementation Guide 4

  Merchant Defined Data fields
 Merchant Detail (User Name & Password)

Authentication ID is provided by dev team to IPG team which merchant integrates in to their script code
and request the required parameter including encrypted key in form of post.

Following are the Data Description posted by the merchant.

Authentication Fields:
Fields Description Required / Optional
The authentication ID of merchant
USER_ID Required
provided by HBL
Password provided by HBL to
PASSWORD Required
authenticate Merchant profile
Merchant must provide a return URL
RETURN_URL which will be used to post back after Required
transaction processing
Cancel URL will be called from HBL
CANCEL_URL Pay if customer decides to cancel Required
during the transaction
CHANNEL Merchant Channel Required
Define channel specification (Union
TYPE_ID Required
Pay, Cybersource)

Order Summary
Fields Description Required / Optional
Discount offered on the total amount
DISCOUNT_ON_TOTAL Optional
charged by the merchant
Total amount of order placed by the
SUBTOTAL Required
customer

Order Summary Description

Fields Description Required / Optional
Name of the specific item that
ITEM_NAME Required
customer placed the order
QUANTITY Quantity of specific items Required
UNIT_PRICE Per Unit Price of the specific item Required
CATEGORY Category of the specific item Required
SUB_CATEGORY Category of the specific item Required
Sub Category of the specific item

Shipping Detail
Fields Description Required / Optional
NAME Name of the shipper Optional
Number of Days required by the
DELIEVERY_DAYS Optional
merchant for delivery of the product

HBLPay Implementation Guide 5

 Cost of the shipment that will be
SHIPPING_COST Optional
deliver by the merchant

Shipping Details (Depends on merchant Profile)

Fields Description Required / Optional
City of the address that customer put
at the time of the transaction where
ship_to_address_city Optional
merchant has to deliver the
purchased product
Country of the address that customer
put at the time of the transaction
ship_to_address_country Optional
where merchant has to deliver the
purchased product
Customer put the address at the time
ship_to_address_line1 of the transaction where merchant Optional
has to deliver the purchased product
Customer put the postal code at the
ship_to_address_postal_cod time of the transaction where
Optional
e merchant has to deliver the
purchased product
State of the address that customer
put at the time of the transaction
ship_to_address_state Optional
where merchant has to deliver the
purchased product
Forename of the shipper or the
ship_to_forename specific customer who receive the Optional
purchased order
Contact Number of the shipper or the specific customer who receive the
ship_to_phone
purchased order
Surname of the shipper or the specific customer who receive the purchased
ship_to_surname
order
Email address of the shipper or the specific customer who receive the
ship_to_email
purchased order

Additional Data Fields

Fields Description Required / Optional
Unique Identifier of specific
ORDER_ID Required
transaction
Unique Identifier of specific
REFERENCE_NUMBER Required
transaction
AMOUNT total amount of the specific order Required
CURRENCY Allowed options of Currency Required
This field identifies the card and
PAYMENT_TOKEN retrieves the associated billing, Optional
shipping, and payment information.
PAYMENT_METHOD Allowed options of Payment method Required
Forename of the Biller or the specific
BILL_TO_FORENAME Required
customer who placed the order

HBLPay Implementation Guide 6

 Surname of the Biller or the specific
BILL_TO_SURNAME Required
customer who placed the order
Email address of the biller or the
BILL_TO_EMAIL specific customer who placed the Required
order
Contact Number of the Biller or the
BILL_TO_PHONE specific customer who placed the Required
order
Country of the address that customer
BILL_TO_ADDRESS_LINE1 Required
put at the time of the transaction
City of the address that customer put
BILL_TO_ADDRESS_CITY Required
at the time of the transaction
State of the address that customer
BILL_TO_ADDRESS_STATE Required
put at the time of the transaction
Country of the address that customer
BILL_TO_ADDRESS_COUNTRY Required
put at the time of the transaction
Customer put the postal code at the
BILL_TO_ADDRESS_POSTA Required
time of the transaction

Merchant Define Data Fields

Fields Description Required / Optional
MERCHANT DEFINED DATA
Required
01 Channel of Operation
MERCHANT DEFINED DATA
Optional
02 3D Secure Registration
MERCHANT DEFINED DATA
Optional
03 Product Category
MERCHANT DEFINED DATA
Optional
04 Product Name
MERCHANT DEFINED DATA Previous Customer (If yes then
Optional
05 Customer ID to be passed)
MERCHANT DEFINED DATA
Optional
06 Shipping Method
MERCHANT DEFINED DATA
Optional
07 Number Of Items Sold
MERCHANT DEFINED DATA
Optional
08 Product Shipping Country Name
MERCHANT DEFINED DATA
Optional
09 Hours Till Departure
MERCHANT DEFINED DATA
Optional
10 Flight Type
MERCHANT DEFINED DATA
Optional
11 Full Journey/ Itinerary
MERCHANT DEFINED DATA
Optional
12 3rd Party Booking
MERCHANT DEFINED DATA
Optional
13 Hotel Name
MERCHANT DEFINED DATA
Optional
14 Date of Booking

HBLPay Implementation Guide 7

 MERCHANT DEFINED DATA
Optional
15 Check In Date
MERCHANT DEFINED DATA
Optional
16 Check Out Date
MERCHANT DEFINED DATA
Optional
17 Product Type
MERCHANT DEFINED DATA
Optional
18 Customer ID/ Phone Number
MERCHANT DEFINED DATA
Optional
19 Country Of Top – up
MERCHANT DEFINED DATA
Optional
20 VIP Customer

Sample Request – JSON (for reference only, in actual the value of parameters should be encrypted)

{
"USER_ID": "testmerchant",
"PASSWORD": "hbl@1234",
"RETURN_URL": "http://localhost:64149/Home/ThankYouPage",
"CANCEL_URL": "http://localhost:64149/Home/FailedPurchase",
"CHANNEL": "BOOKME_WEB",
"TYPE_ID": "0",
"ORDER": {
"DISCOUNT_ON_TOTAL": "20",
"SUBTOTAL": "600",
"OrderSummaryDescription": [
{
"ITEM_NAME": "COMPUTER BOOK",
"QUANTITY": "1",
"UNIT_PRICE": "180",
"OLD_PRICE": "210",
"CATEGORY": "Test_Category",
"SUB_CATEGORY": "Test sUB Category 1"
},
{
"ITEM_NAME": "GUITAR",
"QUANTITY": "2",
"UNIT_PRICE": "200",
"OLD_PRICE": null,
"CATEGORY": "Test_Category2",
"SUB_CATEGORY": "Test sUB Category2"
}
]
},
"SHIPPING_DETAIL": {
"NAME": "DHL SERVICE",
"ICON_PATH": null,
"DELIEVERY_DAYS": "7",
"SHIPPING_COST": "40"
},

HBLPay Implementation Guide 8

"ADDITIONAL_DATA": {
"REFERENCE_NUMBER": "TEST123456789",
"CUSTOMER_ID": null,
"CURRENCY": "PKR",
"BILL_TO_FORENAME": "John",
"BILL_TO_SURNAME": "Doe",
"BILL_TO_EMAIL": "[email protected]",
"BILL_TO_PHONE": "02890888888",
"BILL_TO_ADDRESS_LINE": "1 Card Lane",
"BILL_TO_ADDRESS_CITY": "My City",
"BILL_TO_ADDRESS_STATE": "CA",
"BILL_TO_ADDRESS_COUNTRY": "US",
"BILL_TO_ADDRESS_POSTAL_CODE": "94043",
"SHIP_TO_FORENAME": "John",
"SHIP_TO_SURNAME": "Doe",
"SHIP_TO_EMAIL": "[email protected]",
"SHIP_TO_PHONE": "02890888888",
"SHIP_TO_ADDRESS_LINE": "1 Card Lane",
"SHIP_TO_ADDRESS_CITY": "My City",
"SHIP_TO_ADDRESS_STATE": "CA",
"SHIP_TO_ADDRESS_COUNTRY": "US",
"SHIP_TO_ADDRESS_POSTAL_CODE": "94043",
"MerchantFields": {
"MDD1": "mdd1",
"MDD2": "mdd2",
"MDD3": "mdd3",
"MDD4": "mdd4",
"MDD5": "mdd5",
"MDD6": "mdd6",
"MDD7": "mdd7",
"MDD8": "mdd8",
"MDD9": "mdd9",
"MDD10": "mdd10",
"MDD11": "mdd11",
"MDD12": "mdd12",
"MDD13": "mdd13",
"MDD14": "mdd14",
"MDD15": "mdd15",
"MDD16": "mdd16",
"MDD17": "mdd17",
"MDD18": "mdd18",
"MDD19": "mdd19",
"MDD20": "mdd20"
}
}
}

 All details will be validated on HBL Pay and return with Authorization ID to the merchant web
page.
 For token-based payment, Merchant first ask HBL team for token enablement on Merchant’s
account. Please refer to tokenization section below for further details related to it.

HBLPay Implementation Guide 9

Tokenization
 After Tokenization enablement on Merchant account. Merchant will receive a token upon
successful transaction.
 Following will be the added fields along with sample values receive by merchant only in case of
token-based payment.
o CS_RESP_TOKEN=1234567890123456789012
o CARD_NUM_MASKED=400000xxxxxx0101
 The token can be used by merchant in-order to have the card details for that specific customer in
future transactions. PAYMENT_TOKEN field must be used to process it (Page # 6)

Step 4: HBLPay Page for Transaction Processing

 Merchant can access the HBL Pay page URL using that Authorization ID returned by HBL Pay API.
 Merchant will re-direct the user to following page

Sandbox Redirect URL

https://testpaymentapi.hbl.com/hblpay/site/index.html#/checkout?data=

Production Redirect URL

https://digitalbankingportal.hbl.com/hostedcheckout/site/index.html#/checkout?data=

In above URL, data field will contain encrypted authorization ID

 After getting landed on HBL Pay’s page merchant then now able to see the checkout page along
with details and multiple options of payments i-e Union Pay, Cybersource and Direct Transfer. All
three platforms i-e Cybersource, Direct Transfer & Union Pay are available for online collection
payments.

Card holder have the choice to pay the payment via following option.

 Visa/Master Card
 HBL Account
 UnionPay Card

HBLPay Implementation Guide 10

If customer wants to purchase the item via Visa/Master Card, select the option, click the button Proceed
to Visa/Master Card.

 Put all the details (Card Type, Card number, Expiry date, CVN) on payment details page.

 Customer will redirect to the Cybersource page for payment.

HBLPay Implementation Guide 11

 By clicking the Next button, customer will review all the details and then click the Pay button.

HBLPay Implementation Guide 12

If customer wants to purchase the item via HBL Account, select the option, click the button Proceed to

HBL Account.

 If customer is the HBL account holder and wants to purchase the item via HBL Account, select the

option, put the details (i-e account number and CNIC number) and click the Proceed button.

HBLPay Implementation Guide 13

 If customer attempt the transaction first time on merchant website, Customer will receive a

verification call on registered number and after successful verification, OTP will send to customer via

SMS.

HBLPay Implementation Guide 14

 By putting the OTP on the page, customer will Proceed the transaction and get the message of

Payment Successful.

HBLPay Implementation Guide 15

 If customer wants to purchase the item via Union pay Card, select the option, click the button Proceed

to Union pay.

 Put the details (Card number, Expiry date, CVN and SMS Code) on payment details page.

HBLPay Implementation Guide 16

 Customer will review the payment details and Click the Confirm and Pay button.

HBLPay Implementation Guide 17

 By clicking the Confirm and Pay customer will get the message of Payment Successful.

HBLPay Implementation Guide 18

Plugin Support
HBLPay do offer No-Code integration model as well. If merchant website is developed on any of the
following platforms, then by installing and configuring our plugin package will quickly enable merchants
for accepting payments through our gateway.

Woo-Commerce Setup
1. HBL team will provide merchant HBLPAY plugin as .zip file
2. To install plugin use the following link to install. You may proceed
with the upload zip file step
https://www.wpbeginner.com/beginners-guide/step-by-step-
guide-to-install-a-wordpress-plugin-for-beginners/

3. After installation and activation of plugin go to woo commerce -> settings -> Payments

4. After enabling the payment option go to manage and add plugin settings and save.

HBLPay Implementation Guide 19

Magento Setup

1. Install plugin with the help of following link.

https://bsscommerce.com/blog/how-to- install-
extension-in-magento-2/

2. After installation and execution of commands go to admin dashboard -> Stores -> Configuration -
> Sales -> Payments

3. You will find HBL Pay gateway in a list of payment methods. Enable gateway with the yes option
and fill complete settings to start using HBLPay gateway.

HBLPay Implementation Guide 20

Annexures
.Net Sample Code
public string CallService(string jsonData)
{
string URL =
System.Configuration.ConfigurationSettings.AppSettings["ServiceURL"];
string AllowProxy =
System.Configuration.ConfigurationSettings.AppSettings["AllowProxy"];
string Proxy =
System.Configuration.ConfigurationSettings.AppSettings["Proxy"];
string IsLive =
System.Configuration.ConfigurationSettings.AppSettings["IsLive"];
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(URL);
WebProxy proxy = new WebProxy(Proxy, true);
HBLPayResponseModel hblResponse = new HBLPayResponseModel();
if (IsLive == "1")
{
ServicePointManager.Expect100Continue = true;
ServicePointManager.SecurityProtocol = SecurityProtocolType.Ssl3 |
SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;
}
request.Method = "POST";
request.ContentType = "application/json";
if (AllowProxy == "1")
request.Proxy = proxy;
request.ContentLength = jsonData.Length;
using (Stream webStream = request.GetRequestStream())
using (StreamWriter requestWriter = new StreamWriter(webStream,
System.Text.Encoding.ASCII))
{
requestWriter.Write(jsonData);
}
try
{
string finalResult = "";
WebResponse webResponse = request.GetResponse();
using (Stream webStream = webResponse.GetResponseStream())
{
if (webStream != null)
{
using (StreamReader responseReader = new StreamReader(webStream))
{
string response = responseReader.ReadToEnd();
finalResult = response;
}
}
}
hblResponse =
JsonConvert.DeserializeObject<HBLPayResponseModel>(finalResult);
if (hblResponse.Data != null &&
!string.IsNullOrEmpty(hblResponse.Data.SESSION_ID))

HBLPay Implementation Guide 21

 {
var plainTextBytes =
System.Text.Encoding.UTF8.GetBytes(hblResponse.Data.SESSION_ID);
hblResponse.Data.SESSION_ID =
System.Convert.ToBase64String(plainTextBytes);
}
finalResult = JsonConvert.SerializeObject(hblResponse);
return finalResult;
}
catch (Exception ex)
{
throw new Exception(ex.Message);
}
}

You will receive SESSION_ID in response from API call. Then open the URL from your .net code or
JAVASCRIPT code with session id.

For example:
window.location.href =
'https://testpaymentapi.hbl.com/HBLPay/Site/index.html#/checkout?data=' + sessionID;

HBLPay Implementation Guide 22

PHP Sample Code
function callAPI($method, $url, $data)
{
$is_live = 'no';
use_proxy === 'no';
$curl = curl_init();
switch ($method){
case "POST":
curl_setopt($curl, CURLOPT_POST, 1);
if ($data)
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
break;
case "PUT":
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
if ($data)
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
break;
default:
if ($data)
$url = sprintf("%s?%s", $url, http_build_query($data));
}
// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
if($is_live === 'yes')
{
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
} // PROXY
if($use_proxy === 'yes')
{
$proxy = ‘your proxy’;
curl_setopt($curl, CURLOPT_PROXY, $proxy);
}
//EXECUTE
$result = curl_exec($curl);
if(!$result){die("Connection Failure");}
curl_close($curl);
return $result;
}

HBLPay Implementation Guide 23

You will receive SESSION_ID in response from API call. Then open the URL from your .net code or
JAVASCRIPT code with session id.

For example:
window.location.href =
'https://testpaymentapi.hbl.com/HBLPay/Site/index.html#/checkout?data=' + sessionID;

Test Accounts (for Direct Transfer) **

Type CNIC Account # Passcode/OTP

HBL Branch Account In test environment OTP SMS can be
viewed on below given URL
HBL Konnect In test environment OTP SMS can be
Branchless Account viewed on below given URL

** P.S. HBL Implementation team will provide Direct Transfer test data

https://testpaymentapi.hbl.com/OTPViewer/Home/Email

Test Cards

Scheme Security Card # Expiry Expiry Year CVV Passcode

Month
Visa Non 3D 4000000000000101 05 2023 111
Visa 3D 4000000000000002 05 2023 111 1234
Master Non 3D 5200000000000114 05 2023 111
Master 3D 5200000000000007 05 2023 111 1234
Union Pay Debit Card Card #: 12 33 123 PC Code:
6223164991230014 111111
Mobile #:
13012345678 Mobile Code:
123456
Union Pay Credit Card Card #: 12 33 123 PC Code:
6250947000000014 111111
Mobile #: +852
11112222 Mobile Code:
123456

HBLPay Implementation Guide 24

Response Codes

Response Response Message

Code
100 Dear Customer, Thank you for your payment, Your transaction has been received
successfully.
0 Dear Customer, Thank you for your payment, Your transaction has been received
successfully.
481 Dear Customer, Your transaction has been received and under review, our
representative will contact you shortly for further processing.
89 Channel is NOT ALLOWED
90 SESSION ID NOT FOUND
37 TRANSACTION_CODE_NOT_FOUND
35 INVALID_TRANSACTION
34 PARTIAL_REFUND_NOT_ALLOWED
33 AMOUNT_IS_GREATER_THAN_EXSISTING_AMOUNT
38 TPE_RESPONSE_CODE_NOT_FOUND
36 TRANSACTION TYPE NOT FOUND
230 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
70 Transaction has been redirected, waiting for cardholder input
76 Requires encryption verification for activation
78 Issuer transaction rights limited, for details please contact your issuer
85 Transaction failed, the marketing rules are not met
1012 Account Closed
520 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
230 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
42 Balance deduction successful but transaction exceeded payment time limit
11020 ACCOUNT_STATUS_NOT_FOUND
23 AMOUNT IS GREATER THAN MAX AMOUNT
21 CERTIFICATE NOT PROVIDED
01 CLIENT CERTIFICATE AUTHENTICATION FAILED
02 INVALID USERNAME OR PASSWORD
03 INVALID CNIC
05 ACCOUNT NOT FOUND
06 MOBILE NO. NOT FOUND
07 INCORRECT TXN. REFERENCE NO.
08 INCORRECT OTP
09 OTP EXPIRED
10 INSUFFICIENT FUNDS
11 SYSTEM ERROR
12 API NOT ALLOWED
13 Invalid Channel Password
14 INCORRECT AMOUNT
1111 DAILY DEBIT LIMIT EXCEED
1112 MONTHLY DEBIT LIMIT EXCEED

HBLPay Implementation Guide 25

 1113 YEARLY DEBIT LIMIT EXCEED
1114 DAILY CREDIT LIMIT EXCEED
1115 MONTHLY CREDIT LIMIT EXCEED
1116 YEARLY CREDIT LIMIT EXCEED
11008 INCORRECT PASSCODE
11004 PASSCODE IS EXPIRED
11003 PASSCODE IS VERIFIED
11005 PASSCODE IS PENDING
11006 CODE STRENGTH FAIL
11007 INVALID PASSCODE TYPE
11008 INCORRECT PASSCODE
11009 PASSCODE RETRY EXHAUSTED
11011 EXCEPTION
11010 CODE EXIST
11012 CERTIFICATE NOT PROVIDED
11013 CLIENT CERTIFICATE AUTHENTICATION FAILED
188 INVALID USERNAME OR PASSWORD
76 INVALID CNIC
174 CUSTOMER NOT FOUND
143 ACCOUNT NOT FOUND
202 MOBILE NUMBER NOT FOUND
11014 INCORRECT TRANSACTION REFRENCE NUMBER
11008 INCORRECT PASSCODE
11004 PASSCODE EXPIRED
1003 INSUFFICIENT BALANCE
1 SYSTEM ERROR
11015 API NOT ALLOWED
11016 API LIMIT EXCEED
02 INCORRECT AMOUNT
102 DAILY DEBIT LIMIT EXCEED
88 There is a special condition on your account
63 INSUFFICIENT FUNDS
11018 MONTHLY TRANSACTION COUNT LIMIT EXCEED
11019 YEARLY TRANSACTION COUNT LIMIT EXCEED
173 TRANSACTION NOT FOUND
9000 GENERAL ERROR
1110 DAILY TXN COUNT LIMIT EXCEED
1117 MONTHLY TXN COUNT LIMIT EXCEED
1118 YEARLY TXN COUNT LIMIT EXCEED
69 TRANSACTION NOT FOUND
320 TRANSACTION NOT ALLOWED ON THAT ACCOUNT TYPE
24 CNIC_BLOCKED
11017 DAILY TRANSACTION COUNT LIMIT EXCEED
04 TXN ALREADY CONSUMED
22 AMOUNT IS LESS THAN MIN AMOUNT
79 ACCOUNT NOT FOUND
50 ACCOUNT NOT FOUND

HBLPay Implementation Guide 26

 39 REVERSAL DATE EXCEED
236 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
476 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
106 INVALID BYPASS ID
105 Request Cancelled
99 INVALID ADDITIONAL DETAILS
110 INVALID_URL
271 Bio-metric Verification Failed
111 CURRENCY_NOT_ALLOWED
109 INVALID CUSTOMER ID
108 INVALID_ORDER_REFERENCE_NUMBER
80 Your account is not allowed to be registered for HBL InternetBanking
01 Transaction failed. For details please inquire overseas service hotline.
02 System is not started or temporarily down, please try again later
03 Transaction communication time out, please initiate inquiry transaction
05 Transaction has been successful, please inquire about transaction result shortly
06 System is busy, please retry it later.
10 Message format error
11 Verify signature error
12 Repeat transaction
13 Message transaction key element missing
30 Transaction failed, please try using other UnionPay card for payment or contact
overseas service hotline
31 Merchant state incorrect. The payment is not completed within the order timeout.
32 No such transaction right
33 Transaction amount exceeds limit
34 Could not find this transaction
35 Original transaction does not exist or state is incorrect
36 Does not match original transaction information
37 Max number of inquiries exceeded or too frequent operations
38 UnionPay risk constraint
39 Transaction is not within the acceptance time range
43 Business not allowed, please contact overseas service hotline for help.
44 Wrong number entered or business not opened, please contact overseas service
hotline for help.
45 The original transaction has been refunded or cancelled successfully.
60 Transaction failure, for details, please inquire with your issuer
61 Card number entered is invalid, please double check and enter
62 Transaction failed, issuer does not support this merchant, please change to another
bank card
63 Card state is incorrect
64 Card balance is insufficient
65 Error with PIN, expiration date, or CVN2 entered, transaction failure
66 Cardholder identity information or mobile number entered are incorrect, verification
failure
67 Limit on number of PIN entry attempts exceeded

HBLPay Implementation Guide 27

 68 Your bank card currently does not support this business, please inquire with your
bank or overseas service hotline for help
69 Time limit on entry exceeded, transaction failure
71 Dynamic password or SMS verification code validation failure
72 You have not signed up for UnionPay card-not-present payment service at the bank
counter or on your personal online bank, please go to a bank counter or access your
online banking to activate it or contact overseas service hotline for help.
73 Payment card has exceeded expiration date
77 Bank card has not been activated for authenticated payment
79 The bank card is valid, but issuer does not support SMS verification
80 Transaction failed and the token has expired
81 Monthly accumulated transaction counter (amount) exceeded
82 PIN needs to be verified
84 PIN is required but not submitted
86 QRC status error
88 QRC not found
89 No Token found, invalid TR status or invalid Token status
98 File does not exist
99 General error
00 Dear Customer, Thank you for your payment, Your transaction has been received
successfully.
112 Dear customer, you cancelled the order
218 MONTHLY DEBIT LIMIT EXCEED
100 Successful transaction
101 The request is missing one or more required fields.see the reply fields
missingField_0 through missingField_N for which fields are missing
104 The merchant reference code for this authorization request matches the merchant
reference code of another authorization request that you sent within the past 15
minutes.
150 General system failure.
153 Your CyberSource account is not enabled for the OCT service. Contact CyberSource
Customer Support to have your account enabled for this service.
201 The issuing bank has questions about the request. You do not receive an
authorization code programmatically, but you might receive one verbally by calling
the processor.
Possible action: call your processor to possibly receive a verbal authorization. For
contact phone numbers, refer to your merchant bank information.
203 General decline of the card. No other information was provided by the issuing bank.
Possible action: request a different card or other form of payment
205 Stolen or lost card
208 Inactive card or card not authorized for card-not-present transactions
231 Invalid account number
233 General decline by the processor
234 Incorrect information in your CyberSource account
240 The card type sent is invalid or does not correlate with the credit card number
250 The request was received, but a timeout occurred at the payment processor
490 Your aggregator or acquirer is not accepting transactions from you at this time
491 Your aggregator or acquirer is not accepting this transaction
107 INVALID BILLING DETAILS
91 ORDER_NOT_FOUND

HBLPay Implementation Guide 28

 92 INVALID_ORDER_DETAILS
93 INVALID_SHIPPING_DETAILS
94 SHIPPING_DETAILS_NOT_FOUND
95 SESSION_EXPIRED
96 INVALID_QUANTITY
25 INVALID CLIENT IP
26 ORIGINAL_TRANSACTION_NOT_FOUND
28 INVALID CUSTOMER KEY
29 CLIENT NOT FOUND
30 INVALID_DATA
31 CUSTOMER_ALREADY_REGISTER
97 INVALID_SHIPPING_NAME
98 DECRYPTION_FAILED
219 YEARLY DEBIT LIMIT EXCEED
46 SYSTEM ERROR
44 INTERNAL ERROR
102 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
104 Dear Customer, Your transaction has been rejected because of unsuccessfull
payment.
110 Only a partial amount was approved
150 Dear Customer, Your transaction has been rejected because of unsuccessfull
payment.
151 Dear Customer, Your transaction has been rejected because of unsuccessfull
payment.
152 Dear Customer, Your transaction has been rejected because of unsuccessfull
payment.
200 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
201 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
202 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
203 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
204 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
205 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
207 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
208 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
210 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
211 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
221 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
222 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.

HBLPay Implementation Guide 29

 231 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
232 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
233 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
234 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
240 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
475 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
520 Dear Customer, Your transaction has been declined by your issuing bank, Kindly
contact your issuing bank for further details.
115 INVALID_PAYMENT_TOKEN
116 TOKEN_NOT_ALLOWED

Customer Friendly Messages

Given below or similar messages can be shown to the customer after successful or a failed transaction.

 If transaction response / decision received as “Accept” or “Successful” please display massage like
below;

Dear Customer, thank you for your payment, your transaction has been received successfully
and your account will be updated accordingly.

 If transaction response / decision received as “Declined” please display massage like below:

Dear Customer, your card transaction has been declined by your card issuing bank, Kindly
contact your card issuing bank for details.

 If transaction response / decision received as “Reject” (with Reason Code 481) please display
massage like below.
Dear Customer, your card transaction has been received and under review, our representative
will contact you shortly for further process.

HBLPay Implementation Guide 30