1. Update history

Version Date Content Editor
2.1 11/03/2021 Update and supplement information Le Thanh Tung

2. Integrated demo

2.1. Introduction

This is a document describing the payment connection between the VTC Pay portal as a payment unit and Merchant Shop (partner's system) as a sales unit, using the online payment function of VTC Pay via VTC Pay Ewallet 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

2.2. Alpha Test Parameters

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


Url sending order payment information :


Merchant's receiving account

Account:  0963465816
Password: Aa@123456
OTP: 123456

2.3. Golive parameters

Website VTC Pay:


Url sending order payment information:


warning Note:Alpha test and Golive parameters are different, therefore, in this mode, Merchant need:
- Have a VTC Pay account to create an integrated website and use it as a Merchant's receiving account
- Created integrated website

3. Website Integration Registration Tutorials

To be able to integrate payment through the payment gateway VTC Pay, Merchant needs to register for website integration information. VTC Pay will manage the integrated websites of Merchants.

Here are the steps to create an integrated website:

step Step 1
Merchant log in to your receiving account, select "Website integration" in the "Payment integration" section.

step Step 2
Select "Add New" in the integrated list admin section

step Step 3
Fill out website integration information.


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.

warning For a Merchant account on the provided alpha test environment, profes are already available, so Merchant does not need to create a new profile for the account. However, when golive, Merchant needs to create a profile before you can proceed to create and sign up for website integration. Refer to the GUIDE TO CREATE PROFILE FOR MERCHANT ACCOUNT!

4. Open-source Integration

Integrating VTC Pay Ewallet and Payment Gateway for CMS system, open source: Allows displaying the payment button via the VTC Pay payment gateway on all products and services of the website created from platform after:

5. Programming Payment Integration

5.1. Payment Diagram using bank account

Đăng Ký

5.2. 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_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:


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:


5.3. Returned result

5.3.1. 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: Secret key you entered when creating website

Caution: Upon receiving the returned result, the merchant must verify that the returned amount matches the transferred amount. If there is no match, the returned result is not valid, you need to coordinate with VTC to check again

5.3.2. 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

Caution: Upon receiving the returned result, the merchant must verify that the returned amount matches the transferred amount. If there is no match, the returned result is not valid, you need to coordinate with VTC to check again.


6.1. API look up sales history information

-API information: Look up sales history information

 Alpha test:  http://alpha1.vtcpay.vn/portalgateway/api/AccountApi/MerchantSaleHistoryGetList
Live: https://vtcpay.vn/bank-gateway/api/AccountApi/MerchantSaleHistoryGetList
Key sign: 1!2@3#4$5%
Sign: MD5
Method: POST

- Request Data:

 RevceiverAccount: VTC Pay account
intergratedID: AppID or WebsiteID
merchantType: WEBSITE or APP
fromDate: Start date to get information (2017-01-01)
toDate: End date to get information (2017-11-01)
sign: MD5(keysign + RevceiverAccount + intergratedID + merchantType + fromDate + toDate + secret key web/app)
- Response Data:
- Error description:
 ResponseCode = 1:  Get sales history successful
ResponseCode != 1: Get sales history fail
OrderStatus = 1 Order successful
OrderStatus = 2 Order failed
OrderStatus = 3 Order awaiting approval

6.2. API look up transaction details

-API information: look up transaction details

 Alpha test:  http://alpha1.vtcpay.vn/portalgateway/api/AccountApi/VTCPayGetOrderStatus
Live: https://vtcpay.vn/bank-gateway/api/AccountApi/VTCPayGetOrderStatus
Key sign: 1!2@3#4$5%
Sign: MD5
Method: POST

- Request Data:

 RevceiverAccount:  VTC Pay account
intergratedID: AppID or WebsiteID
merchantType: WEBSITE hoặc APP
sign: MD5(keysign + RevceiverAccount + intergratedID + merchantType + secret key web/app)
- Response Data:
- Error description:
ResponseCode = 1:  Success
ResponseCode != 1: Fail
Status = 1: Success
Status = 2: Fail
Status = 3: Pending
Status = 4: Refunded
Status = 5: Waiting for refund approval
Status = 6: Cancel a refund request
Status <= 0: Invalid partner code

6.3. API refund

-API information: Submit a refund request

 Alpha test:  http://alpha1.vtcpay.vn/portalgateway/api/AccountApi/RefundMoneyVTC
Live: https://vtcpay.vn/bank-gateway/api/AccountApi/RefundMoneyVTC
Key sign: 1!2@3#4$5%
Sign: MD5
Method: POST

- Request Data:

 RevceiverAccount:  Tài khoản ví
intergratedID: ID tích hợp AppID hoặc WebsiteID
merchantType: WEBSITE hoặc APP
sign: MD5(keysign + RevceiverAccount + intergratedID + merchantType + secret key web/app)
- Response Data:
- Error description:
 ResponseCode = 100:  Successful, refunded
ResponseCode = 1: Submit refund request successfully, waiting for approval
ResponseCode = -1: Failed to submit refund request
ResponseCode = -1: Refund request submitted, cannot be resubmitted
ResponseCode <= 0: System error

7. Appendix

7.1. Payment alpha test account information

- VTC Pay account:

Account:  0357758300
Password: Abcd1234
OTP: 123456

- Visa card :

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

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

Card number: 9704 0000 0000 0018 
Card name: NGUYEN VAN A
OTP: otp
Open date: 03/07 (MM/YY)

7.2. Guide to merchant profile registration

step Step 1
Merchant log in to receiving account, select "Manage Profile" in the "Payment Integration" section.

step Step 2
Fill in the required information and select "Save".

step Step 3
Your profile has entered a pending browser. Please contact support staff for the fastest profile review

7.3. 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

7.4. 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

7.5. 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
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
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
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
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
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
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
NFNorfolk Island (AU) NF
MPNorthern Mariana Islands (US) MP
NONorway NO
PKPakistan PK
PWPalau PW
PSPalestinian Territories PS
PAPanama PA
PGPapua New Guinea PG
PYParaguay PY
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
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

7.6. Appendix of states list

state code state name
ASAmerican Samoa
DCDistrict of Columbia
FMFederated States of Micronesia
MHMarshall Islands
NHNew Hampshire
NJNew Jersey
NMNew Mexico
NYNew York
NCNorth Carolina
NDNorth Dakota
MPNorthern Mariana Islands
PRPuerto Rico
RIRhode Island
SCSouth Carolina
SDSouth Dakota
VIVirgin Islands
WVWest Virginia
BCBritish Columbia
NBNew Brunswick
NLNewfoundland and Labrador
NTNorthwest Territories
NSNova Scotia
PEPrince Edward Island