Promopay VAS

Sections

Theme switcher

Introduction

Welcome to our Payment Gateway System

Our powerful web-based online payment services platform, a trusted solution utilized by numerous renowned companies and organizations in the region. Our system offers a secure, multi-channel, multi-lingual, and multi-currency payment experience.

Integration Methods:

Choose the integration method that best suits your needs:

Web Integration

Mobile Integration

Client Post through Browser (e.g. Shopping Cart)

This method is favoured by merchants for its simplicity and speed. It enables swift website integration, ensuring a seamless user experience with a streamlined transaction flow.

PaySDK Android Mobile SDK

This section explains the integration of PaySDK Android SDK in merchant android mobile application.

Direct Client Side Connection

Tailored for Online Shopping Carts, this method uses HTML and JavaScript for broad compatibility, ensuring a seamless experience

PaySDK IOS Mobile SDK

This section explains integration of PaySDK iOS SDK in merchant iOS mobile application.

Server Side Direct Connection (e.g. IVR System, Mobile App)

Merchants request payment authorization via our gateway, pending bank approval. They integrate their IVR or app, and create a custom payment page

eWallet Direct Connection

Merchants can seek direct payment authorization from the bank via our gateway, pending acquiring bank approval. They'll set up a custom payment page to collect information like credit card details, which will be sent to a specific URL provided by the acquiring bank. Customers won't encounter a bank payment page in this process.

Purpose of this Document:

This technical specification document prescribes the constituent parts of specification for integration of an e-commerce web site with PayDollar/SiamPay/PesoPay e-commerce service, the on-line payment service by AsiaPay (HK) Limited, by subscribed merchants of the service. This document has been created to ensure that all technical specifications contain sufficient information to enable a merchant to design and modify the codes of an existing on-line shopping architecture or software to cater for the payment –enabling service. It also provides a checklist to enable the reviewers of specifications to conduct tests on the functionalities of the integration.

Enhanced Security with 3DS 2.0:

There is an extra parameter section under each connection method. That section is especially designed for 3DS 2.0 (Three Domain Secure 2.0). 3DS authentication is an additional security layer for card-not-present transactions. With 3DS 2.0, it is aimed to achieve a better, stronger fraud-detection intelligence.

Merchant API Functions:

In a later section, we'll provide an in-depth description of the various API functions available to subscribed merchants, ensuring a seamless integration process.

Thank you for choosing our payment gateway system. Let's get started.

Web Integration

Following are the three methods of Web Integration

Client Post through Browser (e.g. Shopping Cart)

Direct Client Side Connection

Server Side Direct Connection (e.g. IVR System, Mobile App)

Mobile Integration

Data Feed Handling

To use data feed function, merchant has to create a data feed page and inform payment gateway system about the location of your page (e.g. http://www.yourdomain.com/datafeed.jsp). Merchant can enable or disable this function in the merchant administration site.

Output Parameters

Data Feed Output

Parameters

Data Type

Descriptions

src

Text

Return bank host status code (secondary). Please refer to Appendix A for detail.

prc

Text

Return bank host status code (primary).  Please refer to Appendix A for detail.

Ord

Text (40)

Bank Reference Number

Holder

Text

The Holder Name of the Payment Account

successcode

Number

0- succeeded,

1- failure,

2-pending,

Others - error

Ref

Text

Merchant‘s Order Reference Number

PayRef

Number

PayDollar/SiamPay/PesoPay Payment Reference Number

Amt

Number (12,2)

Transaction Amount

Cur

Text (3)

Transaction Currency i.e. “344” – HKD

“840” – USD

“702” – SGD

“156” – CNY (RMB)

“392” – JPY

“901” – TWD

“036” – AUD

“978” – EUR

“826” – GBP

“124” – CAD

“446” – MOP

“608” – PHP

“764” – THB

“458” – MYR

“360” – IDR

“410” – KRW

“682” – SAR

“554” – NZD

“784” – AED

“096” – BND

“704” – VND

“356” – INR

remark

Text (200)

A remark field for you to store additional data that will not show on the transaction web page

AuthId

Text

Approval Code

eci

Text (2)

ECI value (for 3D enabled Merchants)

VISA / JCB / AMEX

ECI Value Definition

05 Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful

06 Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful, in sample situations as:

  1. 3D cardholder not enrolled
  2. Card issuing bank is not 3-D Secure ready

07 Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction

MasterCard ECI Value Definition 00 Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction 01 Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful, in sample situations as:

  1. 3D Cardholder not enrolled
  2. Card issuing bank is not 3-D Secure ready

02 Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful

Remark : Empty String will be sent when the transaction is rejected by PayDollar PayAlert.

payerAuth

Text (1)

Payer Authentication Status

Y - Card is 3-D secure enrolled and authentication succeeds.

N - Card is 3-D secure enrolled but authentication fails.

P - 3-D Secure check is pending

A - Card is not 3-D secure enrolled yet

U - 3D-secure check is not processed.

If using 3DS 2.0, it is the “Transaction Status” returned in Authentication Response or “Transaction Status” returned in Result Response.

Y - Authentication/ Account Verification Successful

N - Not Authenticated /Account Not Verified; Transaction denied

U - Authentication/ Account Verification Could Not Be Performed

A - Attempts Processing Performed

C - Challenge Required

R - Authentication/ Account Verification Rejected

sourceIp

Text (15)

IP address of payer

ipCountry

Text (3)

Country of payer ( e.g. HK)

  • if country is on high risk country list, an asterisk will be shown (e.g. MY*)

payMethod

Text (10)

Payment method (e.g. VISA, Master, Diners, JCB, AMEX)

cardIssuingCountry

Text (3)

Card Issuing Country Code ( e.g. HK)

  • if country is on high risk country list, an asterisk will be shown (e.g. MY*)
  • if the card issuing country of credit card is undefined, “- -“ will be shown.

Please refer to Appendix A “List of Country Code” for detail

channelType

Text (3)

Channel Type:

SPC – Client Post Through Browser

DPC – Direct Client Side Connection

DPS – Server Side Direct Connection

SCH – Schedule Payment

DPL – Direct Payment Link Connection

MOT – Moto Connection

RTL – RetailPay Connection

BPP – Batch Payment Process

secureHash

Text (40)

Secure hash is used to authenticate the integrity of the response information and the identity of PayDollar/SiamPay/PesoPay. It is calculated by hashing the combination of various response parameters and the Secure Hash Secret.

*Applies to merchants who registered this function only. For more information, please refer to section 4.

AlertCode

Text (50)

The Alert Code

e.g. R14 –IP Country not match with Issuing Country

R 9 - In high risk country list

MerchantId

Number

The merchant Id of transaction

airline_ticketNumber

Text

Air Ticket Number

TxTime

Text (YYYY-MM-DD HH:MI:SS.0)

Transaction time

JAVASCRIPT
// sample data
prc=0&src=0&Ord=12345678&Ref=8e88729be67a4722aa34537db4d0ae99&PayRef=11868042&successcode=0&Amt=80.00&Cur=840&Holder=testing+card&AuthId=868042&AlertCode=&remark=&eci=07&payerAuth=U&sourceIp=203.184.197.67&ipCountry=HK&payMethod=VISA&TxTime=2023-11-22+09%3A23%3A14.0

Card Information

Additional output parameters for Card Information

Parameters

Data Type

Descriptions

expMonth

Text (MM)

Expiry month of the card *Return to approved merchant only

expYear

Text (YYYY)

Expiry year of the card *Return to approved merchant only

panFull

Text

Encrypted PAN with AES256 encryption *Return to approved merchant only

panFirst6

Text (6)

First 6 digit of card *Return to approved merchant only

panFirst4

Text (4)

First 4 digit of card *Return to approved merchant only

panLast4

Text (4)

Last 4 digit of card *Return to approved merchant only

accountHash

Text

Hash value of card *Return to approved merchant only

accountHashAlgo

Text

Hash function of card: SHA-1 SHA-256 *Return to approved merchant only

MPS VAS

Additional output parameters for transaction processing with MPS VAS

Parameters

Data Type

Descriptions

mpsAmt

Number (12,2)

MPS Transaction Amount

Remark: For MPS Enabled only.

mpsCur

Text (3)

MPS Transaction Currency

Remark: For MPS Enabled only.

mpsForeignAmt

Number (12,2)

MPS Transaction Foreign Amount

Remark: For MPS Enabled only.

mpsForeignCur

Text (3)

MPS Transaction Foreign Currency

Remark: For MPS Enabled only.

mpsRate

Number (12,4)

MPS Exchange Rate: (Foreign / Base)

e.g. USD / HKD = 7.77

Remark: For MPS Enabled only.

SchedulePay VAS

Additional output parameters for transaction processing with SchedulePay VAS

Parameters

Data Type

Descriptions

mSchPayId

Number

The Master Schedule Payment Id

*For Schedule payment transaction only

dSchPayId

Number

The Detail Schedule Payment Id

*For Schedule payment transaction only

MemberPay VAS

Additional output parameters for transaction processing with MemberPay VAS

Parameters

Data Type

Descriptions

mpMemberId

Text

Member Id if merchant using memberPay

mpLatestStaticToken

Text

Encrypted static token if merchant using static token mode of memberPay

Third Party eWallet

Additional output parameters for transaction processing through Third Party eWallet

Parameters

Data Type

Descriptions

isEwallet

Text(1)

“T” –This is a transaction with Ewallet function

eWalletBrand

Text

ECO - AMEX Express checkout

MP – MasterPass

VCO – VISA Checkout

eWalletInd

Text

Only Text(3) for MasterPass EWallet, The Wallet Indicator is returned by the wallet platform and must be passed to the payment processor/acquirer in the financial authorization transaction.

Promopay VAS

Additional output parameters for transaction processed with Promopay VAS

Parameters

Data Type

Descriptions

promotionCode

Text(8);

The promotion campaign code of transaction

*For promotion transaction only

promotionRuleCode

Text(8);

The promotion rule code of transaction

*For promotion transaction only

promotionOriginalAmt

Number (12,2)

The original amount of promotion

*For promotion transaction only

Installment

Additional output parameters for installment transaction

Parameters

Data Type

Descriptions

period

Number

The installment period (In number of months)

installmentProvider

Text

The issuing bank or provider of the installment

“HASE” – Hang Seng Bank (Hong Kong)

“BOCIHK” – Bank of China (Hong Kong)

“BCA” - Bank Central Asia (Indonesia)

“WELEND” – WeLend (Hong Kong)

firstPayAmt

Number

The transaction amount for first installment period

*Return only if the installment bank providing this information

eachPayAmt

Number

The transaction amount for each installment period

*Return only if the installment bank providing this information

lastPayAmt

Number

The transaction amount for last installment period

*Return only if the installment bank providing this information

Rewards Program

Additional output parameters for transaction processed with rewards program (e.g. Hang Seng Cash Dollar)

Parameters

Data Type

Descriptions

netAmtAfterRewards

Number(12,2)

Total Net Amount after Redeem Rewards Program

rewardsRedeemTotalAmt

Number(12,2)

Total Rewards Redeem Amount

rewardsRedeemType

Text

Rewards Redeem Type “HASE” – Hang Seng Cash Dollar

rewardsRedeemProgram

Number

Number of redeem programs Return value is 1,2, or 3

rewardsRedeemCode1

Text

First Rewards Program Redeem Program Code

*Return only when rewardsRedeemProgram return value is 1,2 or 3

rewardsRedeemLabel1

Text

First Rewards Program Redeem Program Label

*Return only when rewardsRedeemProgram return value is 1,2 or 3

rewardsRedeemAmt1

Number(12,2)

First Rewards Program Redeem Amount

*Return only when rewardsRedeemProgram return value is 1,2 or 3

rewardsBalance1

Text

First Rewards Program Balance

Format

Expired Rewards Balance Expired Date – Expired Balance Amount | Rewards Balance Expired Date- Rewards Balance

Amount

Example: 0115-20.00|0120-30.00

*Return only when rewardsRedeemProgram return value is 1,2 or 3

rewardsRedeemCode2

Text

Second Rewards Program Redeem Program Code

*Return only when rewardsRedeemProgram return value is 2 or 3

rewardsRedeemLabel2

Text

Second Rewards Program Redeem Program Label

*Return only when rewardsRedeemProgram return value is 2 or 3

rewardsRedeemAmt2

Text

Second Rewards Program Redeem Amount

*Return only when rewardsRedeemProgram return value is 2 or 3

rewardsBalance2

Text

Second Rewards Program Balance

Format

Expired Rewards Balance Expired Date – Expired Balance Amount | Rewards Balance Expired Date- Rewards Balance

Amount

Example: 0115-20.00|0120-30.00

*Return only when rewardsRedeemProgram return value is 2 or 3

rewardsRedeemCode3

Text

Third Rewards Program Redeem Program Code

*Return only when rewardsRedeemProgram return value is 3

rewardsRedeemLabel3

Text

Third Rewards Program Redeem Program Label

*Return only when rewardsRedeemProgram return value is 3

rewardsRedeemAmt3

Number(12,2)

Third Rewards Program Redeem Amount

*Return only when rewardsRedeemProgram return value is 3

rewardsBalance3

Text

Third Rewards Program Balance

Format

Expired Rewards Balance Expired Date – Expired Balance Amount | Rewards Balance Expired Date- Rewards Balance

Amount

Example: 0115-20.00|0120-30.00

*Return only when rewardsRedeemProgram return value is 3

3DS 2.0

Additional output parameters for 3DS 2.0

Parameters

Data Type

Descriptions

threeDSVersion

Text (10)

Indicate the 3DS Version if 3D-Secure is processed in this payment.

“” – Non 3D

“1.0” – Using 3DS 1.0

“2.1.0” / “2.2.0” – Using 3DS 2.0 (depends on the actual message version used in 3DS 2.0 message)

The data feed page must meet the following requirement:

  • Print ‘OK’ in HTML when data captured (ACK message)
  • Make Sure to Print ‘OK’ for acknowledge to our system first then do the rest of your system process, if something wrong with your system process (i.e. download photo, ring tone problem) you can send a void request to our system, for more details please refer to our API guide and contact our technical staff.

Please note that the system only supports either port 80 (HTTP) or 443 (HTTPS) for the data feed page location. And make sure the data feed page location is externally accessible, so that our server can call the data feed page.

* Since the system will read from the data feed page for the word ‘OK’ to determine whether the (data feed) message is delivered or not, if this word does not return successfully, the system will assume the data feed is lost

Data Feed Setup

Merchant can enable or disable the data feed function in the merchant administration site > Profile > Payment Options.

Sample Data Feed Page

The following is a sample data feed page in JSP.

JAVA
<%@ page language="java" %>
<%
 String successCode = request.getParameter("successcode");
 String payRef = request.getParameter("PayRef");
 String Ref = request.getParameter("Ref");
 // Print out 'OK' to notify us you have received the payment result
 out.print("OK");
 if ( successCode.equals("0") )
 {
 // Transaction Accepted
 // *** Add the Security Control here, to check the currency, amount with
the
 // *** merchant’s order reference from your database, if the order exist
then
 // *** accepted otherwise rejected the transaction.
 // Update your database for Transaction Accepted and send email or notify
your
 // customer.
 ....
// In case if your database or your system got problem, you can send a
void transaction request. See API guide for more details
 }
 else
 {
 // Transaction Rejected
 // Update your database for Transaction Rejected
 .....
 }
%>

The following is a sample data feed page in ASP

PLAINTEXT
<%@ Language = "VBScript" %>
<%
 Dim successCode
 Dim payRef
 Dim Ref
 successCode = Request.Form("successcode")
 payRef = Request.Form("PayRef")
 Ref = Request.Form("Ref")
' Print out 'OK' to notify us you have received the payment result
 Response.write("OK")
 If successCode = "0" Then
 ' Transaction Accepted
 ' *** Add the Security Control here, to check the currency, amount with the
 ' *** merchant’s order reference from your database, if the order exist then
 ' *** accepted otherwise rejected the transaction.
 ' Update your database for Transaction Accepted and send email or notify your
 ' customer.
 .....
 ' In case if your database or your system got problem, you can send a void
 ' transaction request. See API guide for more details
 Else
 ' Transaction Rejected
 ' Update your database for Transaction Rejected
 .....
 End If
%>

Transaction Security By Secure Hash

Multi-Currency Processing Service

Functions Of Merchant API

Exceptional Transaction Handling

This section explains various scenarios of transactions, other than good and successful transactions that may occur.

Payment Methods by Regions/Countries

Australia

Payment Options

Payment Methods

Credit and Debit Card

American Express, China UnionPay, Mastercard, Visa

Internet Banking

PayTo, PayID

Digital Wallet

Alipay, PayPal, PayID, WechatPay

Buy Now Pay Later

AfterPay, Humm, Zip

China

Payment Options

Payment Methods

Credit and Debit Card

American Express, JCB, Mastercard, Visa

Digital Wallet

Alipay, WechatPay

Hong Kong

Payment Options

Payment Methods

Credit and Debit Card

American Express, China UnionPay, Diners, Discover, JCB, Mastercard, Visa

Digital Wallet

Alipay, Alipay HK, WeChat Pay, Paypal, BoC Pay, PayMe, Octopus, FPS, PPS, Google Pay, Samsung Pay, Apple Pay

Bank Account and Net Banking

FPS, PPS

Global (no grouping)

Apple Pay, Google Pay, Samsung Pay, Click to Pay

Installment

Visa Instalment

India

Payment Options

Payment Methods

Credit and Debit Card

American Express, Mastercard, RuPay, Visa

Bank Account and Net Banking

NetBanking, UPI

Digital Wallet

ITZ Cash Card, Mobikwik, PhonePe, Yes Bank Wallet

Installment

EMI

Indonesia

Payment Options

Payment Methods

Credit and Debit Card

American Express, JCB, Mastercard, Visa

Bank Account and Net Banking

BCA KlikPay, BNI Virtual Account, CIMB Clicks, Danamon Virtual Account, Mandiri Clickpay, Permata Virtual Account

Over-the-counter

Alfamart Group, Indomaret

Digital Wallet

Dana

Buy Now Pay Later

Kredivo, Indodana

Japan

Payment Options

Payment Methods

Digital Wallet

Alipay HK

Korea

Payment Options

Payment Methods

Credit and Debit Card

MasterCard, Virtual Account, Visa

Digital Wallet

Naver Pay, Kakao Pay, PayCo

Others

Toss

Macau

Payment Options

Payment Methods

Credit and Debit Card

American Express, JCB, Mastercard, Visa

Crypto

BNB (Binance), BTC (Bitcoin), ETH (Ethereum), LBTC (Lightning Bitcoin), USDC (USD Coin), USDT (Tether)

Others

ALIPAYHKONL, WECHATONL

Malaysia

Payment Options

Payment Methods

Credit and Debit Card

American Express, China UnionPay, Discover, JCB, Mastercard, Visa

Bank Account and Net Banking

FPX

Crypto

BNB (BINANCE), BTC (Bitcoin), ETH (Ethereum), LBTC (Lightning Bitcoin), USDC (USD Coin), USDT (Tether)

Digital Wallet

Alipay, WechatPay, PayPal , BOOST, TouchnGo, Scan & Pay by MAE, GrabPay, Shopback Pay

Buy Now Pay Later

Atome, PayLater by Grab

Philippines

Payment Options

Payment Methods

Credit and Debit Card

American Express, China UnionPay, Diners, Dicover, JCB, Mastercard, Visa

Bank Account and Net Banking

BDO (Brankas), BPI, Landbank (Brankas), Metrobank (Brankas), RCBC (Brankas), Unionbank (Brankas)

Digital Wallet

Gcash, Grabpay, ShopeePay, MAYA,  Alipay, Wechatpay

Over-the-counter

Bayad Center, BDO, Cebuana, ECPay, RCBC

Others

PayPal

Buy Now Pay Later

TendoPay

Singapore

Payment Options

Payment Methods

Credit and Debit Card

American Express, China UnionPay, Diners, Discover, JCB, Mastercard, Visa

Bank Account and Net Banking

ENETS, PayNow

Crypto

BNB (Binance), BTC (Bitcoin), ETH (Ethereum), LBTC (Lightning Bitcoin), USDC (USD Coin), USDT (Tether)

Digital Wallet

GrabPay, Shopback Pay, ShopeePay, Alipay, Wechatpay, SGQR, PayPal

Buy Now Pay Later

Atome, PayLater by Grab, Shopee SPayLater

Taiwan

Payment Options

Payment Methods

Global (no grouping)

Apple Pay, Google Pay, Samsung Pay

Credit and Debit Card

JCB, MasterCard, Visa

Digital Wallet

Linepay, Jkopay, Apple Pay , Google Pay

Thailand

Payment Options

Payment Methods

Global (no grouping)

GooglePay

Credit and Debit Card

American Express, China UnionPay, JCB, Mastercard, Visa

Bank Account and Net Banking

BAY, BBL, KBANK, SCB, TMB, UOB

Digital Wallet

Paypal

Buy Now Pay Later

Atome

Over-the-counter

BBL, Kbank, KTB, Lotus, Mpay, TTB, UOB

Vietnam

Payment Options

Payment Methods

Credit and Debit Card

American Express, JCB, Mastercard, Visa

Internet Banking

NAPAS (43 banks), OnePay

Buy Now Pay Later

Kredivo

Digital Wallet

MoMo

FAQ

Appendix A

Security