Tài liệu API

1.GỬI THẺ

Để kết nối API dịch vụ đổi thẻ cào từ website của bạn đến KEY24H, bạn cần có 2 thông tin là PartnerID PartnerKEY do KEY24H cung cấp.

Để lấy thông tin PartnerID PartnerKEY bạn vui lòng gửi email đến: support@key24h.com với nội dung:
- Tên tài khoản KEY24H: Tên đăng nhập, Email hoặc Số điện thoại
- Tên website tích hợp: ví dụ https://key24h.com
- Địa chỉ IP của hosting/vps của website: ví dụ 45.239.23.53

Bạn có thể xem thông tin PartnerID PartnerKEY tại link: https://key24h.com/tich-hop.html sau khi thông tin tích hợp bạn gửi cho chúng tôi hợp lệ.

Sau khi bạn có 2 thông tin này, bạn mở file config.php và điền giá trị vào:

$config['PartnerID']        = '734563454358568';
$config['PartnerKey']        = '34v4e6hw5ewfwc5yvreg5gvrg5';

Thông tin POST thẻ lên gồm:

$amount         = $res->amount; // Mệnh giá thẻ mà bạn gửi sang
$type           = $res->type; // Loại thẻ mà bạn gửi sang
$serial         = $res->serial; // Serial mà bạn gửi sang
$code           = $res->code; // Mã thẻ mà bạn gửi sang
$request_id     = $res->request_id; // request_id mà bạn gửi sang
$transid        = $res->transid; // Mã giao dịch bên key24h.com

Loại thẻ có định dạng như sau:

Viettel: có key là viettel
Mobifone: có key là mobi
Vinaphone: có key là vina
Garena: có key là garena
Gate
: có key là gate

Sau khi post thành công, hệ thống sẽ trả về cho bạn một đối tượng gồm:

transid      = mã giao dịch bên key24h.com
request_id   = mã yêu cầu mà bên bạn lúc gửi thẻ sang
status       = 0 (gửi thẻ lên thành công) // Là gửi thẻ lên key24h thành công chứ không phải xử lý thẻ thành công.
hoặc
status       = 30 (mệnh giá thẻ này không nhận, mã thẻ hoặc serial không đúng định dạng…) // Là thẻ không được gửi lên key24h thành công
message      = tin nhắn trả về từ hệ thống


Chú ý: Khi gửi thẻ xong hệ thống trả về status = 0 hoặc status = 30:
- Status = 0 là thẻ đã được gửi thành công lên key24h xử lý
- Status = 30 là thẻ chưa được gửi sang key24h để xử lý (do Không nhận mệnh giá thẻ gửi, mã thẻ hoặc serial không đúng định dạng…)


BẢNG MÃ LỖI KHI GỬI THẺ SANG KEY24H MÀ TRẢ VỀ STATUS = 30:
1 - Thông tin kết nối PartnerID hoặc PartnerKey sai
2 - Thông tin kết nối đang bị khóa
3 - IP truy cập không hợp lệ
4 - Không tồn tại tài khoản này
5 - Tài khoản thành viên này đang bị khóa
6 - IP truy cập đang bị khóa
7 - Thiếu thông tin kết nối, kiểm tra lại các thông tin thẻ
8 - Loại thẻ không hợp lệ (loại thẻ phải đúng định dạng như bảng trên)
12 - Mã checksum không hợp lệ
13 - Request ID không hợp lệ, các request id gửi sang cần khác nhau
19 - Chức năng này đang tạm dừng hoạt động

Sau khi thẻ được gửi lên thành công lên key24h (status = 0), muốn biết thẻ đúng hoặc sai, lỗi sai là gì thì có 2 cách:
Cách 1: Quý khách chủ động call sang API check_status để check trạng thái thẻ
Cách 2: Quý khách tự thêm link callback ở menu TÍCH HỢP (xem ở phần 2. CALL BACK), khi key24h xử lý thẻ xong sẽ chủ động gửi dữ liệu sang cho bạn qua phương thức HTTP POST để bên bạn đón dữ liệu bên key24h post sang và lưu lại log để kiểm tra.

2.CALL BACK

Hệ thống cung cấp cho bạn một tiện ích trả kết quả đổi thẻ thông qua hình thức POST. Sau khi admin xử lý thẻ thành công, hệ thống sẽ post thông tin kết quả về website của bạn gồm các dữ liệu như sau:

'request_id', // Đây là mã yêu cầu mà bên bạn lúc gửi thẻ sang
'status', // Trạng thái thẻ ('pending', 'completed', 'canceled')
'amount', // Mệnh giá thẻ
'type', // Loại thẻ
'code', // Mã thẻ
'serial', // Serial
'message', // Tin nhắn trả về từ hệ thống
'notice', // Thông báo
'PartnerKey' // Do key24h cung cấp cho bạn, đây là thông tin kết nối

Bạn có thể vào link: https://key24h.com/tich-hop.html để cập nhật thông tin link CallBack bằng cách bấm vào nút SỬA tương ứng với website cần cập nhật.

Ví dụ: http://websitecuaban.com/callback.php
Trong file callback.php bạn phải sửa thông tin PartnerKey của bạn. Ví dụ: $PartnerKey = '54f46j75gw';