Hướng dẫn tích hợp

Hướng dẫn tích hợp thẻ cào sử dụng phương thức Post curl.

1. Mục đích

Cung cấp cho merchant 1 phương thức thanh toán bằng thẻ cào mà khách hàng có thể nhập mã thẻ ngay tại website của merchant.

2. Quy trình

Bước 1: Merchant đăng ký tài khoản ví điện tử NgânLượng.vn (hướng dẫn) và chứng thực tài khoản (hướng dẫn).

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

Bước 3: Khai báo chấp nhận thanh toán qua thẻ cào trên NgânLương.vn (xem phụ lục của tài liệu này).

Bước 4: Viết code kết nối website/merchant tới API chấp nhận thẻ cào của NgânLượng.vn

3. Phương thức kết nối

  1. Sử dụng theo phương thức POST
  2. Địa chỉ nhận tham số xử lý: http://exu.vn/mobile_card.api.post.v2.php

4. Mô tả hàm kết nối:

Tham số đầu vào

STT

Tên tham số

Kiểu dữ liệu

Bắt buộc

Giải thích

1

func

String(50)

 X

Tên hàm xử lý, hàm gạch thẻ là CardCharge

2

version

String(5)

 X

Phiên bản API = 2.0

3

merchant_id

String(50)

 X

Mã merchant đã khai báo tại website nganluong

4

merchant_accoint

String(255)

 X

Địa chỉ Email 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

5

merchant_password

String(50)

 

Mật khẩu kết nối API = MD5(merchant_api + “|” + Mật khẩu khi bạn khai báo website tại NgânLượng.vn)

6

pin_card

String(12 - 14)

 

Mã thẻ cào

7

card_serial

String(20)

 

Số seria của thẻ

8

type_card

String(10)

 

 Loại thẻ cào, nhận một trong các giá trị:

  1. VMS: Thẻ cào MobiFone
  2. VNP: Thẻ cào VinaPhone
  3. VIETTEL: Thẻ cào Viettel
  4. VCOIN: Thẻ cào VTC Coin
  5. GATE: thẻ cào FPT Gate

9

ref_code

String (50)

 

Mã duy nhất tương ứng với một mã khách hàng tại merchant (ví dụ: mã hóa đơn nạp tiền, tên truy cập tài khoản, mã tài khoản …) Trường hợp này dùng để đối soát giữa Nganluong.vn và merchant

10

client_fullname

String(255)

 

Tên đầy đủ của khách hàng tại merchant

11

client_email

String(255)

 

Email khách hàng tại merchant

12

client_mobile

String(20)

 

Điện thoại của khách hàng tại merchant

Tham số trả về (13 tham số ngăn cách bởi dấu |)

STT

Tên tham số

Kiểu dữ liệu

Bắt buộc

Giải thích

1

Dạng chuỗi ngăn cách nhau bởi ký tự “|”

String()

 

Là một chuỗi các ký tự ngăn cách nhau bởi dấu “|” tương ứng với các tham số sau:

 

error_code|merchant_id|merchant_account|pin_card|card_serial|type_card|ref_code|client_fullname|client_email|

client_ mobile|card_amount|transaction_amount|transaction_id

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.

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

pin_card

String(12 - 14)

 

Mã thẻ cào

card_serial

String(20)

 

Số serial của thẻ

type_card

String(10)

 

Loại thẻ cào, nhận một trong các giá trị: 

  1. VMS: Thẻ cào MobiFone
  2. VNP: Thẻ cào VinaPhone
  3. VIETTEL: Thẻ cào Viettel
  4. VCOIN: Thẻ cào VTC Coin
  5. GATE: Thẻ cào FPT Gate

ref_code

String (50)

 

Mã duy nhất tương ứng với một mã khách hàng tại merchant (ví dụ: mã hóa đơn nạp tiền, tên truy cập tài khoản, mã tài khoản …) Trường hợp này dùng để đối soát giữa Nganluong.vn và merchant

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_amount

Int

 

Mệnh giá thẻ

transaction_amount

Int

 

Số tiền merchant thực nhận tại Nganluong.vn (sau khi trừ phí)

transaction_id

String(20)

 

Mã giao dịch phát sinh tại Nganluong,vn


5. Bảng mã lỗi trả về:

Mã lỗi

Mô tả

00

Giao dịch thành công

99

Lỗi, tuy nhiên lỗi chưa được định nghĩa hoặc chưa xác định được nguyên nhân

01

Lỗi, địa chỉ IP truy cập API của NgânLượng.vn bị từ chối

02

Lỗi, tham số gửi từ merchant tới NgânLượng.vn chưa chính xác (thường sai tên tham số hoặc thiếu tham số)

03

Lỗi, Mã merchant không tồn tại hoặc merchant đang bị khóa kết nối tới NgânLượng.vn

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

Tài khoản nhận tiền nạp của merchant không tồn tại

06

Tài khoản nhận tiền nạp của merchant đang bị khóa hoặc bị phong tỏa, không thể thực giao dịch nạp tiền

07

Thẻ đã được sử dụng

08

Thẻ bị khóa

09

Thẻ hết hạn sử dụng

10

Thẻ chưa được kích hoạt hoặc không tồn tại

11

Mã thẻ sai định dạng

12

Sai số serial của thẻ

13

Thẻ chưa được kích hoạt hoặc không tồn tại

14

Thẻ không tồn tại

15

Thẻ không sử dụng dc

16

Số lần thử (nhập sai liên tiếp) của thẻ vượt quá giới hạn cho phép

17

Hệ thống Telco bị lỗi hoặc quá tải, thẻ chưa bị trừ

18

Hệ thống Telco bị lỗi hoặc quá tải, thẻ có thể bị trừ, cần phối hợp với NgânLượng.vn để tra soát

19

Kết nối từ NgânLượng.vn tới hệ thống Telco bị lỗi, thẻ chưa bị trừ (thường do lỗi kết nối giữa NgânLượng.vn với Telco, ví dụ sai tham số kết nối, mà không liên quan đến merchant)

20

Kết nối tới telco thành công, thẻ bị trừ nhưng chưa cộng tiền trên NgânLượng.vn

 

6. Ví dụ về cách gọi API.

 Code PHP

$merchant_id = '17260';

$password = 'cecae5cffadff3cecfc45ce370ef1803';

'func'                                    => 'CardCharge',

'version'                              => '2.0',

'merchant_id'                      => $merchant_id,

'merchant_account'            => 'diendc@peacesoft.net',

'merchant_password'          => MD5($merchant_id.'|'.$password),

'pin_card'                            => '12345678912345',

'card_serial'                      => 'XYZ123',

'type_card'                          => 'VNP',// VNP hoặc VMS hoặc VIETTEL

'ref_code'                            => time(),

              'client_fullname'              => 'Do Cong Dien',

              'client_email'                    => 'diendc@gmail.com',

              'client_mobile'                  => '0904515105',

 );

$post_field = '';

foreach ($params as $key => $value){

if ($post_field != '') $post_field .= '&';

$post_field .= $key."=".$value;

}

$api_url = "http://exu.vn/mobile_card.api.post.v2.php"; $ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_url);

curl_setopt($ch, CURLOPT_ENCODING , 'UTF-8'); curl_setopt($ch, CURLOPT_VERBOSE, 1);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_field); $result = curl_exec($ch);

$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch);

if ($result != '' && $status==200){

$arr_result = explode("|",$result); if (count($arr_result) == 13) {

$error_code                        = $arr_result[0];

$merchant_id                      = $arr_result[1];

$merchant_account             = $arr_result[2];

$pin_card                            = $arr_result[3];

$card_serial                        = $arr_result[4];

$type_card                         = $arr_result[5];

$ref_code                           = $arr_result[6];

$client_fullname                 = $arr_result[7];

$client_email                      = $arr_result[8];

$client_mobile                    = $arr_result[9];

$card_amount                    = $arr_result[10];

$transaction_amount          = $arr_result[11];

$transaction_id                 = $arr_result[12];

if ($error_code == '00'){

            echo(" Nạp thẻ thành công, mệnh giá thẻ = ".$card_amount);

}

else

echo("Có lỗi khi nạp thẻ, mã lỗi ".$error_code);

}

}

}

else echo("Có lỗi khi xử lý: ".$error);

Các tin liên quan