API tích hợp thẻ cào trên Napngay.com

 

Mô tả

Sơ đồ hệ thống

Tham số đầu vào

Tên tham sốKiểu dữ liệuBắt buộc?Mô tả
merchant_idStringYesMã MerchantID đăng ký trên Bảo Kim
api_usernameStringYesApi username được kỹ thuật Bảo Kim cấp
api_passwordStringYesApi Pwd được kỹ thuật Bảo Kim cấp
transaction_idStringYesMã TransactionId xác định giao dịch bên khách hàng
card_idStringYesLoại thẻ cào là 1 trong số loại (VINA, MOBI, VIETTEL, VTC, GATE)
pin_fieldStringYesMã Pin thẻ cào dưới lớp bạc
seri_fieldStringYesMã Seri thẻ
algo_modeStringNoThuật toán mã hóa tạo data_sign (md5 hoặc hmac)
data_signStringYesTrườ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

CodeLoại thẻpin_fieldseri_field
VINAVinaphone12,149-15
MOBIMobifone12,149-15
VIETTELViettel13-1511-15
GATEGate1010
VTCVtc vcoin1212


Dữ liệu trả về

Tên FieldKiểu dữ liệuMô tả
errorMessageStringNội dung lỗi
transaction_idStringMã giao dịch tương ứng với transaction_id gửi đi
amountIntMệ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 CodeTrạng tháiMô tả
200Thành côngGiao dịch nạp thành công
202Thẻ trễGiao dịch chưa xác định được trạng thái thành công hay không! TimeOut
450Lỗi dữ liệu gửi lênNội dung mô tả lỗi dữ liệu gửi lên chưa đúng
460Lỗi kết quả trả về từ nhà mạngNộ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.

1     Mục đích, phạm vi áp dụng tài liệu

Tài liệu đặc tả sơ đồ kiến trúc kỹ thuật của api service nhằm đáp ứng các yêu cầu đặt ra đối với việc thực hiện giao dịch thông qua API

Tài liệu này dùng cho:

-          Bộ phận phụ trách kỹ thuật Bảo Kim

-          Bộ phận quản lý sản phẩm Bảo Kim, giới thiệu các thông tin đến khách hàng (một số thông tin cần thiết trong trường hợp kết nối kỹ thuật)

-          Merchant tích hợp thanh toán Bảo Kim

2    Giải pháp xây dựng api service, sơ đồ luồng trang thanh toán

2.1  Sơ đồ hệ thống

2.2  Mô tả chi tiết dữ liệu giao tiếp

2.2.1    Topup To Merchant Request

Sau khi phía merchant xác thực được tài khoản thành công! Merchant gọi method DoTopupToMerchant đến Bảo Kim việc thực hiện nạp tiền cho tài khoản

·         Api_username: username đăng nhập web service của Bảo Kim, do Bảo Kim cấp cho website merchant

·         Api_password: mật khẩu đăng nhập web service của Bảo Kim, do Bảo Kim cấp cho website merchant

·         Merchant_id: mã merchant của website merchant khi đăng ký trên Bảo Kim

·         Transaction_id: Merchant sinh ra một mã giao dịch không trùng nhau request sang Bảo Kim để nạp tiền cho tài khoản. Baokim không nhận việc trùng mã giao dịch.

·         Card_id: ID thẻ cào (Mobile, Vina, Viettel…)

·         Pin_field: Mã pin thẻ cào

·         Seri_field: Mã Seri thẻ cào

·         Data_sign: Trường thông tin đảm bảo tính toàn vẹn dữ liệu (Được mô tả mục 2.2.3)

1.1.2  Topup To Merchant Response

Bảo Kim sẽ tiến hành xác minh thông tin thanh toán và trả kết quả về cho website merchant object

·         error_code: mã lỗi trả về

·         error_message: thông báo lỗi trả về

·         Transaction_id: Mã giao dịch trên hệ thống Bảo Kim

·         Info_card: Thông tin thẻ cào vừa nạp (Giá trị thẻ vừa cào)

·         Data_sign: Trường thông tin đảm bảo tính toàn vẹn dữ liệu (Trường thông tin này được xác nhận theo quy tắc trên)

Bảng mã lỗi trả về bước này:

         

0 - Suscess

1 – data request error

2 - wrong account api

3 - merchant site not found

4 - api account and merchant site account are not the same

5 - Transaction id existed

6 - merchant account found but not available to make transaction

7 - receiver account not found

8 - receiver account found but not available to make transaction

9 - Transaction amount is out of limited range

10 - escrow transaction mode is not allowed for guarantee account

11 - Transaction create error

12 - Info data changed - data_sign

13 - Payment amount is out of limited range

14 - Info card used BaoKim

15 - Error from gateway

 16 – Card ID invalid

 98 – IP invalid

99 - other error

1.1.3    Tạo Data_sign

***Trường dữ liệu Data sign được thực hiện theo quy tắc: Nối liền theo thứ tự Alphabet các tham số Request với Key tương ứng. Gắn liền trước string trên vào liền sau secure_pass rồi MD5.

Vd: Code mẫu PHP như sau:

ksort($data_request);        

$data_sign = md5($secure_code . implode("", $data_request));

=> $data_sign là trường thông tin sẽ đưa lên Bảo Kim

Tích hợp miễn phí ngay

Kỹ thuật

    4
  • Trần Bảo Trung
  • 01683671417

Kinh doanh

    1
  • Nguyễn Phương Dung
  • 0973132671
    2
  • Nguyễn Đăng Hiếu
  • 0979303590
    3
  • Trần Văn Toàn
  • 0977765343
    4
  • Lê Quỳnh Trang
  • 0982697992