NAV
bash javascript

Giới thiệu Bảo Kim API

Bảo Kim Payment Platform là một nền tảng thanh toán mở, Bảo Kim cung cấp đầy đủ các API cho phép user tích hợp giữa ứng dụng (web/app) của mình với Bảo Kim nhằm thực hiện việc nhận thanh toán đơn hàng, kiểm tra tài khoản, đối soát giao dịch, thực hiện giao dịch tự động, ...

Ví dụ user có thể thực hiện các tác vụ sau với Bảo Kim API

Phương thức bảo mật

Bảo mật Bảo Kim API sử dụng các phương thức sau đây

//PHP JWT example
require_once('vendor/autoload.php');
use \Firebase\JWT\JWT;

class BaoKimAPI {

    /* Bao Kim API key */
    const API_KEY = "x***";
    const API_SECRET = "y***";
    const TOKEN_EXPIRE = 60; //token expire time in seconds
    const ENCODE_ALG = 'HS256';

    private static $_jwt = null;

    /**
     * Refresh JWT
     */
    public static function refreshToken(){

        $tokenId    = base64_encode(mcrypt_create_iv(32));
        $issuedAt   = time()-100000;
        $notBefore  = $issuedAt;
        $expire     = $notBefore + self::TOKEN_EXPIRE;

        /*
         * Payload data of the token
         */
        $data = [
                'iat'  => $issuedAt,         // Issued at: time when the token was generated
                'jti'  => $tokenId,          // Json Token Id: an unique identifier for the token
                'iss'  => self::API_KEY,     // Issuer
                'nbf'  => $notBefore,        // Not before
                'exp'  => $expire,           // Expire
                'form_params' => [                  // request body (dữ liệu post)
                    //'a' => 'value a',
                    //'b' => 'value b',
                ]
        ];

        /*
         * Encode the array to a JWT string.
         * Second parameter is the key to encode the token.
         *
         * The output string can be validated at http://jwt.io/
         */
        self::$_jwt = JWT::encode(
                $data,      //Data to be encoded in the JWT
                self::API_SECRET, // The signing key
                'HS256'     // Algorithm used to sign the token, see https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-3
        );

        return self::$_jwt;
    }

    /**
     * Get JWT
     */
    public static function getToken(){
        if(!self::$_jwt)
            self::refreshToken();

        try {
            JWT::decode(self::$_jwt, self::API_SECRET, array('HS256'));
        }catch(Exception $e){
            self::refreshToken();
        }

        return self::$_jwt;
    }
}

API endpoint

Bảo Kim API endpoint (đường dẫn đầy đủ gọi API) được xác định như sau:

Môi trường production (thật)

Môi trường sandbox (test)

Trong đó API_URI được mô tả trong phần tài liệu chi tiết của từng API

Môi trường Sandbox(test)

Bắt đầu ngay

Để bắt đầu sử dụng Bảo Kim API bạn chỉ cần thực hiện các bước hết sức đơn giản và nhanh chóng sau đây

Tích hợp thanh toán

Bảo Kim cung cấp quy trình và các API cho phép tích hợp thanh toán đơn hàng/sản phẩm từ các website/app thương mại điện tử/nội dung số... Nhằm phục vụ cho việc xử lý thanh toán khi khách hàng mua sắm trực tuyến một cách an toàn và tiện lợi.

Trước khi bắt đầu, hãy đảm bảo rằng bạn

Quy trình tích hợp cơ bản

Đây là quy trình tích hợp đơn giản và nhanh chóng nhất, tuy nhiên xin hãy tìm hiểu thêm về quy trình tích hợp Pro phía dưới với nhiều ưu điểm hơn để có lựa chọn phù hợp.

Ưu điểm:

Nhược điểm:

Quy trình tích hợp cơ bản

Quy trình tích hợp Pro (nâng cao)

Về mặt kỹ thuật, điểm khác biệt duy nhất của tích hợp Pro so với tích hợp cơ bản là Web/App merchant sử dụng API Bank Payment Method List để load danh sách phương thức thanh toán và hiển thị trên giao diện của mình cho user chọn, sau đó gửi các tham số này cùng với đơn hàng sang Bảo Kim qua API Send Order

Ưu điểm chính của tích hợp Pro:

Nhược điểm:

Click để xem trang demo

Quy trình tích hợp Pro

Thanh toán qua Internet Banking (comming soon)

Về cơ bản, thanh toán qua Internet Banking chỉ là 1 phương thức thanh toán thuộc các quy trình tích hợp trên (basic/pro), web/app merchant có thể đơn giản là không cần xử lý gì thêm.
Tuy nhiên, nếu bạn muốn đơn giản hơn cho khách hàng bằng cách hiển thị luôn thông tin tài khoản Internet Banking nhận tiền trên giao diện của mình thay vì phải redirect sang Bảo Kim, hãy xử lý theo quy trình rút ngắn dưới đây: Quy trình tích hợp thanh toán Internet Banking

Xác nhận kết quả thanh toán

Web/App merchant có 2 cách để xác nhận kết quả thanh toán của đơn hàng:

Trong cả 2 cách trên, đơn hàng được coi là thanh toán thành công khi:

Webhook Notification

Webhook notification là cơ chế thông báo cho Web/App merchant khi đơn hàng được thanh toán thành công thông qua HTTP POST request
Làm sao để nhận thông báo webhook notification?

Webhook notification sẽ gửi bao nhiêu lần?

Mô tả dữ liệu trên webhook notification

Method: POST

Header: Content-Type: application/json

Body (xem dữ liệu mẫu bên phải)

{
...."order": {
........"id": 45458,
........"user_id": "1000005",
........"mrc_order_id": "mrc_1543306400",  //Mã đơn hàng duy nhất do merchant tạo và gửi sang
........"txn_id": "100000000",  //Mã giao dịch thanh toán cho đơn hàng
........"ref_no": "TRF_10000000",
........"deposit_id": null,
........"merchant_id": null,
........"total_amount": "100000.00",
........"shipping_fee": "0.00",
........"tax_fee": "0.00",
........"mrc_fee": null,
........"description": "thanh toan don hang 1543306400",
........"url_success": "https:\/\/vnexpress.net\/",
........"url_cancel": null,
........"url_detail": null,
........"stat": "c", //Trạng thái thanh toán đơn hàng: "p" - đang xử lý / "c" - "hoàn thành"
........"payment_version": "4.0",
........"lang": "vi",
........"bpm_id": 0,
........"accept_qrpay": 0,
........"created_at": "2018-11-27 08:13:22",
........"updated_at": "2018-11-27 08:13:22"
....}
...."txn": {
........"id": 100000000,
........"user_id": 1000005,
........"account_id": 1001000079,
........"opening_balance": "1111968443.45",
........"amount": "10000.00",
........"balance": "1111978443.45",
........"opening_freeze_balance": "562387181.18",
........"freeze_amount": "0.00",
........"freeze_balance": "562387181.18",
........"ref_no": "TRF_10000000",
........"bank_ref_no": "vcb_1543390288",
........"type": null,
........"stat": 4,
........"description": "ut nap tien 1@bk.vn",
........"fee_amount": "0.00",
........"is_processed": 1,
........"src_des": null,
........"created_at": "2018-11-28 07:31:28",
........"updated_at": "2018-11-28 07:31:28"
....}
...."sign": "hmac_hash_xxxyyyzzz" //hash sử dụng hmac với thuật toán sha256 ký lên dữ liệu gửi đi nhằm đảm bảo tính toàn vẹn của dữ liệu
}

Các bước kiểm tra và xử lý khi nhận được webhook notification

$signData = json_encode(['order' => $order, 'txn' => $txn]);
$yourSign = hash_hmac('sha256', $signData, $apiKey->secret);
if ($yourSign != $sign) { exit("Dữ liệu webhook notification không toàn vẹn") }

Ngoại lệ đối với thanh toán từ thẻ tín dụng quốc tế:

Bảng mã lỗi

Hằng số/Const Mã /Code Mô tả/Description
ERR_NONE 0 Thành công (không có lỗi)
ERR_SYSTEM 1 Lỗi hệ thống
ERR_VALIDATION 2 Lỗi validate dữ liệu/tham số
ERR_OBJECT_NOT_FOUND 3 Lỗi không tìm thấy đối tượng (tài khoản/giao dịch/đơn hàng...)
ERR_ACCOUNT_LOCKED 4 Lỗi tài khoản bị khóa
ERR_UNAUTHORIZED 5 Lỗi không được phép thực hiện giao dịch (đăng nhập, xác thực 2FA lỗi)
ERR_INVALID_AMOUNT 6 Lỗi số tiền giao dịch không chính xác
ERR_DUPLICATED_ACTION 7 Lỗi giao dịch lặp (vd thanh toán 2 lần...)
ERR_INTERNAL_SERVICE 8 Lỗi hệ thống nội bộ
ERR_INSUFFICIENT_BALANCE 9 Lỗi số dư tài khoản không đủ thực hiện giao dịch
ERR_EXCEED_MAX_DAILY_AMOUNT 10 Lỗi số tiền giao dịch vượt quá hạn mức ngày
ERR_VERIFY_FAILED 11 Lỗi xác minh giao dịch
ERR_CONFIG_FEE_NOT_FOUND 12 Lỗi cấu hình tính phí
ERR_ACCOUNT_NOT_FOUND 13 Lỗi không tìm thấy tài khoản giao dịch
ERR_AMOUNT_TOO_SMALL 14 Lỗi số tiền quá nhỏ so với hạn mức
ERR_AMOUNT_TOO_BIG 15 Lỗi số tiền quá lớn so với hạn mức
ERR_USER_NOT_VERIFIED 16 Lỗi user chưa xác thực tài khoản
ERR_TRANSACTION_REFUNDED 18 Lỗi hoàn tiền lặp (khi thực hiện hoàn tiền)
ERR_TRANSACTION_NOT_COMPLETE 17 Lỗi trạng thái giao dịch chưa hoàn thành
ERR_BANK_ACCOUNT_EXISTED 19 Tài khoản Ngân hàng đã tồn tại trên hệ thống
ERR_BANK_CARD_NOT_FOUND 20 Không tìm thấy thẻ Ngân hàng
ERR_TRANSFER_ON_BANK 21 Lỗi chuyển tiền sang Thẻ ngân hàng
ERR_BANK_ACCOUNT_NAME_NOT_MATCH 22 Tên Tài khoản ngân hàng không trùng với tên Ví
ERR_BANK_ACCOUNT_NOT_FOUND 23 Không tìm thấy Tài khoản Ngân hàng
ERR_OTHER 24 Lỗi khác (không xác định)
ERR_REFUND_NOT_ALLOWED 25 Loại giao dịch không được hoàn tiền
ERR_BANK_CARD_EXISTED 27 Thẻ Ngân hàng đã tồn tại trên hệ thống

Get Postman Collection

Account API

Các API về tài khoản

Account detail

[API Get chi tiết thông tin tài khoản ví Bảo Kim của user]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/account/detail" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/account/detail",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/account/detail", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "id": 1001000079,
        "user_id": 1000005,
        "type": 1,
        "balance": "1110852443.45",
        "freeze_balance": "562387181.18",
        "stat": 0,
        "last_act_id": 27496,
        "created_at": "2010-04-22 07:18:50",
        "updated_at": "2018-07-02 00:28:59"
    }
}

HTTP Request

GET api/v4/account/detail

Bank Card API

APIs for managing Bank Cards

Bank Card List

[List danh sách Thẻ Ngân hàng của user]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/bank-card/list" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/bank-card/list",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/bank-card/list", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": [
        {
            "id": "ID thẻ, sử dụng khi thực hiện giao dịch nạp, rút về thẻ",
            "user_id": 1000005,
            "bank_id": 131,
            "deposit_bpm_id": 154,
            "withdraw_bpm_id": 155,
            "card_type": null,
            "owner_name": "Firzen Le",
            "short_name": null,
            "code": "số thẻ",
            "cvv_code": null,
            "token": null,
            "expiration_date": "12-12",
            "verification": 1,
            "alias": "ABBank - Ngân hàng An Bình - 2661",
            "created_at": "2017-08-30 09:15:55",
            "updated_at": "2017-08-30 09:16:24"
        }
    ]
}

HTTP Request

GET api/v4/bank-card/list

Bank Payment API

Bank Payment Method List

Danh sách phương thức thanh toán từ các ngân hàng Bảo Kim hỗ trợ, Web/App merchant có thể sử dụng API này để hiển thị phương thức thanh toán trên ứng dụng của mình Danh sách này được phân loại theo trường "type" như sau:

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/bpm/list" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/bpm/list",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/bpm/list", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 76,
    "data": [
        {
            "id": 9,
            "name": "Thẻ ATM DongA Bank",
            "bank_id": 82,
            "type": 1,
            "complete_time": "Ngay lập tức",
            "bank_name": "DongA Bank - Ngân hàng Đông Á",
            "bank_short_name": "DongA Bank",
            "bank_logo": "https:\/\/cdn.baokim.vn\/public\/uploads\/banks\/82.png"
        },
        {
            "id": 40,
            "name": "Thẻ ATM Vietinbank",
            "bank_id": 81,
            "type": 1,
            "complete_time": "ngay lập tức",
            "bank_name": "VietinBank - Ngân hàng Công Thương",
            "bank_short_name": "Vietin Bank",
            "bank_logo": "https:\/\/cdn.baokim.vn\/public\/uploads\/banks\/81.png"
        }
    ]
}

HTTP Request

GET api/v4/bpm/list

Order API

Order API cung cấp các API phục vụ việc tích hợp thanh toán đơn hàng/sản phẩm từ các website/app bán hàng/nội dung số...

Bạn cần hiểu rõ các quy trình tích hợp thanh toán Bảo Kim cung cấp trước khi thực hiện tích hợp thanh toán

Send Order

[API Gửi thông tin đơn hàng từ ứng dụng của user sang Bảo Kim để thực hiện thanh toán.]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/order/send"     -d "mrc_order_id"="lyjH0S6qE4Sp2ujS" \
    -d "total_amount"="5" \
    -d "description"="1zioB4lEL4YPCyCs" \
    -d "url_success"="hiGQkUaUCiSWyOTO" \
    -d "url_detail"="vMax5xQWigKKwB8z" \
    -d "lang"="knCmYGcHaKGL839C" \
    -d "bpm_id"="6" \
    -d "accept_bank"="IehAwTsaEPoOAn7V" \
    -d "accept_cc"="pHo44UddkcS4HRtq" \
    -d "accept_qrpay(0,1)"="18" \
    -d "webhooks"="CUrdMZh2LTu21egp" \
    -d "customer_email"="RGMenLKQ5GNGeSON" \
    -d "customer_phone"="7vyyYGCPRcaJSZQS" \
    -d "customer_name"="nYhoy2Ks2VIYKJM0" \
    -d "customer_address"="WcJFQGBSDLSCoS4c" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/send",
    "method": "POST",
    "data": {
        "mrc_order_id": "lyjH0S6qE4Sp2ujS",
        "total_amount": 5,
        "description": "1zioB4lEL4YPCyCs",
        "url_success": "hiGQkUaUCiSWyOTO",
        "url_detail": "vMax5xQWigKKwB8z",
        "lang": "knCmYGcHaKGL839C",
        "bpm_id": 6,
        "accept_bank": "IehAwTsaEPoOAn7V",
        "accept_cc": "pHo44UddkcS4HRtq",
        "accept_qrpay(0,1)": 18,
        "webhooks": "CUrdMZh2LTu21egp",
        "customer_email": "RGMenLKQ5GNGeSON",
        "customer_phone": "7vyyYGCPRcaJSZQS",
        "customer_name": "nYhoy2Ks2VIYKJM0",
        "customer_address": "WcJFQGBSDLSCoS4c"
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['mrc_order_id'] = "lyjH0S6qE4Sp2ujS";
$payload['total_amount'] = "5";
$payload['description'] = "1zioB4lEL4YPCyCs";
$payload['url_success'] = "hiGQkUaUCiSWyOTO";
$payload['url_detail'] = "vMax5xQWigKKwB8z";
$payload['lang'] = "knCmYGcHaKGL839C";
$payload['bpm_id'] = "6";
$payload['accept_bank'] = "IehAwTsaEPoOAn7V";
$payload['accept_cc'] = "pHo44UddkcS4HRtq";
$payload['accept_qrpay(0,1)'] = "18";
$payload['webhooks'] = "CUrdMZh2LTu21egp";
$payload['customer_email'] = "RGMenLKQ5GNGeSON";
$payload['customer_phone'] = "7vyyYGCPRcaJSZQS";
$payload['customer_name'] = "nYhoy2Ks2VIYKJM0";
$payload['customer_address'] = "WcJFQGBSDLSCoS4c";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/order/send", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "order_id": 45475,
        "redirect_url": "\/payment\/?oid=45475&checksum=94e1fddb9dce33c7b9fb79b605845422adb7d6a3"
    }
}

HTTP Request

POST api/v4/order/send

Body Parameters

Parameter Type Status Description
mrc_order_id string required mã đơn hàng của merchant
total_amount integer required tổng số tiền đơn hàng
description string required Mô tả giao dịch
url_success string required Url redirect lại sau khi thanh toán thành công
url_detail string optional Url chi tiết đơn hàng (redirect lại khi khách hủy đơn)
lang string optional Ngôn ngữ
bpm_id integer optional ID phương thức thanh toán từ ngân hàng Từ API Bank Payment Method List
accept_bank int(0,1) optional Chấp nhận thanh toán bằng thẻ ATM ? (Chấp nhận: 1, Không chấp nhận: 0, default: 1)
accept_cc int(0,1) optional Chấp nhận thanh toán bằng thẻ Tín dụng ? (Chấp nhận: 1, Không chấp nhận: 0, default: 1)
accept_qrpay(0,1) integer optional Chấp nhận thanh toán bằng QR code ? (Chấp nhận: 1, Không chấp nhận: 0, default: 0)
webhooks string optional url dùng để gửi thông báo cho website bán hàng, chat, ... khi đơn hàng thanh toán thành công, cho phép notify đến nhiều url, cách nhau bởi dấu ,
customer_email string optional Email khách hàng
customer_phone string optional Số điện thoại khách hàng
customer_name string optional Họ và tên khách hàng
customer_address string optional Địa chỉ khách hàng

Order Detail

[API Get chi tiết thông tin đơn hàng, có thể dùng để kiểm tra trạng thái thanh toán đơn hàng.] Đơn hàng được coi là đã thanh toán thành công khi có:

Chú ý: Với giao dịch thanh toán từ thẻ tín dụng, đơn hàng có thể ở trạng thái chờ 'r' (Reviewing). Trường hợp này khách hàng đã thanh toán nhưng giao dịch phải chờ phía Ngân hàng duyệt. Bảo Kim sẽ không cộng số dư ví cho Merchant cho đến khi ngân hàng duyệt. Việc giao hàng ngay hay đợi duyệt sẽ cho phía Merchant tự quyết định.

Danh sách trạng thái đơn hàng:

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/order/detail" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/detail",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();
$options['query']['id'] = 'u52stYMC1qvLXxVg';
$options['query']['mrc_order_id'] = 'ygaRoBX5EDGSkstc';

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/order/detail", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "id": 45458,
        "user_id": "1000005",
        "mrc_order_id": "mrc_1543306400",
        "txn_id": null,
        "ref_no": null,
        "deposit_id": null,
        "merchant_id": null,
        "total_amount": "100000.00",
        "shipping_fee": "0.00",
        "tax_fee": "0.00",
        "mrc_fee": null,
        "description": "thanh toan don hang 1543306400",
        "url_success": "https:\/\/vnexpress.net\/",
        "url_cancel": null,
        "url_detail": null,
        "stat": "p",
        "payment_version": "4.0",
        "lang": "vi",
        "bpm_id": 0,
        "accept_qrpay": 0,
        "created_at": "2018-11-27 08:13:22",
        "updated_at": "2018-11-27 08:13:22"
    }
}

HTTP Request

GET api/v4/order/detail

Query Parameters

Parameter Status Description
id optional ID đơn hàng [semi-optional]
mrc_order_id optional Mã đơn hàng duy nhất được tạo bảo merchant [semi-optional]

List Order

[API Get danh sách đơn hàng của user, có thể sử dụng để đối soát đơn hàng giữa ứng dụng và Bảo Kim.]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/order/list" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/list",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();
$options['query']['mrc_order_id'] = '7rgTju0jPzS7yKGr';
$options['query']['txn_id'] = 'wDNTyrIJP5qmogbS';
$options['query']['stat'] = 'm88QyIakJLMBsFqG';
$options['query']['from_date'] = 'hhSLlR2u3aRNeAe8';
$options['query']['to_date'] = '0gPHzbgD8JoXQIKw';
$options['query']['per_page'] = 'SsWrfDQE68cq9EVP';
$options['query']['page'] = '2';

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/order/list", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "current_page": 2,
        "data": [
            {
                "id": 3,
                "user_id": "100000",
                "mrc_order_id": "71364",
                "txn_id": null,
                "ref_no": "1000033",
                "deposit_id": null,
                "merchant_id": 6,
                "total_amount": "4000.00",
                "shipping_fee": "0.00",
                "tax_fee": "0.00",
                "mrc_fee": null,
                "description": "Mua hàng tại Vatgia.com, mã đơn hàng dienthoaigiatot_20100420153128",
                "url_success": "http:\/\/vatgia.com\/baokim\/return_payment.php",
                "url_cancel": "",
                "url_detail": "http:\/\/vatgia.com\/profile\/?module=order_detail&record_id=71364",
                "stat": null,
                "payment_version": null,
                "lang": "vi",
                "bpm_id": 0,
                "accept_qrpay": 0,
                "created_at": "-0001-11-30 00:00:00",
                "updated_at": "-0001-11-30 00:00:00"
            }
        ]
    }
}

HTTP Request

GET api/v4/order/list

Query Parameters

Parameter Status Description
mrc_order_id optional mã đơn hàng
txn_id optional mã giao dịch
stat optional trạng thái đơn hàng
from_date optional đơn hàng từ ngày
to_date optional đơn hàng đến ngày
per_page optional tổng số dòng trên một trang
page optional page index cần lấy

Cancel Order

[API hủy đơn hàng, sử dụng trong trường hợp không muốn nhận thanh toán cho đơn hàng nữa]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/order/cancel"     -d "id"="6" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/cancel",
    "method": "POST",
    "data": {
        "id": 6
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['id'] = "6";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/order/cancel", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "id": 45458,
        "user_id": "1000005",
        "mrc_order_id": "mrc_1543306400",
        "txn_id": null,
        "ref_no": null,
        "deposit_id": null,
        "merchant_id": null,
        "total_amount": "100000.00",
        "shipping_fee": "0.00",
        "tax_fee": "0.00",
        "mrc_fee": null,
        "description": "thanh toan don hang 1543306400",
        "url_success": "https:\/\/vnexpress.net\/",
        "url_cancel": null,
        "url_detail": null,
        "stat": "d",
        "payment_version": "4.0",
        "lang": "vi",
        "bpm_id": 0,
        "accept_qrpay": 0,
        "created_at": "2018-11-27 08:13:22",
        "updated_at": "2018-11-27 08:13:22"
    }
}

HTTP Request

POST api/v4/order/cancel

Body Parameters

Parameter Type Status Description
id integer required mã đơn hàng

Refund API

Api cho quản trị hoàn tiền các giao dịch đã hoàn thành

Create Refund

[Tạo giao dịch hoàn tiền]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/refund/create"     -d "txn_id"="hkOBYFb3PShq5XzS" \
    -d "description"="zAlOKbZH18dE9FEf" \
    -d "chanel"="DWNI3GSHS8nyal1M" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/refund/create",
    "method": "POST",
    "data": {
        "txn_id": "hkOBYFb3PShq5XzS",
        "description": "zAlOKbZH18dE9FEf",
        "chanel": "DWNI3GSHS8nyal1M"
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['txn_id'] = "hkOBYFb3PShq5XzS";
$payload['description'] = "zAlOKbZH18dE9FEf";
$payload['chanel'] = "DWNI3GSHS8nyal1M";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/refund/create", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 2,
    "data": [
        {
            "user_id": 1000005,
            "account_id": 1001000079,
            "amount": -99000,
            "fee_amount": -1000,
            "description": "Hoàn tiền giao dịch :32365",
            "ref_no": "REF_32365",
            "stat": 4,
            "type": 7,
            "src_des": "hoàn tiền đến giao dịch 32365",
            "updated_at": "2019-03-15 04:35:48",
            "created_at": "2019-03-15 04:35:48",
            "id": 32375
        },
        {
            "user_id": 1015669,
            "account_id": 1001005056,
            "amount": 100000,
            "fee_amount": 0,
            "description": "Hoàn tiền giao dịch :32365",
            "ref_no": "REF_32365",
            "stat": 4,
            "type": 7,
            "src_des": "hoàn tiền đến giao dịch 32365",
            "updated_at": "2019-03-15 04:35:48",
            "created_at": "2019-03-15 04:35:48",
            "id": 32376
        }
    ]
}

HTTP Request

POST api/v4/refund/create

Body Parameters

Parameter Type Status Description
txn_id numeric required mã giao dịch
description string required nội dung hoàn (max : 255 ký tự)
chanel string optional kênh hoàn tiền chọn hoàn về bank hay Bảo kim (BANK, BAOKIM)

Transaction API

Các API về giao dịch

Transaction list

[API truy xuất thông tin lịch sử giao dịch của user, có thể sử dụng trong đối soát giao dịch]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/txn/list" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/txn/list",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();
$options['query']['txn_id'] = '9KUAyQfgQiF93Hd7';
$options['query']['type'] = 'iBaSVKlVBCcOdaoG';
$options['query']['ref_no'] = 'pZ72QZbJ0SeboR7U';
$options['query']['stat'] = 'IliZcCrBCaHiQpye';
$options['query']['from_date'] = 'zjk3DDIBF2Jja2kU';
$options['query']['to_date'] = 'gx7yhUD3qQMj4j4w';
$options['query']['page'] = '19';
$options['query']['per_page'] = 'Sh96JzXNxFfE0ReQ';

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/txn/list", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 1537,
    "data": {
        "current_page": 4,
        "data": [
            {
                "id": 10313,
                "user_id": 1000005,
                "account_id": 1001000079,
                "opening_balance": "5308590.00",
                "amount": "-10300.00",
                "balance": "5298290.00",
                "opening_freeze_balance": "525306122.96",
                "freeze_amount": "0.00",
                "freeze_balance": "525306122.96",
                "ref_no": "1026288",
                "bank_ref_no": null,
                "type": null,
                "stat": 4,
                "description": null,
                "fee_amount": "0.00",
                "is_processed": 1,
                "src_des": null,
                "created_at": "2016-02-26 10:09:58",
                "updated_at": "-0001-11-30 00:00:00"
            }
        ]
    }
}

HTTP Request

GET api/v4/txn/list

Query Parameters

Parameter Status Description
txn_id optional mã giao dịch
type optional loại giao dịch 1:nạp, 3:rút, 5:chuyển, 7:hoàn
ref_no optional Mã tham chiếu
stat optional trạng thái giao dịch
from_date optional giao dịch từ ngày
to_date optional giao dịch đến ngày
page optional page index cần lấy
per_page optional Số bản ghi trên 1 trang

Transaction detail

[API truy xuất thông tin chi tiết 1 giao dịch]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/txn/detail" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/txn/detail",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();
$options['query']['txn_id'] = '5oBgJBgpDKizHWTo';

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/txn/detail", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "id": 27585,
        "user_id": 1000005,
        "account_id": 1001000079,
        "opening_balance": "1111968443.45",
        "amount": "10000.00",
        "balance": "1111978443.45",
        "opening_freeze_balance": "562387181.18",
        "freeze_amount": "0.00",
        "freeze_balance": "562387181.18",
        "ref_no": "1040791",
        "bank_ref_no": "vcb_1543390288",
        "type": null,
        "stat": 4,
        "description": "ut nap tien 1@bk.vn",
        "fee_amount": "0.00",
        "is_processed": 1,
        "src_des": null,
        "created_at": "2018-11-28 07:31:28",
        "updated_at": "2018-11-28 07:31:28"
    }
}

HTTP Request

GET api/v4/txn/detail

Query Parameters

Parameter Status Description
txn_id required mã giao dịch

Transfer API

API thực hiện giao dịch chuyển tiền cho user khác

Create transfer

[API Chuyển tiền từ ví Bảo Kim sang cho user khác]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/transfer/create"     -d "to_user"="QA86jYJj1qxjzAK4" \
    -d "amount"="DWGXOo3AmevgAcuO" \
    -d "description"="X9PJiwoDPfrS2YA0" \
    -d "verification_code"="mk3OCZgQ0NGZwiwD" \
    -d "fee_payer"="2zBv298s5Q3s9CMf" \
    -d "txn_mode"="HVEZLsw1MZVSuIHO" \
    -d "order_id"="3" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/transfer/create",
    "method": "POST",
    "data": {
        "to_user": "QA86jYJj1qxjzAK4",
        "amount": "DWGXOo3AmevgAcuO",
        "description": "X9PJiwoDPfrS2YA0",
        "verification_code": "mk3OCZgQ0NGZwiwD",
        "fee_payer": "2zBv298s5Q3s9CMf",
        "txn_mode": "HVEZLsw1MZVSuIHO",
        "order_id": 3
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['to_user'] = "QA86jYJj1qxjzAK4";
$payload['amount'] = "DWGXOo3AmevgAcuO";
$payload['description'] = "X9PJiwoDPfrS2YA0";
$payload['verification_code'] = "mk3OCZgQ0NGZwiwD";
$payload['fee_payer'] = "2zBv298s5Q3s9CMf";
$payload['txn_mode'] = "HVEZLsw1MZVSuIHO";
$payload['order_id'] = "3";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/transfer/create", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "transfer": {
            "from_account_id": 1001000079,
            "to_account_id": 1001005056,
            "amount": "20000",
            "description": "no",
            "fee_from": 0,
            "fee_to": 0,
            "stat": 1,
            "updated_at": "2018-12-14 04:00:36",
            "created_at": "2018-12-14 04:00:36",
            "id": 73
        },
        "txn": {
            "user_id": 1000005,
            "account_id": 1001000079,
            "amount": -20000,
            "fee_amount": 0,
            "fee_display": 0,
            "description": "no",
            "ref_no": 73,
            "stat": 4,
            "updated_at": "2018-12-14 04:00:36",
            "created_at": "2018-12-14 04:00:36",
            "id": 27716
        }
    }
}

HTTP Request

POST api/v4/transfer/create

Body Parameters

Parameter Type Status Description
to_user string required email/phone user thụ hưởng
amount decimal required Số tiền chuyển
description string required Nội dung giao dịch
verification_code string optional Mã xác thực 2FA (không áp dụng cho user sử dụng API Key)
fee_payer int[1,2] optional optional User trả phí, 1: user chuyển, 2: user nhận, default: 2
txn_mode int[1,2] optional optional chế độ giao dịch, 1: trực tiếp, 2: an toàn, default: 1
order_id integer optional optional Mã đơn hàng nếu là chuyển tiền thanh toán cho đơn hàng

VAT API

Các API về dịch vụ gia tăng của Bảo Kim (topup/mã thẻ/thẻ game/...)

List

[API trả về danh sách các dịch vụ giá trị gia tăng Bảo kim hỗ trợ. Merchant sử dụng tham số id trong items trả về trong API này để dùng trong API mua dịch vụ]

Example request:

curl -X GET -G "https://api.baokim.vn/payment/api/v4/vat/list" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/vat/list",
    "method": "GET",
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$response = $client->request("GET", "https://api.baokim.vn/payment/api/v4/vat/list", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 3,
    "data": [
        {
            "info": {
                "id": 1,
                "code": "CARD_MOBILE",
                "description": "Thẻ điện thoại",
                "account_recieve": 1015669,
                "stat": 1,
                "created_at": "2019-02-26 03:17:04",
                "updated_at": "-0001-11-30 00:00:00"
            },
            "items": [
                {
                    "id": 1,
                    "service_id": 1,
                    "param": "VIETTEL",
                    "name": "VIETTEL",
                    "discount": "0.00",
                    "partner": "ecopay",
                    "list_amount": "10,20,50,100,200,500",
                    "stat": 1,
                    "created_at": "2019-02-26 03:11:31",
                    "updated_at": "-0001-11-30 00:00:00"
                },
                {
                    "id": 2,
                    "service_id": 1,
                    "param": "VINAPHONE",
                    "name": "VINAPHONE",
                    "discount": "0.00",
                    "partner": "ecopay",
                    "list_amount": "10,20,50,100,200,500",
                    "stat": 1,
                    "created_at": "2019-02-26 03:10:46",
                    "updated_at": "-0001-11-30 00:00:00"
                }
            ]
        },
        {
            "info": {
                "id": 2,
                "code": "TOPUP_MOBILE",
                "description": "Nạp tiền điện thoại",
                "account_recieve": 1015669,
                "stat": 1,
                "created_at": "2019-02-26 03:17:06",
                "updated_at": "-0001-11-30 00:00:00"
            },
            "items": [
                {
                    "id": 5,
                    "service_id": 2,
                    "param": "VIETTEL",
                    "name": "VIETTEL",
                    "discount": "0.00",
                    "partner": "ecopay",
                    "list_amount": "10,20,50,100,200,500",
                    "stat": 1,
                    "created_at": "2019-02-26 03:10:48",
                    "updated_at": "-0001-11-30 00:00:00"
                },
                {
                    "id": 6,
                    "service_id": 2,
                    "param": "VINAPHONE",
                    "name": "VINAPHONE",
                    "discount": "0.00",
                    "partner": "ecopay",
                    "list_amount": "10,20,50,100,200,500",
                    "stat": 1,
                    "created_at": "2019-02-26 03:10:49",
                    "updated_at": "-0001-11-30 00:00:00"
                }
            ]
        }
    ]
}

HTTP Request

GET api/v4/vat/list

Purchase

[API cho merchant mua dịch vụ giá trị gia tăng của Bảo kim]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/vat/purchase"     -d "mrc_order_id"="g8HzWas1hi6XLDj4" \
    -d "service_item_id"="12" \
    -d "amount"="7" \
    -d "phone"="hQ6cl6tHVREI4qDE" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/vat/purchase",
    "method": "POST",
    "data": {
        "mrc_order_id": "g8HzWas1hi6XLDj4",
        "service_item_id": 12,
        "amount": 7,
        "phone": "hQ6cl6tHVREI4qDE"
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['mrc_order_id'] = "g8HzWas1hi6XLDj4";
$payload['service_item_id'] = "12";
$payload['amount'] = "7";
$payload['phone'] = "hQ6cl6tHVREI4qDE";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/vat/purchase", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "success": 0,
        "mrc_order_id": "101566938",
        "service_item_id": "2",
        "service": "CARD_MOBILE",
        "param": "VINAPHONE",
        "amount": 10000,
        "pin": "",
        "seri": "",
        "transaction_id": "36719",
        "created_at": "2019-05-13 01:01:41"
    }
}

HTTP Request

POST api/v4/vat/purchase

Body Parameters

Parameter Type Status Description
mrc_order_id string required Mã đơn hàng (Tạo trên hệ thống của Merchant, là duy nhất)
service_item_id integer optional Mã dịch vụ (lấy trong API Service list)
amount integer required Mệnh giá thẻ cào/giá trị nạp (lấy trong API Service list)
phone string optional Số điện thoại nhập Topup (required nếu mua Topup)

Withdraw API

API thực hiện giao dịch rút tiền từ ví => ngân hàng

Create Withdrawal

[API thực hiện rút tiền từ ví Bảo Kim về Thẻ/Tài khoản Ngân hàng]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/withdraw/create"     -d "card_id"="9" \
    -d "bank_account_id"="10" \
    -d "amount"="ZlAw0rsKN3GNjSqQ" \
    -d "descripton"="bjkMn36KfHxTEYaE" \
    -d "verification_code"="3077ZjZPz9Q0wCCP" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/withdraw/create",
    "method": "POST",
    "data": {
        "card_id": 9,
        "bank_account_id": 10,
        "amount": "ZlAw0rsKN3GNjSqQ",
        "descripton": "bjkMn36KfHxTEYaE",
        "verification_code": "3077ZjZPz9Q0wCCP"
    },
    "headers": {
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
//pre-requisites: install Guzzle package https://github.com/guzzle/guzzle
$client = new GuzzleHttp\Client(['timeout' => 20.0]);
$options['query']['jwt'] = BaoKimAPI::getToken();

$payload['card_id'] = "9";
$payload['bank_account_id'] = "10";
$payload['amount'] = "ZlAw0rsKN3GNjSqQ";
$payload['descripton'] = "bjkMn36KfHxTEYaE";
$payload['verification_code'] = "3077ZjZPz9Q0wCCP";
$options['form_params'] = $payload;

$response = $client->request("POST", "https://api.baokim.vn/payment/api/v4/withdraw/create", $options);
echo "Response status code: " . $response->getStatusCode();
echo "Response data: ". $response->getBody()->getContent();

Example response:

{
    "code": 0,
    "message": [],
    "count": 0,
    "data": {
        "withdrawal": {
            "user_id": 1000005,
            "account_id": 1001000079,
            "card_id": 475,
            "description": "rut tien ve the vcb",
            "stat": 6,
            "amount": "10000",
            "fee_amount": 50000,
            "net_amount": -40000,
            "updated_at": "2018-12-18 05:31:15",
            "created_at": "2018-12-18 05:31:15",
            "id": 454
        },
        "txn": {
            "user_id": 1000005,
            "account_id": 1001000079,
            "amount": -60000,
            "fee_amount": 50000,
            "fee_display": 50000,
            "description": "rut tien ve the vcb",
            "ref_no": 454,
            "stat": 4,
            "updated_at": "2018-12-18 05:31:15",
            "created_at": "2018-12-18 05:31:15",
            "id": 27815
        }
    }
}

HTTP Request

POST api/v4/withdraw/create

Body Parameters

Parameter Type Status Description
card_id integer optional required_without:bank_account_id ID Tài khoản Nhận tiền
bank_account_id integer optional required_without:card_id ID Thẻ Nhận tiền
amount decimal required Số tiền rút
descripton string required Nội dung giao dịch
verification_code string optional Mã xác thực 2FA, không áp dụng đối với giao dịch xác thực qua user API Key
bash javascript