Lịch sử cập nhật

Phiên bản Ngày thực hiện Nội dung Người thực hiện
2.0 09/26/2016 Tạo mới Khúc Chí Huân

Demo tích hợp

Giới thiệu chung

Đây là tài liệu mô tả kết nối thanh toán giữa cổng VTC Pay trong vai trò là đơn vị thanh toán và Merchant Shop (hệ thống của đối tác) trong vai trò là đơn vị bán hàng, sử dụng chức năng thanh toán trực tuyến của VTC Pay qua ví điện tử VTC Pay và tài khoản ngân hàng (internet banking nội địa và quốc tế)

Tài liệu mô tả các chức năng cần thiết mà hệ thống 2 bên cần có cho việc tích hợp, trao đổi thông tin

Tài liệu mô tả luồng dữ liệu qua lại giữa hai hệ thống trong quá trình giao dịch

Qui định các chuẩn trao đổi dữ liệu và các biện pháp đảm bảo an toàn cũng như xác thực nguồn gốc giao dịch

Thông số test sandbox

Webiste VTC Pay để vào đăng ký website tích hợp, xem lịch sử giao dịch:

http://alpha1.vtcpay.vn/wallet

Url gửi thông tin thanh toán đơn hàng:

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

Tài khoản test:

Thông tin tài khoản Merchant test, dùng đăng nhập VTC Pay để đăng ký tích hợp website bán hàng, xem lịch sử giao dịch :

Account:  0963465816
Password: Aa@123456

Thông tin tài khoản ví VTC Pay để test thanh toán đơn hàng:

Account:  01657758300
Password: Abcd1234

Thẻ Visa test thanh toán bằng thẻ quốc tế:

Số thẻ:  4111111111111111
Zip/Postal Code: 123
CardType: Visa
CVN: 123
Exprition Date: 01/2020
Các thông tin còn lại: Nhập bất kỳ, chỉ cần đúng định dạng

Thẻ test ngân hàng Techcombank:

Số thẻ:  9704000000000018
Tên chủ thẻ: NGUYEN VAN A
OTP: otp
Ngày mở thẻ: 03/07 (MM/yy)

Thông số triển khai thật

Website VTC Pay:

https://vtcpay.vn/

Url gửi thông tin thanh toán đơn hàng:

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

Lưu ý: Dữ liệu test và thật là hai dữ liệu riêng biệt, do vậy khi triển khai thật bạn cần:
- Có tài khoản VTC Pay để tạo website tích hợp và dùng làm tài khoản hứng tiền
- Tạo website tích hợp

Hướng dẫn đăng ký website tích hợp thanh toán

Để đăng ký tích hợp thanh toán qua cổng VTC Pay, Merchant cần đăng nhập vào tài khoản trên VTC Pay, truy cập vào menu "Tích hợp thanh toán, chọn Tích hợp website” để đăng ký một website tích hợp. VTC Pay sẽ hiện ra trang quản lý các website tích hợp của Merchant. Điền các thông tin cần thiết và làm theo yêu cầu để hoàn thành đăng ký tích hợp.

Minh họa đăng ký một website tích hợp:

Đăng Ký

Chú ý:

Url nhận kết quả: Là địa chỉ nhận kết quả giao dịch thanh toán đơn hàng từ VTC Pay theo POST. Như khai báo ở trên thì sau khi hoàn thành giao dịch VTC sẽ post kết quả về trang đón của Merchant là: http://www.kidsplaza.vn/Result.html

Nếu không truyền Url Redirect trên đơn hàng, VTC cũng redirect khách hàng về Url nhận kết quả

Mã bí mật: Là thông tin thêm vào khi tạo chữ ký theo chữ ký bằng SHA256. Mã bí mật phải bao gồm số, ký tự hoa, thường và nên có độ dài ít nhất 16 ký tự.

Biểu phí tích hợp: có hai lựa chọn để người bán quyết định ai chịu phí ngân hàng (Người mua hay Merchant phải chịu)
Ví dụ: Một đơn hàng giá trị 100000 VND, thanh toán qua ngân hàng VietComBank, phí ngân hàng là 3000.
Nếu chọn gói phí NH2: Phí tính cho người bán → Khách hàng bị trừ 100000 tại ngân hàng, tài khoản hứng của Merchant sẽ được nhận (100000 – 3000 = 97000)
Nếu chọn phí NH1: Phí tính cho người mua → Khách hàng bị trừ 103000 tại ngân hàng, tài khoản hứng của Merchant được nhận 100000

Tích hợp mã nguồn mở

Tích hợp Ví điện tử và Cổng thanh toán VTC Pay cho hệ thống CMS, mã nguồn mở: Cho phép hiển thị nút thanh toán qua cổng thanh toán VTC Pay trên toàn bộ các sản phẩm, dịch vụ của website được tạo từ các nền tảng sau:

Lập trình tích hợp thanh toán

Sơ đồ thanh toán bằng tài khoản ngân hàng

Đăng Ký

Tham số merchant request

Tên tham sốKiểu dữ liệuBắt buộc (*)Mô tả
amountdoubleYSố tiền thanh toán:
- Với VNĐ thì để kiểu int
- Với USD làm tròn đến hai số thập phân
bill_to_addressString(100)NĐịa chỉ khách hàng (Số nhà, đường phố …)
bill_to_address_cityString(100)NThành phố
bill_to_emailString(100)NEmail khách hàng
bill_to_forenameString(50)NTên (Ex: Hùng)
bill_to_phoneString(30)NSố điện thoại khách hàng
bill_to_surnameString(50)NHọ (Ex: Nguyễn Văn)
countryString(5)NQuốc gia của khách hàng. Khi truyền tham số merchant truyền theo bảng mã quốc gia. Mã quốc gia được liệt kê trong phần phụ lục
currencystring(5)YLoại tiền tệ muốn thanh toán:
    - VND
    - USD
languagestringNNgôn ngữ sẽ hiển thị trên site VTC. Nếu không truyền mặc định là tiếng Việt:
    vi: Việt Nam
    en: English
payment_typestringNLoại thanh toán. Truyền các giá trị sau:
VTCPay: Thanh toán bằng số dư Pay
DomesticBank: Chỉ thanh toán bằng ngân hàng nội địa InternationalCard: Chỉ thanh toán bằng thẻ quốc tế Trường hợp muốn thanh toán bằng ngân hàng cụ thể, truyền giá trị Mã ngân hàng được liệt kê trong phần phụ lục
postcodeString(50)NMã bưu điện của tỉnh/thành phố của khách hàng
receiver_accountstringYTài khoản nhận tiền của đối tác khi giao dịch thành công
reference_numberstring(30)YMã tham chiếu của đối tác tích hợp. Mã này phải duy nhất và dùng làm cơ sở hai bên đối soát, kiểm tra
transaction_typestringNsale
url_returnstringNUrl của Merchant mà VTC sẽ redirect khách hàng sau khi kết thúc giao dịch. Nếu không truyền thì sẽ lấy url khi đăng ký tạo website
website_idintYMã websiteid đối tác tạo trên hệ thống VTC
signaturestringYChữ ký, SHA (256). Text để tạo chữ ký bao gồm các tham số truyền trên Url và SecretKey. Các trường sắp xếp theo trật tự alphabe ngăn nhau bởi ký tự “|”, Ví dụ: Trường hợp request có năm tham số amount, currency, receiver_account, reference_number, website_id thì: plaintext = string.Format("{0}|{1}|{2}|{3}|{4}|{5}", amount, currency, receiver_account, reference_number, website_id, Security_Key);
stateString(5)NBang của khách hàng. Khi truyền tham số merchant truyền theo bảng mã bang. Mã bang được liệt kê trong phần phụ lục

(*). Các tham số có trường Bắt buộc là:
        Y : Phải truyền giá trị tham số này trên url
        N : Có thể truyền null, empty hoặc không cần truyền trên url

Trường signature: Nếu truyền đủ hết các tham số thì text để tạo chữ ký sẽ như sau là giá trị các tham số và secreKey xếp lần lượt như sau:


                      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(Mã bảo mật): Giá trị của trường Mã bảo mật lúc tạo website
Trường hợp có một số tham số không truyền trên url request thì text tạo chữ ký không có tham số đó.
Ví dụ, trên request thanh toán đơn hàng không có tham số bill_to_address_city, transaction_type, url_return. Khi đó text để ký sẽ như sau:

                      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
                      

Kết quả trả về theo phương thức POST ( Server to Server)

HTTP POST là hình thức giao tiếp Server to Server. Dữ liệu sẽ được post từ server VTC Pay tới trang đón của Merchant, là trang khai báo khi tạo website tích hợp. VTC luôn post kết quả giao dịch về trang đón này. Với cách nhận kết quả qua phương thức POST này:

Giúp Merchant luôn nhận được kết quả, hạn chế được tình trạng không nhận được kết quả trong trường hợp sử dụng HTTP Get do khách hàng tắt trình duyệt khi đang giao dịch, vấn đề truyền internet của khách hàng

Giúp Merchant nhận được kết quả cuối cùng với các giao dịch Review, cần duyệt lại khi quản trị của VTC Pay duyệt giao dịch.

Giúp Merchant so sánh kết quả nhận được qua phương thức GET được trình bày ở phần sau nhằm hạn chế rủi ro


Các tham số kết quả thanh toán đơn hàng VTC Pay trả về trang đón tại hệ thống Merchant

TrườngKiểuBắt buộcMô tả
data string Y amount|message|payment_type|reference_number| status|trans_ref_no|website_id
signature string Y Mã hóa SHA256 (UTF8 Encoding) các trường theo format như sau: 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

Chú ý: Khi nhận được kết quả trả về, merchant phải kiểm tra lại số tiền trả về có khớp với số tiền đã truyền lên không. Nếu không khớp thì kết quả trả về không hợp lệ, cần phối hợp với VTC để check lại

Kết quả trả về theo phương thức HTTP GET

Sau khi thanh toán xong, VTC Pay sẽ redirect khách hàng về trang đón của Merchant, đồng thời trả kết quả thanh toán cho Merchant qua các tham số trên Url.

Chi tiết các tham số trả về:

Trường Kiểu Bắt buộc Mô tả
amount int Y Giá trị đơn hàng, là số tiền của đơn hàng tại hệ thống Merchant
message string N Thông tin bổ xung
payment_type string N Hình thức thanh toán khách hàng thực hiện giao dịch
reference_number string(50) Y Mã đơn hàng Merchant gửi lên
status int Y Xem phụ lục
trans_ref_no Mã tham chiếu VTC
website_id int Y Mã của website đăng ký trên VTC Pay, xem trong phần quản lý tích hợp website trong VTC Pay
signature string Y Mã hóa SHA256 (UTF8 Encoding) các trường theo alphabet, rồi cộng thêm secret_key ở cuối. Lần lượt như sau: Amount|message|paymentType|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

Chú ý: Khi nhận được kết quả trả về, merchant phải kiểm tra lại số tiền trả về có khớp với số tiền đã truyền lên không. Nếu không khớp thì kết quả trả về không hợp lệ, cần phối hợp với VTC để check lại

Phụ lục

Phụ lục kết quả

Status Mean Ghi chú
0 Giao dịch ở trạng thái khởi tạo
1 SUCCESS Giao dịch thành công
7 REVIEW Tài khoản thanh toán của khách hàng đã bị trừ tiền nhưng tài khoản của Merchant chưa được cộng tiền. Bộ phận quản trị thanh toán của VTC sẽ duyệt để quyết định giao dịch thành công hay thất bại
-1 FAIL Giao dịch thất bại
-9 FAIL Khách hàng tự hủy giao dịch
-3 FAIL Quản trị VTC hủy giao dịch
-4 FAIL Thẻ/tài khoản không đủ điều kiện giao dịch (Đang bị khóa, chưa đăng ký thanh toán online …)
-5 FAIL Số dư tài khoản khách hàng (Ví VTC Pay, tài khoản ngân hàng) không đủ để thực hiện giao dịch
-6 FAIL Lỗi giao dịch tại VTC
-7 FAIL Khách hàng nhập sai thông tin thanh toán ( Sai thông tin tài khoản hoặc sai OTP)
-8 FAIL Quá hạn mức giao dịch trong ngày
-22 FAIL Số tiền thanh toán đơn hàng quá nhỏ
-24 FAIL Đơn vị tiền tệ thanh toán đơn hàng không hợp lệ
-25 FAIL Tài khoản VTC Pay nhận tiền của Merchant không tồn tại.
-28 FAIL Thiếu tham số bắt buộc phải có trong một đơn hàng thanh toán online
-29 FAIL Tham số request không hợp lệ
-21 CHECK Trùng mã giao dịch, Có thể do xử lý duplicate không tốt nên mạng chậm hoặc khách hàng nhấn F5 bị, hoặc cơ chế sinh mã GD của đối tác không tốt nên sinh bị trùng, đối tác cần kiểm tra lại để biết kết quả cuối cùng của giao dịch này
-23 CHECK WebsiteID không tồn tại
-99 CHECK Lỗi chưa rõ nguyên nhân và chưa biết trạng thái giao dịch. Cần kiểm tra để biết giao dịch thành công hay thất bại

Phục lục danh sách ngân hàng

Mã ngân hàng Tên ngân hàng
Vietcombank Ngân hàng Ngoại Thương Việt Nam
Techcombank Ngân hàng Kỹ thương Việt Nam
MB Ngân hàng Quân Đội MB
Vietinbank Ngân hàng Công thương Việt Nam Vietinbank
Agribank Agribank - Ngân hàng Nông nghiệp & Phát triển Nông thôn
DongABank Ngân hàng Đông Á
Oceanbank Ngân hàng Đại Dương Ocean Bank
BIDV Ngân hàng Đầu tư và Phát triển Việt Nam BIDV
SHB Ngân hàng Sài Gòn – Hà Nội SHB
VIB Ngân hàng Quốc tế VIB
MaritimeBank Ngân hàng Hàng Hải Việt Nam Maritime Bank
Eximbank Ngân hàng Xuất Nhập Khẩu Việt Nam Eximbank
Master Master
Visa Visa
Jcb Jcb
ACB Ngân hàng Á Châu ACB
HDBank Ngân hàng Phát Triển Nhà TP. Hồ Chí Minh HDBank
NamABank Ngân hàng Nam Á Nam A Bank
SaigonBank Ngân hàng Sài Gòn Công Thương SAIGONBANK
Sacombank Ngân hàng Sài Gòn Thương Tín Sacombank
VietABank Ngân hàng Việt Á VietABank
VPBank Ngân hàng Việt Nam Thịnh Vượng VPBank
TienPhongBank Ngân hàng TMCP Tiên Phong TienPhongBank
SeaABank Ngân hàng Đông Nam Á SeABank
PGBank Ngân hàng Thương mại Cổ phần Xăng dầu Petrolimex PGBank
NCB Ngân hàng TMCP Quốc dân
GPBank Ngân hàng Thương mại TNHH MTV Dầu khí Toàn Cầu
BACABANK Bac A Bank
OCB Phương Đông
LienVietPostBank Ngân hàng TMCP Bưu Điện Liên Việt
ABBANK Ngân hàng TMCP An Bình
PVcomBank Ngân hàng TMCP Đại Chúng PVcomBank
BVB Ngân hàng TMCP Bảo Việt
SCBBank Ngân hàng TMCP Sai Gon Bank
KienLongBank Ngân hàng TMCP Kiên Long
VRB Ngân hàng Liên doanh Việt - Nga
PublicBank Ngân hàng Public Việt Nam

Phục lục danh sách quốc gia

Mã quốc gia Tên quốc gia
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

Phục lục danh sách bang

Mã bang Tên bang
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