Version Info

Version Date Content Editor
2.0 09/26/2016 Create Khuc Chi Huan

Overview

Introduction

This document describes the payment integration between VTC Pay Gateway in the role of payment service provider and Merchant Shop (system of partner) in the role of sales organization, using online payment methods of VTC Pay via VTC Pay e-wallet and bank accounts (domestic and international internet banking).

This document describes functions which are necessary for integration, information transmission between two parties’ systems.

This document describes database stream that interacts between two systems in transaction process.

Definition of data exchange standards, safety solutions as well as authenticating transaction source.

Alpha Test Parameters

VTC Pay web address to register website integration, check transaction history :

http://alpha1.vtcpay.vn/wallet

Url sending order payment information :

http://alpha1.vtcpay.vn/portalgateway/checkout.html

Test Account:

Merchant test account to login VTC Pay to register website integration, check transaction history:

Account:  0963465816
Password: Aa@123456

Customer’s VTC Pay e-wallet account to test order payment:

Account:  01657758300
Password: Abcd1234

Customer’s Visa Card test order payment by international card:

Card number:  4111111111111111
Zip/Postal Code: 123
CardType: Visa
CVN: 123
Exprition Date: 01/2020
Other fields: Whatever in correct format

Customer’s Techcombank Card test order payment by domestic card:

Card number:  9704000000000018
Card name: NGUYEN VAN A
OTP: otp
Open date: 03/07 (MM/yy)

Golive Parameters

Website VTC Pay:

https://vtcpay.vn/

Url sending order payment information:

https://vtcpay.vn/bank-gateway/checkout.html

Note: Test and Golive Parameters are different, therefore, in this mode, Merchant need a valid VTC Pay e-wallet account:
- To register website integration.
- To receive money after successful transactions.

Website Integration Registration Tutorials

To register payment integration via VTC Pay, Merchant need to login VTC Pay e-wallet account, access to menu "Payment integration – Website Integration” to register an integration website. VTC Pay will show the interface that manages Merchant’s integration websites. Fill in necessary information and follow the instruction to complete integration registration.

Ex:

Đăng Ký

Note:

Url Receiving: the address that receives order payment transaction result from VTC Pay according to POST. As in the example, it should be http://www.kidsplaza.vn/listen.html

If Url Redirect is not on order, VTC shall redirect customers to Url Receiving.

Website Secret Key: As information added when creating signature by SHA256 . Secret Key must include numbers, uppercase letter, lowercase letter, and have at least 16 characters.

Transaction Fees: Merchants choose either buyers or sellers to be charged. Ex: A $100 oder with fee of $3, in case:
- Sellers be charged: Buyers spend $100, Sellers get $(100-3).
- Buyers be charged: Buyers spend $(100+3), Sellers get $100.

Open-source Integration

Programming Payment Integration

Payment Diagram using bank account

Đăng Ký

Merchant request Parameters

FieldStyleCompulsion (*)Description
amountdoubleYTotal amount of payment:
- VND: rounded to 1
- USD: take 2 numbers after the comma
bill_to_addressString(100)NAddress of customer (number, street, etc.)
bill_to_address_cityString(100)NCity
bill_to_emailString(100)NEmail of customer
bill_to_forenameString(50)NName (Ex: Hung)
bill_to_phoneString(30)NPhone number of customer
bill_to_surnameString(50)NSurname/Family name (Ex: Nguyen Van)
countryString(5)NNation of Customers. Transmitting country code value is listed as appendix
currencystring(5)YPayment currency:
    - VND
    - USD
languagestringNLanguage displayed on VTC site. If not transmitted, Vietnamese is default:
    vi: Vietnam
    en: English
payment_typestringNPayment type. Transmitting the following:
VTC Pay: payment by VTC Pay balance
DomesticBank: payment with only domestic bank InternationalCard: payment with only international card. In case of payment with specific bank, transmitting Bank code value is listed as appendix
postcodeString(50)NPostcode of city or province’s customers
receiver_accountstringYReceiving account of customers after successful transaction
reference_numberstring(30)YRef. number of integrating partner. This number is unique and is the base of reconciling and monitoring
transaction_typestringNDefault value is: sale
url_returnstringNMerchant’s Url that VTC shall redirect customers after finishing transaction. If not transmitted, Url when registering to create website
website_idintYWebsite ID code which is created by partner on VTC system
signaturestringYSignature (SHA-256, Uppercase). Text to create a signature includes the value of parameters (plaintext, non-encode) and SecretKey. In the order of alphabet and divide with “|”. Ex: plaintext = string.Format("{0}|{1}|{2}|{3}|{4}|{5}", amount, currency, receiver_account, reference_number, website_id, Security_Key);
stateString(5)NState of Customers. Transmitting State code value is listed as appendix

(*). Compulsory Fields :
        Y : Must transmit to url.
        N : Maybe null, empty or no need.

Signature: This is an example with full parameters in the following order:


                        amount|bill_to_address|bill_to_address_city|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|country|currency|language|payment_type|postcode|receiver_account|reference_number|transaction_type|url_return|website_id|SecurityCode|state
                      

SecurityCode: Passcode created in Website Integration Registration Process.
In case of missing some parameters (ex: bill_to_address_city, transaction_type, url_return), text to generate signature should be like that:

                      amount|bill_to_address|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|currency|language|payment_type|receiver_account|reference_number|website_id|SecurityCode
                      

Returned result according to POST(server to server)

HTTP POST is the connection form of Server to Server. Data will be posted from VTC Pay server to receiving site at Merchant server that’s the site when creating website integration. VTC always posts transaction result to this receiving site:

=> It helps Merchant receive the result all time, avoid not receiving the result if using HTTP Get, in case customers turn off their browser in transaction process or problems of the internet connection.

=> It helps Merchant receive the final result, special with verified transactions that need to be approved by VTC admin.

=> It helps merchant compare with results by GET method to avoid risk


Parameters of order payment result that VTC Pay return to Merchant’s site:

Field Style Compulsion Description
data string Y amount|message|payment_type|reference_number| status|trans_ref_no|website_id
signature string Y Encrypt SHA256(UTF8 Encoding) fields based on the following format: amount|message|payment_type|reference_number| status|trans_ref_no|website_id|secret_key
secret_key: Chính là mã bí mật bạn nhập khi tạo website

Note: When receiving the result returned, Merchant has to check amount of money returned and amount of money sent to VTC Pay is correct or not.If it is not correct, the result returned is invalid, need to contact with VTC to check again.

Returned result according to HTTP GET

After finishing checkout process, VTC Pay shall redirect customer to receving site of Merchant, and return the payment result to Merchant at the same time through parameters on Url.

Details of returned parameters:

Field Style Compulsion Description
amount int Y Value of order, is the amount money of order in Merchant’s system
message string N Additional information
payment_type string N Payment form that customer process transaction
reference_number string(50) Y Order ref. that Merchant send
status int Y As in Appendix
trans_ref_no VTC ref. code
website_id int Y Website’s code registered on VTC Pay, in Website integrating managing session on VTC Pay
signature string Y Encrypt SHA256(UTF8 Encoding) fileds in the order of alphabet, and add secret_key in the end.Respectively: Amount|message|paymentType|reference_number| status|trans_ref_no|website_id|secret_key
secret_key: secret key you entered when creating website website

Note: When receiving the result returned, Merchant has to check amount of money returned and amount of money sent to VTC Pay is correct or not.If it is not correct, the result returned is invalid, need to contact with VTC to check again.

Appendix

Appendix of order payment

Status Mean Note
0 Transaction status of initializing
1 SUCCESS Successful transaction
7 REVIEW Payment account of customer is deducted but Merchant’s account is not credited.Payment admin department of VTC will approve to decide transaction is successful or failed.
-1 FAIL Failed transaction
-9 FAIL Customer cancel transaction
-3 FAIL VTC admin cancel transaction
-4 FAIL Account not eligible for transaction(Locked, not registered for online payment ...)
-5 FAIL Customer account balance(VTC Pay ewallet, bank account) is not sufficient to make payment
-6 FAIL Transaction error at VTC
-7 FAIL Customer enter wrong payment information(account information or OTP)
-8 FAIL Exceed day transaction limit
-22 FAIL Order payment value is too small
-24 FAIL Order payment currency is not valid
-25 FAIL Merchant’s VTC Pay receiving account does not exist
-28 FAIL Lack of compulsory parameters in one online payment order
-29 FAIL Request parameter is not valid
-21 CHECK Duplicating transaction reference.May be because of duplicating solving is not good, poor internet connection, customer enter F5, or poor transaction code generating, partner must check to get the final result of this transaction
-23 CHECK WebsiteID does not exist
-99 CHECK Undefined errors and transaction status.Must check to know if transaction is successful or not

Appendix of banks list

Bank code Bank name
Vietcombank JSC Bank for Foreign Trade of Vietnam - Vietcombank
Techcombank Vietnam Technological and Commercial Joint- stock Bank - Techcombank
MB Military Commercial Joint Stock Bank - MBBank
Vietinbank Vietnam Joint Stock Commercial Bank for Industry and Trade - Vietinbank
Agribank Vietnam Bank for Agriculture and Rural Development - Agribank
DongABank DongA Joint Stock Commercial Bank - DongABank
Oceanbank Ocean Commercial One Member Limited Liability Bank - Oceanbank
BIDV Bank for Investment and Development of Vietnam - BIDV
SHB Saigon – Hanoi Commercial Joint Stock Bank - SHB
VIB Vietnam International Commercial Joint Stock Bank - VIB
MaritimeBank Vietnam Maritime Commercial Joint Stock Bank - MaritimeBank
Eximbank Vietnam Export Import Commercial Joint Stock Bank - Eximbank
Master Master
Visa Visa
Jcb Jcb
ACB Asia Commercial Joint Stock Bank - ACB
HDBank Ho Chi Minh City Development Joint Stock Commercial Bank - HDBank
NamABank Nam A Commercial Joint Stock Bank - NamABank
SaigonBank Saigon Bank for Industry and Trade - SaigonBank
Sacombank Saigon Thuong Tin Commercial Joint Stock Bank - Sacombank
VietABank VietNam Asia Commercial Joint Stock Bank - VietABank
VPBank Vietnam Prosperity Joint-Stock Commercial Bank - VPBank
TienPhongBank Tien Phong Commercial Joint Stock Bank - TienPhongBank
SeaABank Southeast Asia Commercial Joint Stock Bank - SeABank
PGBank Petrolimex Group Commercial Joint Stock Bank - PGBank
NCB National Citizen Bank - NCB
GPBank Global Petro Commercial Joint Stock Bank - GPBank
BACABANK Bac A Commercial Joint Stock Bank - BacABank
OCB Orient Commercial Joint Stock Bank - OCB
LienVietPostBank Lien Viet Post Joint Stock Commercial Bank - LienVietPostBank
ABBANK An Binh Commercial Join Stock Bank - ABBank
PVcomBank Vietnam Public Joint Stock Commercial Bank - PVcomBank
BVB Bao Viet Joint Stock Commercial Bank - BaoVietBank
SCBBank Sai Gon Joint Stock Commercial Bank - SCB
KienLongBank Kien Long Commercial Joint Stock Bank - Kienlongbank
VRB Vietnam - Russia Joint Venture Bank - VRB
PublicBank Public Bank

Appendix of countries list

country code country name
AFAfghanistan AF
AXAland Islands AX
ALAlbania AL
DZAlgeria DZ
ASAmerican Samoa (US) AS
ADAndorra AD
AOAngola AO
AIAnguilla (UK) AI
AQAntarctica AQ
AGAntigua and Barbuda AG
ARArgentina AR
AMArmenia AM
AWAruba AW
AUAustralia AU
ATAustria AT
AZAzerbaijan AZ
BSBahamas BS
BHBahrain BH
BDBangladesh BD
BBBarbados BB
BYBelarus BY
BEBelgium BE
BZBelize BZ
BJBenin BJ
BMBermuda (UK) BM
BTBhutan BT
BOBolivia BO
BQBonaire, Sint Eustatius and Saba BQ
BABosnia and Herzegovina BA
BWBotswana BW
BVBouvet Island BV
BRBrazil BR
IOBritish Indian Ocean Territory IO
VGBritish Virgin Islands (UK) VG
BNBrunei Darussalam BN
BGBulgaria BG
BFBurkina Faso BF
BIBurundi BI
KHCambodia KH
CMCameroon CM
CACanada CA
CVCape Verde CV
KYCayman Islands (UK) KY
CFCentral African Republic CF
TDChad TD
CLChile CL
CNChina CN
CXChristmas Island (AU) CX
CCCocos (Keeling) Islands (AU) CC
COColombia CO
KMComoros KM
CDCongo, Democratic Republic of the CD
CGCongo, Republic of the CG
CKCook Islands (NZ) CK
CRCosta Rica CR
CICôte D'Ivoire CI
HRCroatia HR
CUCuba CU
CWCuraçao CW
CYCyprus CY
CZCzech Republic CZ
DKDenmark DK
DJDjibouti DJ
DMDominica DM
DODominican Republic DO
ECEcuador EC
EGEgypt EG
SVEl Salvador SV
GQEquatorial Guinea GQ
EREritrea ER
EEEstonia EE
ETEthiopia ET
FKFalkland Islands (UK) FK
FOFaroe Islands (DK) FO
FJFiji FJ
FIFinland FI
FRFrance FR
GFFrench Guiana (FR) GF
PFFrench Polynesia (FR) PF
TFFrench Southern Territories TF
GAGabon GA
GMGambia GM
GEGeorgia GE
DEGermany DE
GHGhana GH
GIGibraltar (UK) GI
GRGreece GR
GLGreenland (DK) GL
GDGrenada GD
GPGuadeloupe (FR) GP
GUGuam (US) GU
GTGuatemala GT
GGGuernsey GG
GNGuinea GN
GWGuinea-Bissau GW
GYGuyana GY
HTHaiti HT
HMHeard Island and McDonald Islands HM
VAHoly See (Vatican City) VA
HNHonduras HN
HKHong Kong (CN) HK
HUHungary HU
ISIceland IS
INIndia IN
IDIndonesia ID
IRIran IR
IQIraq IQ
IEIreland IE
IMIsle of Man IM
ILIsrael IL
ITItaly IT
JMJamaica JM
JPJapan JP
JEJersey JE
JOJordan JO
KZKazakhstan KZ
KEKenya KE
KIKiribati KI
KPKorea, Democratic People's Republic (North) KP
KRKorea, Republic of (South) KR
KWKuwait KW
KGKyrgyzstan KG
LALaos LA
LVLatvia LV
LBLebanon LB
LSLesotho LS
LRLiberia LR
LYLibya LY
LILiechtenstein LI
LTLithuania LT
LULuxembourg LU
MOMacau (CN) MO
MKMacedonia MK
MGMadagascar MG
MWMalawi MW
MYMalaysia MY
MVMaldives MV
MLMali ML
MTMalta MT
MHMarshall Islands MH
MQMartinique (FR) MQ
MRMauritania MR
MUMauritius MU
YTMayotte (FR) YT
MXMexico MX
FMMicronesia, Federated States of FM
MDMoldova Republic of MD
MCMonaco MC
MNMongolia MN
MEMontenegro ME
MSMontserrat (UK) MS
MAMorocco MA
MZMozambique MZ
MMMyanmar MM
NANamibia NA
NRNauru NR
NPNepal NP
NLNetherlands NL
ANNetherlands Antilles (NL) AN
NCNew Caledonia (FR) NC
NZNew Zealand NZ
NINicaragua NI
NENiger NE
NGNigeria NG
NUNiue NU
NFNorfolk Island (AU) NF
MPNorthern Mariana Islands (US) MP
NONorway NO
OMOman OM
PKPakistan PK
PWPalau PW
PSPalestinian Territories PS
PAPanama PA
PGPapua New Guinea PG
PYParaguay PY
PEPeru PE
PHPhilippines PH
PNPitcairn Islands (UK) PN
PLPoland PL
PTPortugal PT
PRPuerto Rico (US) PR
QAQatar QA
REReunion (FR) RE
RORomania RO
RURussia RU
RWRwanda RW
BLSaint Barthelemy BL
SHSaint Helena (UK) SH
KNSaint Kitts and Nevis KN
LCSaint Lucia LC
MFSaint Martin (French Part) MF
PMSaint Pierre & Miquelon (FR) PM
VCSaint Vincent and the Grenadines VC
WSSamoa WS
SMSan Marino SM
STSao Tome and Principe ST
SASaudi Arabia SA
SNSenegal SN
RSSerbia RS
SCSeychelles SC
SLSierra Leone SL
SGSingapore SG
SXSint Maarten (Dutch Part) SX
SKSlovakia SK
SISlovenia SI
SBSolomon Islands SB
SOSomalia SO
ZASouth Africa ZA
GSSouth Georgia & South Sandwich Islands (UK) GS
SSSouth Sudan SS
ESSpain ES
LKSri Lanka LK
SDSudan SD
SRSuriname SR
SJSvalbard and Jan Mayen SJ
SZSwaziland SZ
SESweden SE
CHSwitzerland CH
SYSyria SY
TWTaiwan TW
TJTaj ikistan TJ
TZTanzania TZ
THThailand TH
TLTimor-Leste TL
TGTogo TG
TKTokelau TK
TOTonga TO
TTTrinidad and Tobago TT
TNTunisia TN
TRTurkey TR
TMTurkmenistan TM
TCTurks and Caicos Islands (UK) TC
TVTuvalu TV
UGUganda UG
UAUkraine UA
AEUnited Arab Emirates AE
GBUnited Kingdom GB
USUnited States US
UMUnited States Minor Outlying Islands UM
UYUruguay UY
UZUzbekistan UZ
VUVanuatu VU
VEVenezuela VE
VNVietnam VN
VIVirgin Islands (US) VI
WFWallis and Futuna (FR) WF
EHWestern Sahara EH
YEYemen YE
ZMZambia ZM
ZWZimbabwe ZW

Appendix of states list

state code state name
ALAlabama
AKAlaska
ASAmerican Samoa
AZArizona
ARArkansas
CACalifornia
COColorado
CTConnecticut
DEDelaware
DCDistrict of Columbia
FMFederated States of Micronesia
FLFlorida
GAGeorgia
GUGuam
HIHawaii
IDIdaho
ILIllinois
INIndiana
IAIowa
KSKansas
KYKentucky
LALouisiana
MEMaine
MHMarshall Islands
MDMaryland
MAMassachusetts
MIMichigan
MNMinnesota
MSMississippi
MOMissouri
MTMontana
NENebraska
NVNevada
NHNew Hampshire
NJNew Jersey
NMNew Mexico
NYNew York
NCNorth Carolina
NDNorth Dakota
MPNorthern Mariana Islands
OHOhio
OKOklahoma
OROregon
PWPalau
PAPennsylvania
PRPuerto Rico
RIRhode Island
SCSouth Carolina
SDSouth Dakota
TNTennessee
TXTexas
UTUtah
VTVermont
VIVirgin Islands
VAVirginia
WAWashington
WVWest Virginia
WIWisconsin
WYWyoming
ABAlberta
BCBritish Columbia
MBManitoba
NBNew Brunswick
NLNewfoundland and Labrador
NTNorthwest Territories
NSNova Scotia
NUNunavut
ONOntario
PEPrince Edward Island
QCQuebec
SKSaskatchewan
YTYukon