Tài liệu kết nối thẻ BIT

Cập nhật: September 10, 2014

 

 

 

 

 

 TÀI LIỆU

HƯỚNG DẪN ĐẤU NỐI NẠP THẺ

 

 

 

1.                  Giới thiệu

Hệ thống BIT Card (BITCard) cung cấp dịch vụ cho phép đối tác sử dụng thẻ cào BIT để nạp tiền cho tài khoản khách hàng của đối tác.

Việc đấu nối với hệ thống thẻ của BIT Card được thực hiện bằng giao thức SOAP tại địa chỉ http://ws.qpal.net/cardservice.asmx

2.                  Tài khoản đấu nối

Mỗi một đối tác sử dụng dịch vụ của BITCard được cấp một tài khoản để đấu nối với các thông tin như sau:

  • PartnerID : Định danh tài khoản của đối tác
  • SecretKey : Khóa bảo mật
  • Password : Mật khẩu dùng để truy cập BackEnd

Ngoài ra, để có thể sử dụng được các API được cung cấp bởi hệ thống, đối tác phải cung cấp địa chỉ IP của máy chủ kết nối. BITCard sẽ cấp quyền cho phép sử dụng các API dựa trên IP do đối tác cung cấp.

 

Thông tin tài khoản test là

PartnerID: TestPartner

Secretkey: gSPbAD1swWxdc1DJze::M6Rm4ZyvErW3MCWT5mmuFojd!

3.                  Thực hiện giao dịch gạch thẻ

Chức năng:

Gởi yêu cầu đến hệ thống BITCard để thực hiện giao dịch gạch thẻ (nạp thẻ)

Phương thức: Topup

Tham số đầu vào:

Tên tham số Kiểu dữ liệu Mô tả
transId String Mã giao dịch. Do đối tác tự sinh và phải duy nhất
userName String Tài khoản khách hàng nạp thẻ (lưu ý: không sử dụng tiếng Việt trong tên tài khoản)
userIP String IP khách hàng nạp thẻ
timeSpan String Chuỗi số, là UnixTime tại server của đối tác
serial String Số serial của thẻ nạp
pin String Mã của thẻ được nạp
cardType String Ký hiệu loại thẻ (BIT)
partnerId String Định danh của đối tác
signature String Chữ ký bảo mật

Quy tắc tạo chữ ký:

Signature = MD5(transID+userName+timeSpan+serial+pin+partnerId+secretKey)

Kết quả:

Kết quả trả về là chuỗi đối tượng JSON có dạng:

{

”Code”: code,

”Message”: message,

”Amount”: amount

}

Trong đó

  • Code : Số kiểu int cho biết việc nạp thẻ thành công hay không (1: thành công, khác: không thành công)
  • Message: thông báo kết quả thực hiện giao dịch
  • Amount: Là số tiền mệnh giá của thẻ nạp (trong trường hợp nạp thẻ thành công). Nếu nạp thẻ không thành công, giá trị của Amount là 0.

4.                  Truy vấn giao dịch

Chức năng:

Truy vấn để kiểm tra lại kết quả của một giao dịch nạp thẻ đã thực hiện

Phương thức: QueryTransaction

Tham số đầu vào:

Tên tham số Kiểu dữ liệu Mô tả
transId String Mã giao dịch cần truy vấn
timeSpan String Chuỗi số, là UnixTime tại server của đối tác
serial String Số serial của thẻ nạp
pin String Mã của thẻ được nạp
cardType String Ký hiệu loại thẻ (BIT)
partnerId String Định danh của đối tác
signature String Chữ ký bảo mật

Quy tắc tạo chữ ký:

Signature = MD5(transId+timeSpan+serial+pin+partnerId+secretKey)

Kết quả:

Kết quả trả về là chuỗi đối tượng JSON có dạng:

{

”Code”: code,

”Message”: message,

”UserName” : username,

”Amount”: amount

}

Trong đó

  • Code : Số kiểu int cho biết việc nạp thẻ thành công hay không (1: thành công, khác: không thành công)
  • Message: thông báo kết quả thực hiện giao dịch
  • UserName: Tài khoản khách hàng nạp thẻ
  • Amount: Là số tiền mệnh giá của thẻ nạp (trong trường hợp nạp thẻ thành công). Nếu nạp thẻ không thành công, giá trị của Amount là 0.

5.                  Bảng mã lỗi

Mã lỗi Giải thích
1 Nạp thẻ thành công
0 Giao dịch đang được xử lý
-1 Thẻ không tồn tại
-2 Thẻ đã được sử dụng
-3 Thẻ đã hết hạn sử dụng
-10 Mã giao dịch bị trùng
-11 Giao dịch không tồn tại
-20 Đối tác không hợp lệ
-21 Chữ ký sai
-22 IP chưa được xác thực
-23 Đối tác tạm không được sử dụng dịch vụ
-98 Tham số đầu vào không hợp lệ
-99 Lỗi khác

6.                  Hỗ trợ kết nối

Để được hỗ trợ kết nối hệ thống thẻ BIT, vui lòng liên hệ chị: Trần Lê Phương Nhi

Email: phuongnhi@qpal.vn

Mobile: 01653 761207

Skype: tranlephuongnhi

 

Tài liệu thuộc bản quyền Qpal