Tích hợp thanh toán thẻ cào điện thoại

Tích hợp thanh toán bằng thẻ cào điện thoại trên hai hệ thống Bảo Kim và Ngân Lượng

I. Hệ thống Bảo Kim

          Mô tả:

·        Chuẩn webservice: restful

·        Địa chỉ webservices: https://www.baokim.vn/the-cao/restFul/send

·        Request method: POST

·        Tài khoản đăng nhập WS qua Http Digest mô tả rõ tại: http://en.wikipedia.org/wiki/Digest_access_authentication

Sơ đồ hệ thống

gdsgfsa

Tham số đầu vào

Tên tham số Kiểu dữ liệu Bắt buộc Mô tả
Merchant_id String Yes Mã MarchantID đăng ký trên Bảo Kim
api_username String Yes Api username được kỹ thuật Bảo Kim cấp
api_password String Yes Api Pwd được kỹ thuật Bảo Kim cấp
transaction_id String Yes Mã TransactionId xác định giao dịch bên khách hàng
card_id String Yes Loại thẻ cào là 1 trong số loại (VINA, MOBI, VIETTEL, VTC, GATE)
pin_field String Yes Mã Pin thẻ cào dưới lớp bạc
seri_field String Yes Mã Seri thẻ
algo_mode String No Thuật toán mã hóa tạo data_sign (md5 hoặc hmac)
data_sign String Yes Trường mô tả tính toàn vẹn dữ liệu gửi lên (Mô tả bên dưới)
   - Trong đó các tham số do Bảo kim cung cấp bao gồm:
  • merchant_id
  • api_username
  • api_password
  • secure_pass (Key bí mật) : dùng để tạo ra data_sign(xem thêm phần cơ chế bảo mật).

 

  – Bảng độ dài quy định pin_field và seri_field
Code Loại thẻ Pin_field Seri_field
VINA Vinaphone 12.14 9-15
MOBI Mobifone 12.14 9-15
VIETTEL Viettel 13-15 11-15
GATE Gate 10 10
VTC Vtc vcoin 12 12

 

Dữ liệu trả về      

Tên field Kiểu dữ liệu Mô tả
errorMessage String Nội dung lỗi
transaction_id String Mã giao dịch tương ứng với transaction_id gửi đi
amount int Mệnh giá thẻ cào thành công

 

Bảng mã lỗi

(Mã lỗi trả về dựa trên HTTP Header Status Code)

Status code Trạng thái Mô tả
200 Thành công Giao dịch nạp thành công
202 Thẻ trễ Giao dịch chưa xác định được trạng thái thành công hay không! TimeOut
450 Lỗi dữ liệu gửi lên Nội dung mô tả lỗi dữ liệu gửi lên chưa đúng
460 Lỗi kết quả trả về từ nhà mạng Nội dung mô tả lỗi thẻ cào từ nhà mạng

 

Cơ chế bảo mật

Mô tả cách tạo Field data_sign trên tham số gửi đi cần có:

  1. Dữ liệu gửi đi (rawData) = Nối liền các tham số gửi đi theo thứ tự Alphabel key dữ liệu
  2. Key bí mật (secure_pass) = Giá trị secure_pass khi đăng ký Merchant Id
  3. Thuật toán tạo data_sign = hash_hmac (“SHA1″,rawData, secure_pass)
  4. Code mẫu php tham khảo

function hmacCreateDataSign(&$args, $secure_code){
if(empty($args) || !$secure_code){
//Lỗi dữ liệu đầu vào return false;
}
//Sắp xếp thứ tự Array $args theo Key
ksort($args);
return = hash_hmac(“SHA1″,implode(“”,$args),$secure_code);
}

Quy trinh xử lý thẻ lỗi :

  • Các trường hợp thẻ lỗi hoặc không nhận được kết quả trả về khách hàng có thể đăng nhập tài khoản (Đã đồng bộ với tài khoản Bảo kim) trên napngay.com để đối soát.

II. Hệ thống nganluong.vn

  1. Giới thiệu chung

                  a.Mục đích

Mô tả chi tiết cách thức tích hợp cổng thanh toán trực tuyến Ngân Lượng để nạp tiền vào tài khoản tiền ảo                        trên ứng dụng Mobile trên JAVA của bạn sử dụng thẻ cào điện thoại.

                b. Giới hạn tài liệu

Chỉ sử dụng cho các merchant bán sản phẩm và dịch vụ nội dung số trên mobile

                c. Địa chỉ cung cấp các thông tin liên quan

  •  Môi trường live:

–   Địa chỉ đăng ký tài khoản Ngân Lượng: https://www.nganluong.vn/?portal=nganluong&page=user_register

–   Địa chỉ webservice giao tiếp của Ngân Lượng: https://www.nganluong.vn/mobile_card_api.php?wsdl

–  Hướng dẫn đăng ký tài khoản Ngân Lượng để nhận tiền bán hàng: http://help.nganluong.vn/danh-muc-56/2/1/Dang-ky-mo-tai-khoan.html

–   Hướng dẫn chứng thực tài khoản Ngân Lượng:
Sau khi đăng ký tài khoản thành công, bạn cần chứng thực tài khoản của mình, để phục vụ cho mục đích định danh tài khoản trong giao dịch rút tiền sau này http://help.nganluong.vn/danh-muc-63/2/1/Chung-thuc-tai-khoan.html

 

  1. Quy trình thực hiện kết nối

 a. Merchant đăng ký tài khoản ví điện tử Ngân Lượng

–   Thực hiện đăng ký mở tài khoản ví Ngân Lượng theo http://help.nganluong.vn/danh-muc-56/2/1/Dang-ky-mo-tai-khoan.html

–   Chứng thực tài khoản vừa đăng ký http://help.nganluong.vn/danh-muc-63/2/1/Chung-thuc-tai-khoan.html

        b. Khai báo ứng dụng của merchant trên hệ thống Ngân Lượng

Khai báo website/merchant trong phần tích hợp nâng cao của NgânLượng.vn

       c. Mô tả hàm “CardCharge

 

 

Tên hàm: CardCharge
Tham số vào (gồm 3 tham số)
STT Tên tham số Kiểu dữ liệu Bắt buộc Giải thích
1 merchant_id String(50) x Mã website/merchant đã khai báo tại NgânLượng.vn
2 checksum String(50) x Là mã MD5 của các tham số và Mật khẩu kết
nối giữa website/merchant với NgânLượng.vn
3 params String() x Là một chuỗi các giá trị ngăn cách nhau bởi dấu ‘|’, tương ứng với các tham  số như sau:
pin_card String(20) x Mã thẻ cào
type_card String(10) x Loại thẻ cào, nhận một trong các giá trị:VMS: Thẻ cào MobiFoneVNP: Thẻ cào VinaPhone

VIETTEL: Thẻ cào Viettel

ref_code String(50) x Mã duy nhất tương ứng với một khách hàng tại merchant (ví dụ: tên tài khoản, mã tài khoản,…)
merchant_account String(255) x Địa chỉ Email chính của tài khoản NgânLượng.vn mà merchant dùng để nhận tiền nạp vào từ thẻ cào
client_fullname String(255) Tên đầy đủ của khách hàng tại merchant
client_email String(255) Email khách hàng tại merchant
client_mobile String(20) Điện thoại của khách hàng tại merchant
card_serial String(20) Số serial thẻ cào
Các tham số trên được ngăn cách nhau bởi dấu gạch thẳng đứng ‘|’ theo thứ tự như sau:
params = pin_card|type_card|ref_code|merchant_account|client_fullname|client_email|client_mobile|card_serial
Trong đó, tham số checksum được mã hóa như sau:
Checksum = MD5(param + “|” + Merchant Password
(với Merchant Password là mật khẩu kết nối giữa merchant và NgânLượng.vn được khai báo khi khai báo thông tin website hoặc merchant tại NgânLượng.vn)
Tham số ra (trả về)
STT Tên tham số Kiểu dữ liệu Bắt buộc Giải thích
1 result String() Là một chuỗi các giá trị ngăn cách nhau bởi dấu ‘|’,
tương ứng với các tham số như sau:
error_code|merchant_id|transaction_id|amount|pin_card|type_card|ref_code| merchant_account|client_fullname|client_email|client_mobile
error_code String(5) Mã kết quả xử lý của hàm
merchant_id String(50) Mã website/merchant đã khai báo tại NgânLượng.vn
transaction_id String(20) Mã GD phát sinh tại NgânLượng.vn
amount Int Mệnh giá thẻ
pin_card String(20) Mã thẻ cào
type_card String(10) Loại thẻ cào, nhận một trong các giá trị:VMS: Thẻ cào MobiFoneVNP: Thẻ cào VinaPhone

VIETTEL: Thẻ cào Viettel

ref_code String(50) Mã duy nhất tương ứng với một khách hàng tại merchant
(ví dụ: tên tài khoản, mã tài khoản,…)
merchant_account String(255) Địa chỉ Email chính của tài khoản NgânLượng.vn
mà merchant dùng để nhận tiền nạp vào từ thẻ cào
client_fullname String(255) Tên đầy đủ của khách hàng tại merchant
client_email String(255) Email khách hàng tại merchant
client_mobile String(20) Điện thoại của khách hàng tại merchant

 

        d. Bản mô tả lỗi trả về

Mã lỗi Mô tả
00 Đã xử lý thành công (thẻ đã bị gạch, tiền đã được nạp vào tài khoản của merchant)
01 Lỗi, tuy nhiên lỗi chưa được định nghĩa/không xác định
02 Lỗi, Mã website/merchant không tồn tại hoặc website/merchant đang bị khóa
03 Lỗi, Địa chỉ IP truy cập API của NgânLượng.vn bị từ chối
04 Lỗi, Mã checksum không chính xác (lỗi này thường xảy ra khi mật khẩu giao tiếp giữa merchant và NgânLượng.vn không chính xác, hoặc cách sắp xếp các tham số trong biến params không đúng)
05 Lỗi, Mã thẻ cào không chính xác hoặc đã được sử dụng
06 Lỗi, Không kết nối tới hệ thống xác thực thẻ của Telco
07 Lỗi, Tài khoản NgânLượng.vn của merchant nhận tiền nạp không tồn tại
08 Lỗi, Tài khoản NgânLượng.vn của merchant nhận tiền nạp đang bị khóa hoặc bị phong tỏa
09 Lỗi, khách hàng tương ứng với tham số ref_code bị khóa (do nhập sai mã thẻ liên tiếp nhiều lần)
10 Lỗi, thẻ bị trừ, nhưng nạp được tiền vào tài khoản NgânLượng.vn của người bán

 

           e. Demo đơn giản

           - đăng nhập với tài khoản vừa đăng ký. Tài khoản phải được chứng thực.

sdfasf

 

           - chọn phương thức tích hợp thanh toán

gdsgfsa

– chọn kiểu nút và lấy mã nhúng

Untitled

         – copy paste mã nhúng vào website

<a target=”_blank” href=”https://www.nganluong.vn/?portal=nganluong&page=deposit&cmd=process&mtype=mobile_card&method=viettel?

receiver=(Email chính tài khoản nhận tiền)

&product_name=(Mã đơn hàng)

&price=(tổng giá trị đơn hàng)

&return_url=(URL thanh toán thành công)

&comments=(Ghi chú về đơn hàng)” >

<img src=”https://www.nganluong.vn/data/images/buttons/17.gif”  border=”0″ />

</a>

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">