1. Lịch sử cập nhật

2. Demo tích hợp

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

Quy đị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

2.2. Thông số test sandbox

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

https://alpha1.vtcpay.vn/wallet/

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

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

Tài khoản nhận tiền của Merchant:

Account:  0963465816
Password: Aa@123456
OTP: 123456

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

Website VTC Pay:

https://alpha1.vtcpay.vn/wallet/

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

https://alpha1.vtcpay.vn/portalgateway/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

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

3.1. Hướng dẫn đăng ký profile merchant

BÆ°á»›c 1

BÆ°á»›c 2

BÆ°á»›c 3

3.2. Hướng dẫn đăng ký WebsiteID

Để có thể tích hợp thanh toán qua cổng thanh toán VTC Pay, Merchant cần đăng ký thông tin tích hợp website. VTC Pay sẽ thực hiện quản lý các website tích hợp của Merchant.

Sau đây là các bước chi tiết để Merchant có thể đăng ký thông tin tích hợp website cho mình:

BÆ°á»›c 1

BÆ°á»›c 2

BÆ°á»›c 3

Lưu ý:

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

Đối với tài khoản Merchant trên môi trường test được cung cấp, đã có sẵn các profile nên Merchant không cần tạo mới profile cho tài khoản. Tuy nhiên khi tích hợp trên môi trường thật, Merchant cần tạo được profile cho tài khoản trước khi có thể tiến hành tạo và đăng ký tích hợp website . Tham khảo mục HƯỚNG DẪN TẠO PROFILE CHO TÀI KHOẢN MERCHANT!

4. 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:

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

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

5.2. Tham số merchant request

5.2.1. Tham số merchant request

(*). 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|customerid|language|payment_type|postcode|reference_number|transaction_type|url_return|website_id|SecurityCode|state
                      

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

5.2.2. Thanh toán và lưu liên kết thẻ

Trong trường hơp merchant có truyền thêm mã định danh khách hàng (customerID), khi khách hàng thực hiện thanh toán trên cổng thanh toán VTC lần đầu sẽ có thể chọn lưu lại liên kết thẻ để thanh toán cho các lần sau. Kể từ lần thanh toán thứ 2, khách hàng không cần nhập lại thông tin thẻ mà chỉ cần xác thực OTP để hoàn tất thanh toán

- Giao diện thanh toán lần đầu:

- Giao diện thanh toán kể từ lần thứ 2 khi có mã định danh khách hàng:

5.3. Kết quả trả về

5.3.1. Kết quả trả về theo phương thức POST

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

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

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

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

6. MERCHANT API

6.1. Tra cứu lịch sử bán hàng

-Thông tin API: Tra cứu lịch sử bán hàng

 Alpha test:  https://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
 Phương thức:  POST 

- Request Data:

 RevceiverAccount:  Tài khoản ví
 intergratedID:  ID tích hợp AppID hoặc WebsiteID
 merchantType:  WEBSITE hoặc APP
 fromDate:  Ngày bắt đầu lấy lịch sử (2017-01-01)
 toDate:  Ngày kết thúc lấy lịch sử (2017-11-01)
 sign:  MD5(keysign + RevceiverAccount + intergratedID + merchantType + fromDate + toDate + mã bảo mật web/app) 

 ResponseCode = 1:  Lấy lịch sử thành công
 ResponseCode != 1:  Lấy lịch sử không thành công
 ResponseCode = -50:  Tài khoản không tồn tại
 ResponseCode = -1002:  Sai chữ ký
 ResponseCode = -601/-602:  Thông tin tích hợp không đúng
 ResponseCode = -603:  Thời gian không hợp lệ
 ResponseCode = -604:  Tối đa 31 ngày
 ResponseCode = -605:  Website không tồn tại với tài khoản
 OrderStatus = 1  Đơn hàng thành công
 OrderStatus = 2  Đơn hàng thất bại
 OrderStatus = 3  Đơn hàng nghi vấn chờ duyệt
 

6.2. Tra cứu chi tiết giao dịch

-Thông tin API: Tra cứu chi tiết giao dịch

 Alpha test:  https://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
 Phương thức:  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 + mã bảo mật web/app) 

 ResponseCode = 1:  Thành công
 ResponseCode != 1:  Không thành công
 ResponseCode = -50:  Tài khoản không tồn tại
 ResponseCode = -1002:  Sai chữ ký
 ResponseCode = -600/-601/-602:  Thông tin tích hợp không đúng
 ResponseCode = -603:  Danh sách mã đơn hàng merchant rỗng
 ResponseCode = -604:  App không tồn tại với tài khoản
 ResponseCode = -605:  Website không tồn tại với tài khoản
 ResponseCode = -701/-703: Đơn hàng không tồn tại
 ResponseCode = -705: Không tìm thấy đơn hàng của Merchant
 Status = 1:  Thành công
 Status = 2:  Thất bại
 Status = 3:  Nghi vấn
 Status = 4:  Hoàn tiền
 Status = 5:  Chờ duyệt hoàn tiền
 Status = 6:  Hủy yêu cầu hoàn tiền
 Status <= 0:  Mã đối tác không hợp lệ
 

6.3. Gửi yêu cầu hoàn tiền

-Thông tin API: Gửi yêu cầu hoàn tiền

 Alpha test:  https://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
 Phương thức:  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 + mã bảo mật web/app) 

 ResponseCode = 100:  Thành công, đã hoàn tiền
 ResponseCode = 10:  Yêu cầu hoàn tiền đã được gửi thành công, cần phê duyệt thủ công
 ResponseCode = 1:  Gửi yêu cầu hoàn thành công
 ResponseCode = -1:  Gửi yêu cầu hoàn thất bại
 ResponseCode = -2:  Đã gửi yêu cầu hoàn, vui lòng chờ quản trị viên xử lý
 ResponseCode = -3:  Đơn hàng đã được hoàn toàn bộ, không thể gửi thêm yêu cầu hoàn
 ResponseCode = -103:  Số tiền hoàn vượt quá giá trị đơn hàng
 ResponseCode = -101/-102/-104/-1001:  Gửi yêu cầu hoàn tiền không thành công. Vui lòng thử lại
 ResponseCode = -99:  Hệ thống bận, vui lòng thử lại sau
 ResponseCode = -50:  Tài khoản không tồn tại
 ResponseCode = -1002:  Sai chữ ký
 ResponseCode = -600/-601/-602:  Thông tin tích hợp không đúng
 ResponseCode = -603:  Danh sách mã đơn hàng merchant rỗng
 ResponseCode = -604:  App không tồn tại với tài khoản
 ResponseCode = -605:  Website không tồn tại với tài khoản
 ResponseCode = -700:  Thông tin hoàn tiền không hợp lệ
 ResponseCode = -701/-703: Đơn hàng không tồn tại
 ResponseCode = -704: Số tiền hoàn không hợp lệ
 ResponseCode = -705: Không tìm thấy đơn hàng của Merchant
 ResponseCode <= 0:  Lỗi hệ thống
 

6.4. Mô tả kết quả trả về

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

7. Phụ lục

7.1. Thông tin tài khoản test thanh toán

- Tài khoản VTC Pay:

Account:  0357758300
Password: Abcd1234
OTP: 123456

- Thẻ Visa test thanh toán qua thẻ quốc tế:

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

- Thẻ test thanh toán qua ngân hàng nội địa Techcombank:

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

7.2. Kết quả đơn hàng

7.3. Danh sách ngân hàng

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

7.5. Phục lục danh sách bang