Buy Voucher

DescriptionThis API is about to buy vouchers.

This API must be requested from your server side

Request

Method Content Type URL POST Application/JSON https://evoucher.giftz.vn/api/v1/buy-voucher

Params

Param Name (Case-sensitive) Type Required Description user_name string required user, provided by GiftZ trans_id string required unique in your system voucher_id string required Voucher ID, this is the ID from get-available-vouchers API time integer required current timestamp quantity integer required Quantity of vouchers, quantity > 0 and <= 10 checksum string required Check sum of transaction
$checksum = base64_encode(hash('sha256', $user_name . $trans_id . $voucher_id . $quantity . $secure_key . $time, true));
$secure_key: provided by GiftZ
Note: We use sha256 with binary mode, the parameter with "true" indicates this

Response

Status Code Response success 200

                                    
{
    "data":
       {
         "code": "200",
         "status": "success",
         "message": "Buy vouchers success",
         "number_of_vouchers": int,
         "vouchers": [
             {
               "voucher_id": "znke",
               "custom_data": "a_json_data",
               "secure_data": "encrypted_json_data"
             },
             {
               "voucher_id": "znke",
               "custom_data": "a_json_data",
               "secure_data": "encrypted_json_data"
              }
          ]
       }
}

* subscription_data must be decrypted to get the real data, and it's json data. See decryption at the end of document fail 202 {"data": { "code": "202", "status": "fail", "message": "Buy voucher failed, voucher is not available"}}

fail 100 {"errors": {"code": 100, "status": "error", "message": "Out of balance"}} fail 102

{"errors": {"code": 102, "status": "error", "message": "Transaction ID existed", "vouchers": [{ "voucher_id": "znke", "custom_data": "a_json_data", "secure_data": "encrypted_json_data" }, { "voucher_id": "znke", "custom_data": "a_json_data", "secure_data": "encrypted_json_data" }]}}

fail 106 {"errors": {"code": 106, "status": "error", "message": "Parameter is invalid"}} fail 108 {"errors": {"code": 108, "status": "error", "message": "Request from IP is not allowed"}}

* Notes: IMPORTANT

We encrypt code by using AES algorithm, from your end you must use the same algorithm to decrypt

We will provide password to partner. Please keep it securely

PHP

function encrypt($text, $password)
{
    define("AES_METHOD","aes-256-cbc");

    if (OPENSSL_VERSION_NUMBER <= 268443727) {
        throw new \RuntimeException('OpenSSL Version too old');
    }

    $ivSize        = openssl_cipher_iv_length();
    $iv             = openssl_random_pseudo_bytes($ivSize); //we generate random iv

    $cipherText     = openssl_encrypt($text, AES_METHOD, $password, OPENSSL_RAW_DATA, $iv); //encrypt data to binary

    $ciphertextHex = bin2hex($cipherText); //convert encrypted data to hex
    $ivHex         = bin2hex($iv);         //convert iv to hex

    //the encrypted code is concatenated by iv and cipher text, partner need to parse it to get iv - delimiter is :
    return "$ivHex:$ciphertextHex";
}

function decrypt($encryptedText, $password)
{
    define("AES_METHOD","aes-256-cbc");

    $data       = explode(":", $encryptedText); //parse encrypted text to get iv and cipher text

    $iv         = hex2bin($data[0]); //convert iv to binary
    $cipherText = hex2bin($data[1]); //convert encrypted text to binary

    return openssl_decrypt($cipherText, AES_METHOD, $password, OPENSSL_RAW_DATA, $iv);
}

NodeJS


const crypto = require("crypto");

function encrypt(text, password) {
    if (process.versions.openssl <= '1.0.1f') {
        throw new Error('OpenSSL Version too old, vulnerability to Heartbleed')
    }

    let iv = crypto.randomBytes(IV_LENGTH);
    let cipher = crypto.createCipheriv(AES_METHOD, new Buffer.from(password), iv);

    let encrypted = cipher.update(text);

    encrypted = Buffer.concat([encrypted, cipher.final()]);

    return iv.toString('hex') + ':' + encrypted.toString('hex'); //convert iv and encrypted text to hex (from BINARY) then concatenate them with :

}

function decrypt(text, password) {
    let textParts = text.split(':');

    let iv = new Buffer.from(textParts.shift(), 'hex'); //convert iv from hex to binary
    let encryptedText = new Buffer.from(textParts.join(':'), 'hex');   //convert text from hex to binary

    let decipher = crypto.createDecipheriv('aes-256-cbc', new Buffer.from(password), iv);
    let decrypted = decipher.update(encryptedText);

    decrypted = Buffer.concat([decrypted, decipher.final()]);

    return decrypted.toString();
}

Other APIs

Get Available Vouchers API