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 Sacombank Card test order payment by domestic card:

Card number:  9704030092314258
Card name: NGUYEN VAN A
OTP: 123456
Open date: 01/2017 (MM/yyyy)

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)
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
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);

(*). 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|currency|language|payment_type|receiver_account|reference_number|transaction_type|url_return|website_id|SecurityCode 
                      

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