DirectPay IPG Integration
Payment Link
V1.0.1
Integration document Directpay (Pvt) Ltd
1
Document Change History
Version Updated by Updated on Updates
1.0.0 Asela Priyadarshana 05/10/2020 Initial document
1.0.1 Nimesh Chathunraga 03/01/2022 Payment Link API Update
Integration document Directpay (Pvt) Ltd
2
Document Change History 1
Overview 3
2. Integration 3
2.1. Security 3
2.2. API provided by DirectPay 4
Create payment session 4
Query payment status 8
2.3. API provided by merchant 10
Payment confirmation 10
Integration document Directpay (Pvt) Ltd
3
1. Overview
Merchant should create a session for each payment using the provided api. After completing the
transaction by customer, the merchant will receive a confirmation to the endpoint provided to
DirectPay.
Once the merchant has registered with directpay following data will be provided.
merchant_id: To identify the merchant in payment request
Secret: To generate HMAC
2. Integration
Sandbox URL: https://test-gateway.directpay.lk/api/v3/
2.1. Security
Directpay API use HMAC (Hashed Message Authentication Code) for Authentication and
Authorization of requests
Send requests with HMAC authentication.
Step 1: Encode payload
Stringify json data object and then base64 encode the json string.
Step 2: Generate signature
Generate HMAC signature for the payload using the provided secret key. Hashing algorithm is:
SHA256
Step 3: Send request with encoded payload as the body and the generated signature as the value of the
‘Authorization’ header as shown below
<token> = Generated HMAC for each request
Key Value
Authorization hmac <token>
Sample request header
Authorization: hmac 7152e3971e590ec0e81ff28200efd0ace962b2f80aede7c62fd61ef6c6756425
Sample request body
ewogICAibWVyY2hhbnRfaWQiOiJEUDAwMDAxIiwKICAgImFtb3VudCI6IjEyMi4yMjIiLAogICAiY3VycmVuY3kiOiJ
MS1IiLAogICAidHlwZSI6Ik9ORV9USU1FIiwKICAgIm9yZGVyX2lkIjoib3JkZXJfMTIzNCIsCiAgICJyZXR1cm5fdXJsIj
oiaHR0cHM6Ly9tZXJjaGFudC5tL2NvbXBsZXRlIiwKICAgInJlc3BvbnNlX3VybCI64oCdaHR0cHM6Ly9tZXJjaGFudC5t
Integration document Directpay (Pvt) Ltd
4
L25vdGlmeSIsCiAgICJmaXJzdF9uYW1lIjoiSmhvbiIsCiAgICJsYXN0X25hbWUiOiJEb2UiLAogICAicGhvbmUiOiIwNzE
yMzQ1Njc4IiwKICAgImVtYWlsIjoiaGVsbG9AZGlyZWN0cGF5LmxrIiwKICAgImxvZ28iOiJodHRwczovL2RpcmVjdH
BheS5say8xMjAweDYzMHdhLnBuZyIsCn0K
2.2. API provided by DirectPay
1. Create payment link
Endpoint: {Base URL}/create-link
Method: POST
Body: Base64 encoded JSON string
Request Parameters:
Parameter Type Required Description
merchant_id String yes Id given to the merchant by DirectPay
name String yes Item name
amount String yes Payment amount with 2 decimals.
Ex: “10.20” , “10.34” , “10.00”
currency String yes Payment currency. Allowed values: ‘LKR’,
‘USD’
type String yes Allowed values: ‘0’, ’1’, ’2’
Product = 0
Service = 1
Recurring = 2
order_id String yes Unique id generated by merchant for the
payment
return_url String no If exists, redirect to this url after the
payment is completed
notification_url String no If exists, request will be send to this url
after the transaction is completed
logo String no Url of the logo to be displayed in the
payment page
product Object Yes if type = 0 If type is 0 , product objects are mandatory.
Product objects include stock count,
delivery type and delivery fee.
product.stock string Yes if type = 0 Stock count maximum 500 stock can be
added.
Integration document Directpay (Pvt) Ltd
5
product.delivery_type string Yes if type = 0 Delivery fee type Allowed values: ‘0 , ‘1’
Free of Charge = 0
Fixed Fee = 1
product.delivery_fee string Yes if type = 0
and
delivery_type =
1
Fixed fee amount
subscription Object Yes if type = 2 If type is 2, subscription object mandatory,
subscription object contain start date, end
date, initial payment option , subscription
amount and subscription interval
subscription.start_date string Yes if type = 2 Subscription start date
Allowed values: ‘Y-m-d’
Ex: 2023-01-11
subscription.end_date string Yes if type = 2 Subscription end date
Allowed values: ‘Y-m-d’
Ex: 2023-01-11
subscription.do_initial_
payment
string Yes if type = 2 Allowed values: ‘0’, ‘1’
Disable = 0
Enable = 1
Do the first transaction when subscribe
time.
subscription.amount string Yes if type = 2 Subscription amount, amount needed to
deduct form card in given interval.
subscription.interval string Yes if type = 2 Allowed values: ‘1’, ‘2’, ‘3’, ‘4’
MONTHLY = 1
BIANNUALLY = 2
ANNUALLY = 3
QUARTERLY= 4
Interval type need to get subscription
amount
send_sms Object No SMS payment link through directpay
send_sms.sms_content string If send_sms key
exist
Content need to concat link
send_sms.contact_no string If send_sms key
exist
Contact number of the recipient
send_email Object No Email payment link through directpay
Integration document Directpay (Pvt) Ltd
6
send_email.email_cont
ent
string Is send_email
key exist
Content need to concat link
send_email.email string Is send_email
key exist
Email recipient
link_expire string No Expire the payment link specific date and
time
Allowed values: ‘Y-m-d H:i’
Ex: 2023-01-11 02:03
Integration document Directpay (Pvt) Ltd
7
Sample request:
{
"merchant_id":"xxxxxxx",
"name":"myProduct",
"amount":"324",
"currency":"LKR",
"type":'0',
"order_id": '123',
"notification_url":"",
"return_url":"",
"logo":"",
"product":{
"stock":8,
"delivery_type":"1",
"delivery_fee":100
},
"subscription":{
"start_date":"2022-12-31",
"end_date":"",
"do_initial_payment":"",
"amount":"",
"interval":"1",
},
"send_sms":{
"sms_content":"abc test",
"contact_no":"07777777777"
},
"send_email":{
"email_content":"Pay using this link: ",
"email":"user@gmail.com"
},
"link_expire":"2023-01-11 02:03"
}
● Merchant should calculate the HMAC for request data and include it in the header using the
method in section 2.1 (Security)
Response Parameters:
Parameter Type Description
status String API response status
data Object Object containing response data
Integration document Directpay (Pvt) Ltd
8
data.status String Link create status
data.link String Payment link
data.link_code String Payment link code
data.buttonCode String Clickable button contain payment links. Can
add web sites.
data.smsStatus String SMS Status (success or failed)
data.emailStatus String Email Status (success or failed)
Sample Response :
Success {
"status": 200,
"data": {
"status": "success",
"link": "http://gateway/link/a8de5c3ab6",
"link_code": "a8de5c3ab6",
"buttonCode": "<form action='http://gateway/link/a8de5c3ab6' method='get'><input
name='submit' type='image' src='https://cdn.directpay.lk/dev/assets/pay_directpay.png'
style='width:200px;' value='Pay Now'></form>",
"smsStatus": "Success",
"emailStatus": "Success"
}
}
Validation
Error
{
"status": 422,
"data": {
"product.stock": [
"The product.stock field is required."
]
}
}
Other Error {
"status": 400,
"data": {
"title": "Failed",
"message": "Failed to create the session",
"code": "createFailed"
}
}
2. Query payment session
Endpoint: {Base URL}/query-session
Method: POST
Integration document Directpay (Pvt) Ltd
9
Body: Base64 encoded JSON string
Request Parameters:
Parameter Type Required Description
merchant_id String yes Id given to the merchant by DirectPay
order_id String yes Unique id generated by merchant
Sample request:
{
"merchant_id":"DP00001",
"order_id":"order_1234",
}
● Merchant should calculate the HMAC for request data and include it in the header using the
method in section 2.1 (Security)
Response Parameters:
Parameter Type Description
status String SUCCESS/FAILED
order_id String Order id sent by merchant
transaction_id String Unique id generated by DirectPay
description String Description of the transaction
Sample Response :
Success {
"status": 200,
"data": {
"status":"SUCCESS",
"order_id":"ORDER2342424",
,"transaction_id":"17323",
"description":"Successfully completed the transaction"
}
}
Validation Error {
"status": 422,
"data": {
"order_id": [
"Order id not found"
],
Integration document Directpay (Pvt) Ltd
10
}
}
Other Error {
"status": 400,
"data": {
"title": "Failed",
"message": "Failed to query the session",
"code": "queryFailed"
}
}
2.3. API provided by merchant
1. Payment confirmation
Once the payment is completed, confirmation will be sent to the notification_url given by the
merchant at the session creation.
Method: POST
Body: Base64 encoded JSON string
Sample Request Body:
Before decode:
eyJjaGFubmVsIjoiTUFTVEVSQ0FSRCIsInR5cGUiOiJPTkVfVElNRSIsIm9yZGVyX2lkIjoiMTIzIi
widHJhbnNhY3Rpb25faWQiOiIxMTA4MTYiLCJzdGF0dXMiOiJTVUNDRVNTIiwiY2FyZF9pZC
I6bnVsbCwiZGVzY3JpcHRpb24iOm51bGwsImNhcmRfbWFzayI6bnVsbCwiY3VzdG9tZXIiOnsib
mFtZSI6InVzZXIiLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIiwibW9iaWxlIjoiMDc3Nzc3NzcifSwi
dHJhbnNhY3Rpb24iOnsiaWQiOiIxMTA4MTYiLCJzdGF0dXMiOiJTVUNDRVNTIiwiZGVzY3Jpc
HRpb24iOiJBcHByb3ZlIiwibWVzc2FnZSI6IlNVQ0NFU1MiLCJhbW91bnQiOiIzMzkuMjAiLCJjd
XJyZW5jeSI6IkxLUiIsInByb21vdGlvbl9hbW91bnQiOiI4NC44MCJ9LCJwcm9tb3Rpb24iOnsiYXB
wbHkiOnRydWUsIk5hbWUiOiJuZXcgcHJvbW90aW9uIiwicGVyY2VudGFnZSI6MjAsInN0YXJ0
X2RhdGUiOiIyMDIxLTA3LTIwIDE0OjA2OjI0IiwiZW5kX2RhdGUiOiIyMDIyLTExLTIxIDE0Oj
A2OjI3IiwicGF5X3R5cGUiOiJPTkVfVElNRSIsImN1cnJlbmN5IjoiTEtSIiwiYmFua19uYW1lIjoiQ
W1hbmEgQmFuayBMdGQiLCJjYXJkX3R5cGUiOiJERUJJVCJ9fQ==
After base64 decode:
{
"channel":"MASTERCARD",
"type":"ONE_TIME",
"order_id":"123",
"transaction_id":"110816",
"status":"SUCCESS",
"card_id":null,
"description":null,
"card_mask":null,
"customer":{
Integration document Directpay (Pvt) Ltd
11
"name":"user",
"email":"user@gmail.com",
"mobile":"07777777"
},
"transaction":{
"id":"110816",
"status":"SUCCESS",
"description":"Approve",
"message":"SUCCESS",
"amount":"339.20",
"currency":"LKR",
"promotion_amount":"84.80"
},
"promotion":{
"apply":true,
"Name":"new promotion",
"percentage":20,
"start_date":"2021-07-20 14:06:24",
"end_date":"2022-11-21 14:06:27",
"pay_type":"ONE_TIME",
"currency":"LKR",
"bank_name":"Amana Bank Ltd",
"card_type":"DEBIT"
}
}
Status codes:
● Merchants should Verify requests using calculating the HMAC for request data using the
given method in section 2.1 (Security). If the calculated HMAC does not match with the value
in the Authorization header sent by DirectPay, do not proceed with the order and send a 405
(verification failed) response.