NAV
bash javascript

Introducing Bao Kim API

Bao Kim Payment Platform is an open payment platform, Bao Kim provides a full range of APIs that allow users to integrate their application (web / app) with Bao Kim in order to receive payment orders and checks. account, transaction control, automatic trading, ...

For example, users can perform the following tasks with Bao Kim API

Security method

Security Bao Kim API uses the following methods

//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 (post data)
                    //'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

Bao Kim API endpoint (full path called API) is defined as follows:

Production environment(Live)

Sandbox environment (Test)

In which API_URI is described in the detailed documentation of each API

Sandbox environment (Test)

Start now

To start using Bao Kim API you just need to take the following simple and quick steps

Payment integration

Bao Kim provides processes and APIs that allow to integrate payment of orders / products from websites / e-commerce applications / digital content ... To serve payment processing when customers shop Safe and convenient online.

Before starting, make sure you

Basic integration process

This is the simplest and fastest integration process, but please learn more about the Pro integration process below with more advantages to make the right choice.

Advantages:

Defect:

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

Pro integration process (advanced)

Technically, the only difference between Pro integration and basic integration is the Web / App merchant that uses API Bank Payment Method List to load the list of payment methods and display on its interface to users. Select, then send these parameters along with the order to Bao Kim via the Send Order API

The main advantage of Pro integration:

Defect:

Click to view the demo page

Quy trình tích hợp Pro

Payment via Internet Banking (comming soon)

Basically, payment via Internet Banking is only one payment method of the above integrated processes (basic / pro), web / merchant app can simply do not need to handle any more.
However, if you want to be simpler for your customers by displaying your Internet Banking account information on your interface instead of having to redirect to Bao Kim, handle the shortening process below: Quy trình tích hợp thanh toán Internet Banking

Confirm payment results

After the customer successfully pays, Bao Kim will send a Webhook notification to the Web / App merchant, then redirect the client browser according to url_success on order with data. Web / App merchant has 2 ways to confirm payment results of orders:

In both ways, the order is considered a successful payment when:

Webhook Notification

Webhook notification is a notification mechanism for Web/Merchant App when the order is successfully paid via HTTP POST request
How to receive webhook notification?

How many times will the Webhook notification be sent?

Describe data on webhook notification

Method: POST

Header: Content-Type: application/json

Body (see sample data on the right)

{
...."order": {
........"id": 45458,
........"user_id": "1000005",
........"mrc_order_id": "mrc_1543306400",  //Merchant transaction code, it is unique
........"txn_id": "100000000",  //Transaction ID of orders
........"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", //Order status: "p" - processing / "c" - "complete"
........"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 use hmac algorithm with sha256 sign up the data send to merchant to confirm data integrity
}

Check and process steps when receiving webhook notification

  1. Check the received data integrity by checking the accuracy of the sign signature as follows (See the PHP sample code tab on the right, under webhook data description):
    • Use the secret value in the key / secret folder in your API Key
    • Use the hash_hmac algorithm with sha256, sign up the data you receive (except for the $sign field, of course) => $yourSign
    • Compare the signature you created ($yourSign) with the signature you received ($sign), if not the same => incomplete data
//Verify signature on webhook with PHP
//Decode webhook notification data received from Baokim
$jsonWebhookData = '{"order":{order data},"txn":{txn data},"sign":"baokim sign"}';
$webhookData = json_decode($jsonWebhookData, true);

//Get and remove sign field from data
$baokimSign = $webhookData['sign'];
unset($webhookData['sign']);

//Json encode data without sign field and using hash sha256 algorithm to create signature with secret key
$signData = json_encode($webhookData);
$secret = "9623ac03057e433f95d86cf4f3bef5cc";
$mySign = hash_hmac('sha256', $signData, $secret);

//Compare the signature you created with the signature received from Baokim, if result is equal verify is success
if($baokimSign == $mySign)
    echo "Signature is valid"
else
    echo "Signature is invalid"
  1. Check order payment status, payment transaction, payment amount, order fulfillment

    • Check the payment order status ($order->stat == 'c' // completed). With payment from credit card, there may be an exception of 'r' status (Reviewing, see description below)
    • Check the amount actually received on the payment transaction plus the fee ($txn->amount + $txn->fee_amount) has the sufficient amount of the order ($order->total_amount)
    • Check if the order information ($order) is correct for your order information on the web/app
    • If the above test steps are completely correct, you can be sure that the order has been paid and can complete the order.
  2. Returns the json string with err_code = 0, eg {"err_code": "0", "message": "some message"} to tell Kim that the merchant has received the notification and does not continue to resend it. The maximum length of data returned is 255 characters.

Exceptions to payments from international credit cards:

Data returned on url_success

If the web/app merchant applies payment processing results by 1 Webhook Notification, it is possible to ignore the processing of returned data on url_success and simply display the successful payment page for the customer. If not, verify the data returned on url_success as follows.

Data description on url_success

Name Description
mrc_order_id Merchant unique order code
txn_id Transaction code for payment orders
total_amount Amount of order payment
stat Order status
updated_at Time to record payment
checksum Data security signature (see details below)

Checksum is signed on the pass parameter on url_success using the hash sha256 algorithm, with the secret key as the key key in your API key. How to verify the checksum on url_success please see the steps and sample code on the right tab.

$urlSuccess = 'https://example.com/baokim/payment-success?your_param=your_value&txn_id=10000000&mrc_order_id=yourOrderId&total_amount=20000&updated_at=2019-07-20+09%3A36%3A18&checksum=17c5f89c132c814e5e4647f9eb8398fd3dc0621fe57d1662b72878ee513ad413';

//1. Load data from url_success,
// Remove checksum and all params of merchant (Don't response by Baokim)
$parts = parse_url($urlSuccess);
parse_str($parts['query'], $query);
$checksum = $query['checksum'];
unset($query['checksum']);
unset($query['your_param']);

//2. Sort all data by key
ksort($query);

//3. Create string to make checksum from data sorted
// follow by format key1=value1&key2=value2&...
$signData =  http_build_query($query);

//4. Create and compare checksum
$myChecksum = hash_hmac('sha256', http_build_query($query), $secretKey);
if($checksum == $myChecksum)
echo "Checksum is valid"
else
echo "Checksum is invalid"

Error code

Constant / Const Code Description
ERR_NONE 0 Successful (no errors)
ERR_SYSTEM 1 System error
ERR_VALIDATION 2 Error validate data/parameters
ERR_OBJECT_NOT_FOUND 3 Error finding object (account/transaction/order ...)
ERR_ACCOUNT_LOCKED 4 Account error is locked
ERR_UNAUTHORIZED 5 Error not allowed to execute transactions (login, 2FA authentication error)
ERR_INVALID_AMOUNT 6 Error of incorrect transaction amount
ERR_DUPLICATED_ACTION 7 Error with repeating transactions (eg payment of 2 times ...)
ERR_INTERNAL_SERVICE 8 Internal system error
ERR_INSUFFICIENT_BALANCE 9 Error of insufficient account balance to execute transactions
ERR_EXCEED_MAX_DAILY_AMOUNT 10 Transaction amount error exceeds the daily limit
ERR_VERIFY_FAILED 11 Transaction verification error
ERR_CONFIG_FEE_NOT_FOUND 12 Error of charging configuration
ERR_ACCOUNT_NOT_FOUND 13 Error not found trading account
ERR_AMOUNT_TOO_SMALL 14 Error amount is too small for the limit
ERR_AMOUNT_TOO_BIG 15 Error amount is too large for the limit
ERR_USER_NOT_VERIFIED 16 Error user has not verified account
ERR_TRANSACTION_REFUNDED 18 Repeat refund error (when making a refund)
ERR_TRANSACTION_NOT_COMPLETE 17 Incomplete transaction status error
ERR_BANK_ACCOUNT_EXISTED 19 Bank account already exists on the system
ERR_BANK_CARD_NOT_FOUND 20 No Bank card found
ERR_TRANSFER_ON_BANK 21 Error transferring money to bank card
ERR_BANK_ACCOUNT_NAME_NOT_MATCH 22 Bank account name does not match the name of Wallet
ERR_BANK_ACCOUNT_NOT_FOUND 23 No Bank Account found
ERR_OTHER 24 Other error (unknown)
ERR_REFUND_NOT_ALLOWED 25 Transaction type cannot be refunded
ERR_BANK_CARD_EXISTED 27 Bank card already exists on the system

Get Postman Collection

Account API

APIs for accounts

Account detail

[API Get detailed account information for BaoKim's 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 of Bank Card users list]

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": "Card ID, using to recharge from card or withdrawal to card",
            "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": "Card number",
            "cvv_code": null,
            "token": null,
            "expiration_date": "12-12",
            "verification": 1,
            "alias": "ABBank - An Binh Bank - 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

List of payment methods from BaoKim supporting banks, Web/Merchant App can use this API to display payment method on your application This list is classified by "type" field as follows:

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": "ATM Card DongA Bank",
            "bank_id": 82,
            "type": 1,
            "complete_time": "Now",
            "bank_name": "DongA Bank - Dong A Bank",
            "bank_short_name": "DongA Bank",
            "bank_logo": "https:\/\/cdn.baokim.vn\/public\/uploads\/banks\/82.png"
        },
        {
            "id": 40,
            "name": "ATM Card Vietinbank",
            "bank_id": 81,
            "type": 1,
            "complete_time": "Now",
            "bank_name": "VietinBank - Vietnam Joint Stock Commercial Bank For Industry and Trade",
            "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 provides APIs for integrating payment orders/products from sales websites/app/content ...

You need to understand the payment integration processes Bao Kim provides before making payment integration

Send Order

[API Send order information from user application to Bao Kim to make payment.]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/order/send"     -d "mrc_order_id"="ZSUgmaxQaUcBlwga" \
    -d "total_amount"="14" \
    -d "description"="eSDA8R4E8V1exqEc" \
    -d "url_success"="K9isFaGsjizZCaWS" \
    -d "url_detail"="TWKn2cCve0nc3GgS" \
    -d "lang"="D59ssxuwnRWFRqUv" \
    -d "bpm_id"="5" \
    -d "accept_bank"="Rwhost4T2PfiqbEZ" \
    -d "accept_cc"="FOsi36BnxEPK4BUn" \
    -d "accept_qrpay(0,1)"="14" \
    -d "webhooks"="Vq2A0BmrYvbeM1Zg" \
    -d "customer_email"="HyVlXLErSJQE2jZm" \
    -d "customer_phone"="tbT5ioXLXZBhQbkp" \
    -d "customer_name"="suoaRTlFnuTce15Z" \
    -d "customer_address"="rTUFtfHuqfvXfaiz" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/send",
    "method": "POST",
    "data": {
        "mrc_order_id": "ZSUgmaxQaUcBlwga",
        "total_amount": 14,
        "description": "eSDA8R4E8V1exqEc",
        "url_success": "K9isFaGsjizZCaWS",
        "url_detail": "TWKn2cCve0nc3GgS",
        "lang": "D59ssxuwnRWFRqUv",
        "bpm_id": 5,
        "accept_bank": "Rwhost4T2PfiqbEZ",
        "accept_cc": "FOsi36BnxEPK4BUn",
        "accept_qrpay(0,1)": 14,
        "webhooks": "Vq2A0BmrYvbeM1Zg",
        "customer_email": "HyVlXLErSJQE2jZm",
        "customer_phone": "tbT5ioXLXZBhQbkp",
        "customer_name": "suoaRTlFnuTce15Z",
        "customer_address": "rTUFtfHuqfvXfaiz"
    },
    "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'] = "ZSUgmaxQaUcBlwga";
$payload['total_amount'] = "14";
$payload['description'] = "eSDA8R4E8V1exqEc";
$payload['url_success'] = "K9isFaGsjizZCaWS";
$payload['url_detail'] = "TWKn2cCve0nc3GgS";
$payload['lang'] = "D59ssxuwnRWFRqUv";
$payload['bpm_id'] = "5";
$payload['accept_bank'] = "Rwhost4T2PfiqbEZ";
$payload['accept_cc'] = "FOsi36BnxEPK4BUn";
$payload['accept_qrpay(0,1)'] = "14";
$payload['webhooks'] = "Vq2A0BmrYvbeM1Zg";
$payload['customer_email'] = "HyVlXLErSJQE2jZm";
$payload['customer_phone'] = "tbT5ioXLXZBhQbkp";
$payload['customer_name'] = "suoaRTlFnuTce15Z";
$payload['customer_address'] = "rTUFtfHuqfvXfaiz";
$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": 50911,
        "redirect_url": "/payment/?oid=50911&checksum=50f1c60363c29c19b1c18359f1b4cfc655165117",
        "payment_url": "http://sandbox.baokim.vn/payment/?oid=50911&checksum=50f1c60363c29c19b1c18359f1b4cfc655165117",
        "bank_account": {
            "acc_name": "Bank Account Name",
            "acc_no": "Bank Account Number",
            "bank_name": "Bank Name",
            "branch": "Bank Branch",
            "amount": "Amount transfer on Bank"
        }
    }
}

HTTP Request

POST api/v4/order/send

Body Parameters

Parameter Type Status Description
mrc_order_id string required Merchant order_id
total_amount integer required total order amount
description string required Transaction description
url_success string required The url redirects again after the payment is successful
url_detail string Optional Line item url (redirect when guest canceles)
lang string Optional Language payment page
bpm_id integer Optional Payment method ID from the Bank From the API Bank Payment Method List
accept_bank int(0,1) Optional Accept payment by ATM card? (Accepted: 1, Not accepted: 0, default: 1)
accept_cc int(0,1) Optional Accept payment by Credit card? (Accepted: 1, Not accepted: 0, default: 1)
accept_qrpay(0,1) integer Optional Accept payment by QR code? (Accepted: 1, Not accepted: 0, default: 0)
webhooks string optional The url used to send notifications to the sales website, chat, ... when the order is successful, allows notify to multiple urls, separated by a comma ","
customer_email string optional Email customer
customer_phone string optional Customer phone number
customer_name string optional Customer's full name
customer_address string optional Customer address

Order Detail

[API Get order details information, can be used to check the status of order payment.] Orders are considered to have been successfully paid when available:

Note: With payment from credit card, the order may be pending 'r' (Reviewing). In this case, the customer has paid but the transaction must wait for the Bank's approval. Bao Kim will not add the wallet balance to the Merchant until the bank approves it. Immediate delivery or waiting for approval will be given to Merchant's discretion.

List of order status:

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'] = '76OCuDznkgkM3jv0';
$options['query']['mrc_order_id'] = 'imrksJ7yZ3ptntQT';

$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 Order ID [semi-optional]
mrc_order_id optional The unique order code is created for the merchant [semi-optional]

List Order

[API Get user list of orders, can be used to control orders between the application and Bao 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'] = 'fGZIxRvWAROMzyer';
$options['query']['txn_id'] = 'F9uczVqFj8QNr41s';
$options['query']['stat'] = 'sY4HmVuGF8XZZObp';
$options['query']['from_date'] = 'IWRxOSRwTq0fS8C8';
$options['query']['to_date'] = 'CA2nr9pbNs6H7xLr';
$options['query']['per_page'] = '5xRNwOhXMlnkg7y0';
$options['query']['page'] = '10';

$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 Merchant orders code
txn_id optional Transaction code
stat optional Orders status
from_date optional orders from date
to_date optional Orders to date
per_page optional Number of records per page
page optional Page index should be get

Cancel Order

[API cancel orders, use in case you do not want to receive payment for orders anymore]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/order/cancel"     -d "id"="12" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/order/cancel",
    "method": "POST",
    "data": {
        "id": 12
    },
    "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'] = "12";
$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 Orders ID

Refund API

Api gives refunds for completed transactions

Create Refund

[Create a refund transaction]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/refund/create"     -d "txn_id"="z1uyiEUgamNutMaw" \
    -d "description"="VMxdblTIbmc1OPcR" \
    -d "chanel"="KjxMLGIHMfgix5Dp" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/refund/create",
    "method": "POST",
    "data": {
        "txn_id": "z1uyiEUgamNutMaw",
        "description": "VMxdblTIbmc1OPcR",
        "chanel": "KjxMLGIHMfgix5Dp"
    },
    "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'] = "z1uyiEUgamNutMaw";
$payload['description'] = "VMxdblTIbmc1OPcR";
$payload['chanel'] = "KjxMLGIHMfgix5Dp";
$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 Transaction ID
description string required Description refund (max : 255 characters)
chanel string optional Refund channel for banks or Bao Kim wallet (BANK, BAOKIM)

Transaction API

APIs for transactions

Transaction list

[API accesses user transaction history information, can be used in transaction control]

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'] = 'LkZ76nM1qF1ubNgQ';
$options['query']['type'] = 'VYelr3vT9VJI9R3U';
$options['query']['ref_no'] = 'YIQLgNdPDE37teN5';
$options['query']['stat'] = 'iMo9xSmRVyQENUot';
$options['query']['from_date'] = 'NSedbYJzFS5IBeP7';
$options['query']['to_date'] = 'uIMTRxDHAEbUDzU4';
$options['query']['page'] = '12';
$options['query']['per_page'] = '0UvVLGSl2OTcgHhu';

$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 Transaction ID
type optional Transaction type 1:Recharge, 3:Withdrawal, 5:Transfer, 7:Refund
ref_no optional Reference code
stat optional Transaction status
from_date optional Transaction from date
to_date optional Transaction to date
page optional Page index to get
per_page optional Number of records per page

Transaction detail

[API access details one transaction]

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'] = 'oOH0tNXgEOuVElyy';

$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 Transaction ID

Transfer API

API performs money transfer for other users

Create transfer

[API Transfer money from Bao Kim wallet to another user]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/transfer/create"     -d "to_user"="njjMOmzSuZB3P5DQ" \
    -d "amount"="aPz0NBlKfJTAyR75" \
    -d "description"="7T60RxOIggfpY7vn" \
    -d "verification_code"="LnG1UxmbTUVskVVm" \
    -d "fee_payer"="geFsH5w5goqgyIQK" \
    -d "txn_mode"="KYvuEotNTRxctkLx" \
    -d "order_id"="2" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/transfer/create",
    "method": "POST",
    "data": {
        "to_user": "njjMOmzSuZB3P5DQ",
        "amount": "aPz0NBlKfJTAyR75",
        "description": "7T60RxOIggfpY7vn",
        "verification_code": "LnG1UxmbTUVskVVm",
        "fee_payer": "geFsH5w5goqgyIQK",
        "txn_mode": "KYvuEotNTRxctkLx",
        "order_id": 2
    },
    "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'] = "njjMOmzSuZB3P5DQ";
$payload['amount'] = "aPz0NBlKfJTAyR75";
$payload['description'] = "7T60RxOIggfpY7vn";
$payload['verification_code'] = "LnG1UxmbTUVskVVm";
$payload['fee_payer'] = "geFsH5w5goqgyIQK";
$payload['txn_mode'] = "KYvuEotNTRxctkLx";
$payload['order_id'] = "2";
$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 beneficiary
amount decimal required Transfer amount
description string required Transaction content
verification_code string optional 2FA authentication code (does not apply to users using API Key)
fee_payer int[1,2] optional optional User pays, 1: user send, 2: user receives, default: 2
txn_mode int[1,2] optional optional trading mode, 1: direct, 2: safe, default: 1
order_id integer optional optional Order code if the payment is for payment of the order

VAT API

Bao Kim's increased service APIs (topup / card code / game card / ...)

List

[API returns a list of value-added services Bao kim supports. Merchant uses the parameters id in items this API to use in the service purchase API]

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 for merchant to buy value-added services of Bao Kim]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/vat/purchase"     -d "mrc_order_id"="iCrWGutZ44ne92il" \
    -d "service_item_id"="14" \
    -d "amount"="8" \
    -d "phone"="P9blF1KX9tHoJbsB" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/vat/purchase",
    "method": "POST",
    "data": {
        "mrc_order_id": "iCrWGutZ44ne92il",
        "service_item_id": 14,
        "amount": 8,
        "phone": "P9blF1KX9tHoJbsB"
    },
    "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'] = "iCrWGutZ44ne92il";
$payload['service_item_id'] = "14";
$payload['amount'] = "8";
$payload['phone'] = "P9blF1KX9tHoJbsB";
$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 Order code (Created on Merchant's system, is unique)
service_item_id integer optional Service code (taken in API Service list)
amount integer required Scratch card value / loaded value (taken in API Service list)
phone string optional Phone number entered Topup (required if buying Topup)

Withdraw API

API carries out cash withdrawal from wallet => bank

Create Withdrawal

[API to withdraw money from Bao Kim wallet to Bank Card/Bank Account]

Example request:

curl -X POST "https://api.baokim.vn/payment/api/v4/withdraw/create"     -d "card_id"="18" \
    -d "bank_account_id"="3" \
    -d "amount"="KwnyfhkRxfyGWh0Q" \
    -d "descripton"="3gCsbPl18k3bbiBj" \
    -d "verification_code"="CJe7VPA9rZ95kaZm" 
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://api.baokim.vn/payment/api/v4/withdraw/create",
    "method": "POST",
    "data": {
        "card_id": 18,
        "bank_account_id": 3,
        "amount": "KwnyfhkRxfyGWh0Q",
        "descripton": "3gCsbPl18k3bbiBj",
        "verification_code": "CJe7VPA9rZ95kaZm"
    },
    "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'] = "18";
$payload['bank_account_id'] = "3";
$payload['amount'] = "KwnyfhkRxfyGWh0Q";
$payload['descripton'] = "3gCsbPl18k3bbiBj";
$payload['verification_code'] = "CJe7VPA9rZ95kaZm";
$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 Account ID Received
bank_account_id integer optional required_without: card_id ID Card Receiving money
amount decimal required Amount withdrawn
descripton string required Transaction content
verification_code string optional 2FA authentication code, does not apply to authentication transactions via user API Key