File Goc 771103

CÔNG TY CỔ PHẦN GIẢI PHÁP THANH TOÁN VIỆT NAM
Simplify the life
TÀI LIỆU ĐẶC TẢ KỸ THUẬT

KẾT NỐI DỊCH VỤ VNTOPUP
Mã hiệu tài liệu: Partner_Interface
Phiên bản: 2.0
Hà Nội, tháng 1 năm 2009

Tài liệu kết nối VnTopup v1.03
Bảng ghi nhận thay đổi tài liệu
Phiên
Ngày thay Vị trí thay Phiên
Lý do Người sửa Mô tả thay đổi bản
đổi đổi bản cũ
mới
17/01/09 Thuynt Publish 1.00
19/05/09 2.2, 2.3, III Bổ sung Thuynt 1.00 Bổ sung 1.01
GetBalance,
GetTransaction,
Ghi chú
21/05/09 Dữ liệu Sign Sửa đổi Thuynt 1.01 Sửa thông tin Sign, 1.02
kết quả do Bổ sung mã lỗi.
VnPay trả
ra.
RespCode
29/05/09 2.1 - Dữ liệu Bổ sung Thuynt 1.02 Bổ sung thông tin: 1.03
kết quả trả Balance, Amount.
ra. Sửa thông tin Sign.
21/09/2011 2.2 Bổ sung Vinhnc 1.03 Thêm mô tả hàm 1.03
TopupPostp TopupPostpaid
aid
16/05/2012 2.2 Sửa đổi, Bổ Vinhnc 1.03 Bỏ hàm 2.0
GetViettelCa sung ToupPostPaid,
rd thêm hàm
GetViettelCard
22/08/2012 IV Bổ sung Vinhnc 2.0 Thêm quy trình đối 2.0
chiếu
19/11/2012 I Bổ sung Vinhnc 2.0 Thêm hàm 2.0.1
GetTransactionCar
d
Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 2/14

MỤC LỤC
I. Thực hiện gọi lệnh....................................................................................................................4
1. Địa chỉ webservice..............................................................................................................4
2. Các hàm chức năng.............................................................................................................4
2.1 TopupMobile...............................................................................................................4
2.2 GetCard.......................................................................................................................5
2.3 GetBalance..................................................................................................................8
2.4 GetTransaction............................................................................................................9
2.5 GetTransactionCard...................................................................................................10
2.6 GetMaxTrace.............................................................................................................11
II. Bảng mã lỗi............................................................................................................................12
III. Ghi chú.................................................................................................................................12
IV. Quy trình đối chiếu..............................................................................................................14
4.1. Mô tả quy trình và thời gian gửi file.............................................................................14
4.2. Định dạng file trao đổi giữa VNPAY – PARTNER......................................................14

I. Thực hiện gọi lệnh
1. Địa chỉ webservice.
Mô tả Chi tiết Ghi chú

URL Live http://210.245.12.219:1122/Vn Địa chỉ URL Webservice
pSrv.asmx?wsdl Topup của VnPay.
URL Test http://210.245.12.220:19061/Pa
rtner/VnpSrv.asmx ?wsdl
2. Các hàm chức năng.
2.1 TopupMobile
Gởi thông tin yêu cầu nạp tiền điện thoại tới VnPay. Và thực hiện nạp tiền điện
thoại nếu các thông tin là hợp lệ.
Input Data:
Kiểu dữ
Tham số Mô tả
liệu
MobileNo Ký tự Số điện thoại cần nạp, theo định dạng 0xxxx…
Amount Number Số tiền cần nạp. Theo các mệnh giá sau: 10000;
20000; 30000; 50000; 100000; 200000; 300000;
500000.
Trace Number Số Trace tại đối tác. Không được trùng lặp thông tin
trong ngày (1-999999).
LocalDateTime Ký tự Thời gian phát sinh giao dịch tại nơi yêu cầu, theo
định dang: yyyyMMddHHmmss.
PartnerCode Ký tự Mã doanh nghiệp do VnPay cung cấp.
Sign Ký tự Chữ ký điện tử của doanh nghiệp trên các thông tin:
MobileNo-Amount-Trace-LocalDateTime-
PartnerCode.
Chú ý:
- Chữ ký được ký theo thuật toán RSA 1024bit (*),
chuẩn PKCS#1, bằng Private Key do Doanh nghiệp
tạo ra và bảo quản. Sau khi ký xong chuyển về dạng
Hexa.
- VnPay sẽ dùng khóa Public Key do doanh nghiệp
cung cấp để chứng thực tính toàn vẹn của các thông
tin được doanh nghiệp chuyển sang cho VnPay.

Return Data:
Kiểu dữ
Tham số Mô tả
liệu
RespCode Ký tự Trạng thái nạp tiền. 00 – Thành công, xx – Tham
chiếu bảng mã lỗi.
MobileNo Ký tự Số điện thoại được nạp, theo định dạng 0xxxx…
Trace Number Số Trace tại đối tác. Không được trùng lặp thông
tin trong ngày (1-999999).
Balance Decimal Số dư tài khoản của Partner tại VNPAY.
Amount Decimal Số tiền bị trừ tại tài khoản VNPAY.
LocalDateTime Ký tự Thời gian phát sinh giao dịch tại đối tác theo định
dạng: yyyyMMddHHmmss.
VnPayDateTime Ký tự Thời gian phát sinh giao dịch tại VnPay theo định
Sign Ký tự Chữ ký điện tử của VnPay trên các thông tin:
RespCode-MobileNo-Trace-Balance-Amount-
LocalDateTime-VnPayDateTime.
Chú ý:
PKCS#1, bằng khóa PrivateKey do VnPay tạo ra và
bảo quản. Sau khi ký xong chuyển về dạng Hexa.
- VnPay sẽ gửi cho doanh nghiệp khóa Public Key.
Doanh nghiệp sẽ dùng khóa này để chứng thực tính
toàn vẹn của các thông tin được Vnpay chuyển sang
cho doanh nghiệp.
2.2 GetCard
Gởi thông tin yêu cầu mua mã thẻ Viettel, Vinaphone, Mobifone tới VNPAY.
Input Data:
Kiểu dữ
Tham số Mô tả
liệu
ProductCode Ký tự Loại mã thẻ:
- VT: Viettel
- MB: Mobifone
- VP: Vinaphone
Amount Number Mệnh giá thẻ. Theo các mệnh giá sau: 10000;
20000; 30000; 50000; 100000; 200000; 300000;
500000.
trong ngày.
(1-999999)
LocalDateTime Ký tự Thời gian phát sinh giao dịch tại nơi yêu cầu, theo
định dang: yyyyMMddHHmmss.
Sign Ký tự Chữ ký điện tử của doanh nghiệp trên các thông tin:
PartnerCode – ProductCode - Trace - Amount -
LocalDateTime
Chú ý:
chuẩn PKCS#1, bằng Private Key do Doanh nghiệp
tạo ra và bảo quản. Sau khi ký xong chuyển về dạng
Hexa.

Return Data:
Kiểu dữ
Tham số Mô tả
liệu
RespCode Ký tự Trạng thái nạp tiền. 00 – Thành công, xx – Tham
chiếu bảng mã lỗi.
Trace Number Số Trace tại đối tác. Không được trùng lặp thông
tin trong ngày (1-999999).
Amount Decimal Số tiền bị trừ tại tài khoản VNPAY.
LocalDateTime Ký tự Thời gian phát sinh giao dịch tại đối tác theo định
PinCode Ký tự Mã số nạp tiền thẻ
Serial Ký tự Số Serial
RespCode - ProducCode- Amount -
LocalDateTime - VnPayDateTime - Trace -
Serial - PinCode
Chú ý:
PKCS#1, bằng khóa PrivateKey do VnPay tạo ra và
bảo quản. Sau khi ký xong chuyển về dạng Hexa.
cho doanh nghiệp.

2.3 GetBalance
Gởi thông tin vấn tin số dư tài khoản Partner tại hệ thống VNPAY nếu các thông
tin là hợp lệ hệ thống sẽ trả ra số dư tài khoản của Partner tại hệ thống.
Input Data:
Kiểu dữ
Tham số Mô tả
liệu
LocalDateTime Ký tự Thời gian yêu cầu tra cứu tại nơi phát sinh yêu cầu.
Sign Ký tự Chữ ký điện tử của Doanh nghiệp trên các thông tin:
PartnerCode-LocalDateTime.
Chú ý:
bằng Private Key do Doanh nghiệp tạo ra và bảo
quản. Sau khi ký xong chuyển về dạng Hexa.
Return Data:
Kiểu dữ
Tham số Mô tả
liệu
Result Number 0 – Thành công, 1 – Sai chữ ký, 2 – Hệ thống đang
Offline bảo trì, 3 – Không tìm thấy thông tin
PartnerCode, 4 – Địa chỉ IP không được cấp phép
truy cập hệ thống.
PartnerCode Ký tự Mã doanh nghiệp cho VnPay cung cấp.
Balance Number Số dư tài khoản Partner tại VnPay.
Result-PartnerCode-Balance-VnPayDateTime.
Chú ý:
- Chữ ký được ký theo thuật toán RSA (*), bằng
khóa PrivateKey do VnPay tạo ra và bảo quản. Sau
khi ký xong chuyển về dạng Hexa.
cho doanh nghiệp.

2.4 GetTransaction
Gởi thông tin tra cứu thông tin giao dịch của Partner tại hệ thống VNPAY nếu các
thông tin là hợp lệ hệ thống sẽ trả ra thông tin giao dịch của Partner tại hệ thống.
Input Data:
Kiểu dữ
Tham số Mô tả
liệu
LocalDateTime Ký tự Thời gian phát sinh giao dịch.
PartnerCode-Trace-LocalDateTime.
Chú ý:
bằng Private Key do Doanh nghiệp tạo ra và bảo
quản. Sau khi ký xong chuyển về dạng Hexa.
Return Data:
Kiểu dữ
Tham số Mô tả
liệu
Result Number 0 – Thành công, 1 – Sai chữ ký, 2 – Hệ thống đang
Offline bảo trì, 3 – Không tìm thấy thông tin
PartnerCode, 4 – Địa chỉ IP không được cấp phép
truy cập hệ thống, 5 – Không tìm thấy thông tin
giao dịch.
RespCode Ký tự xx|[xx]|[xx] (**)
PartnerCode Ký tự Mã doanh nghiệp do VNPAY cấp.
MobileNo Ký tự Số điện thoại được nạp.
Amount Number Mệnh giá nạp tiền.
LocalDateTime Ký tự Thời gian phát sinh giao dịch Partner theo định
VnPayDateTime Ký tự Thời gian phát sinh giao dịch tại VNPAY theo định
Result-RespCode-PartnerCode-MobileNo-
Amount-VnPayDateTime.
Chú ý:
- Chữ ký được ký theo thuật toán RSA (*), bằng
khóa PrivateKey do VnPay tạo ra và bảo quản. Sau
khi ký xong chuyển về dạng Hexa.
cho doanh nghiệp.
2.5 GetTransactionCard
Gởi thông tin tra cứu thông tin giao dịch mua mã thẻ của Partner tại hệ thống VNPAY nếu các
thông tin là hợp lệ hệ thống sẽ trả ra thông tin giao dịch của Partner tại hệ thống.
Input Data:
Tham số Kiểu dữ liệu Mô tả
LocalDateTime Ký tự Thời gian phát sinh giao dịch.
PartnerCode-Trace-LocalDateTime.
Chú ý:
- Chữ ký được ký theo thuật toán RSA 1024bit (*), bằng
Private Key do Doanh nghiệp tạo ra và bảo quản. Sau khi
ký xong chuyển về dạng Hexa.
- VnPay sẽ dùng khóa Public Key do doanh nghiệp cung
cấp để chứng thực tính toàn vẹn của các thông tin được
doanh nghiệp chuyển sang cho VnPay.
Return Data:
Tham số Kiểu dữ liệu Mô tả
Result String Respcode@ pincode @ serial
00@ pincode @ serial – Thành công
01@@ - Không tìm thấy giao dịch, hoặc giao dịch
không thành công.
2.6 GetMaxTrace
Lấy thông tin số trace lớn nhất ngày hiện tại.
Input Data:
Kiểu dữ
Tham số Mô tả
liệu
Return Data:
Kiểu dữ
Tham số Mô tả
liệu
Result Long >0 : Số trace lớn nhất trong ngày
-1: Exception (lỗi hệ thống, không lấy được thông
tin)

II. Bảng mã lỗi

RespCode Mô tả
00 Thành công.
01 Lỗi Telco.
03 Sai mệnh giá tiền.
04 Sai Product Code
05 Hệ thống bảo trì
06 Sai LocalDate
25 Địa chỉ IP không được cấp phép truy cập dịch vụ.
08 Time out.
09 Số Trace đã tồn tại. Hoặc sai format.
11 Trả sau.
20 Partner không tồn tại. Hoặc chưa cấp phép sử dụng dịch vụ.
22 Số điện thoại cần nạp không hợp lệ. (format)
Số điện thoại cần nạp không hợp lệ. (đúng format nhưng không
23
tồn tại số điện thoại,…)
79 Chữ ký không hợp lệ.
51 Tài khoản không đủ số dư để thực hiện giao dịch.
90 Hệ thống telco tạm ngừng giao dịch.
62 Hết mã thẻ mệnh giá cần mua. (gd mua mã thẻ)
96 Lỗi hệ thống.
99 Offline để bảo trì hệ thống.
65 Vượt quá hạn mức giao dịch trong ngày
III. Ghi chú

(*) Dùng US Secured Hash Algorithm (SHA1) để tạo chữ ký điện tử, và dùng chuẩn
RSA Encryption Standard Version 1.5 để mã hóa chữ ký điện tử trước khi gửi đi. Độ dài khóa
1024 bit.
(**) xx|[xx]|[xx] – Giao dịch từ partner sang sẽ chia làm 3 phase: [] – Dữ liệu có thể có.
- Phase 1: Trừ tiền tại hệ thống VNPAY.
- Phase 2: Nạp tiền tại hệ thống telco.
- Phase 3: Trả lại tiền cho Partner nếu không nạp được tiền tại telco.
- Chú ý: với giao dịch có mã RespCode: 08: Đây là những giao dịch nghi ngờ, sẽ
không được trả lại tiền cho khách hàng. Giao dịch này cần sự phối hợp giữa bộ phận đối
chiếu của 2 bên để kiểm tra xem đã nạp tiền thành công tại telco chưa. Nếu chưa mới
được hoàn lại tiền. Còn các trường hợp khác sẽ được tự động hoàn tiền ngay.

IV. Quy trình đối chiếu
4.1. Mô tả quy trình và thời gian gửi file
- VNPAY cấp cho PARTNER account truy cập FTP server của VNPAY để nhận và xuất
file đối chiếu.
- Địa chỉ FTP server: 210.245.12.219 . Port 21
- Trước 07:00:00 ngày T+1, VNPAY xuất file chi tiết các giao dịch thành công của
PARTNER trên hệ thống VNPAY của ngày T cho PARTNER.
+ Tên file có dạng: yymmdd_TRANS_DETAIL_PARTNERCODE.csv
+ Thư mục chứa File: Inbox
- Trước 08:00:00 ngày T+1, PARTNER sau khi nhận file của VNPAY:
+ Đồng bộ trạng thái các giao dịch giữa PARTNER & VNPAY.
+ Kết xuất file đối soát cho VNPAY
 Tên file có dạng: yymmdd_TRANS_DISPUTE_PARTNERCODE.csv
 File này gửi về cho VNPAY qua thư mục Outbox của VNPAY trên FTP
Server
 Trong file đối soát đó có chứa các giao dịch nghi vấn: respcode 31
- Trước ngày T+3 VNPAY sẽ xuất file trả lời các giao dịch nghi vấn của ngày T.
+ Tên file có dạng: yymmdd_TRANS_SOLVED_DISPUTE_PARTNERCODE.csv
+ Thư mục chứa file: Inbox
Lưu ý: Thời gian tính theo ngày làm việc (không tính các ngày lễ, chủ nhật)
Hiện tại, VNPAY sẽ xuất file Trans_Detail hàng ngày cho đối tác,
Các giao dịch nghi vấn đối tác sẽ gửi mail cho VNPAY để check lại, và kết quả
VNPAY sẽ trả lời qua Email.
4.2. Định dạng file trao đổi giữa VNPAY – PARTNER

Định dạng file : .csv, .xls
Nội dung file: Gồm 2 phần

- Dòng tiêu đề: Chứa tên các trường.
- Dòng giao dịch: Mỗi giao dịch chi tiết là 1 dòng, trường nào không có thông tin thì bỏ
trống.
STT Tên trường Mô tả

1 TraceVNPAY Partner Code
2 TracePartner Tài khoản đối tác tại VNPAY
3 PartnerCode Số trace giao dịch ghi nhận phía PARNER
4 AccountNo Số trace giao dịch ghi nhận phía VNPAY
5 MobileDes Số điện thoại được nạp (giao dịch Topup)
6 Serial Số Serial ( Giao dịch mua mã thẻ, file SOLVED trường

hợp mã trả lời 33)
7 PinCode Mã Pin ( Giao dịch mua mã thẻ, file SOLVED trường
hợp mã trả lời 33)
8 TranType 0 – Giao dịch Topup (TopupMobile)
1 – Giao dịch mua mã thẻ (GetCard)
9 Amount Mệnh giá tiền
10 DebitAmount Số tiền trừ tài khoản đối tác
11 DateTopup Thời gian giao dịch
12 RespCode Mã trả lời
- 00 (0): Giao dịch thành công ( file DETAIL
VNPAY xuất)
- 08 (8): Giao dịch Timeout, là giao dịch nghi
vấn cần đối chiếu đối soát.
- 31: Giao dịch nghi vấn (file DISPUTE Parter
xuất)
- 32: Mã trả lời giao dịch nghi vấn – Giao dịch
không thành công, hoặc không tồn tại giao dịch
trên hệ thống VNPAY.
- 33: Giao dịch thành công
- 34: Giao dịch không thành công, hoàn lại tiền
vào tài khoản đối tác.

File Goc 771103

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

File Goc 771103

Uploaded by

Copyright:

Available Formats

CÔNG TY CỔ PHẦN GIẢI PHÁP THANH TOÁN VIỆT NAM

Simplify the life

TÀI LIỆU ĐẶC TẢ KỸ THUẬT

Hà Nội, tháng 1 năm 2009

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 2/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 3/14

1. Địa chỉ webservice.

Mô tả Chi tiết Ghi chú

2. Các hàm chức năng.

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 4/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 6/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 7/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 8/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 11/14

II. Bảng mã lỗi

III. Ghi chú

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 12/14

IV. Quy trình đối chiếu

4.1. Mô tả quy trình và thời gian gửi file

4.2. Định dạng file trao đổi giữa VNPAY – PARTNER

Nội dung file: Gồm 2 phần

STT Tên trường Mô tả

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 13/14

Công ty CP Giải pháp thanh toán Việt Nam – VNPAY 14/14

You might also like