VLoad - Merchant API
Overview
VLoad is a prepaid top-up voucher service that enables customers to make online payments. VLoad uses a 16-digit PIN that represents the equavalent cash value indicated on the voucher, which is individually encoded and issued, in exchange for payment at merchant website. A range of denominations and currencies are available.This API document is intended for Participating Merchants to implement point of redemption mechanism on their website, which enables customer to enter the 16-digits PIN to make purchases.
Flow of Process:
- Customer enters 16 to 20 digit PIN number on the voucher in a PIN field
- Voucher Validate: VLoad API will check the status of the PIN (ACTIVE, OPEN or USED)
- Voucher Redeem: VLoad API will mark off the entered PIN as USED to finalise the purchase
Error Handling
| Result | Descripton | Meaning |
| 0 | Success | Transaction has been processed succesfully |
| 503 | Error | Maintenance Mode |
| 4019 | Voucher Type or value is not accepted | The voucher type or Value is not accepted by merchant |
| 4071 | Fraud suspicion | The voucher is blocked and can not be used at this time |
| 4072 | Voucher is used | The voucher has already been used |
| 4073 | Voucher is not active | The voucher is not in an active status and can not be used |
| 4074 | Voucher is expired | The voucher has expired and can not be used |
| 4075 | Voucher is not found | The voucher can not be found |
| 4076 | Decline | Mismatch Customer match score overpass decline treshold |
| 4080 | Voucher has insufficient value | The voucher value is insufficient for the request |
| 5000 | Store data is not available | Store data is not available |
Payout Error Handling:
| Result | Descripton | Meaning |
| 403 | Unauthorized | You are not authorized to access this resource |
| 4081 | No amount remains | Total payout amount exceeded |
| 4082 | Exceed available remains | Requested amount exceds the avilable balance |
| 4083 | Customer exceed balance | Customer Tier limit execeeded |
| 4085 | General exception | Something went wrong. |
| 4086 | Missing parameters | Some parameters are missing. |
| 4087 | Invalid value | Invalid customer id or amount |
| 4088 | Customer mismatch | Customer mismatch. |
HMAC Authentication
HMAC Authentication is required for all endpoints using the following HTTP header format AUTHENTICATION: HMAC [api_key]:[signature]:[nonce] REST API Test Environment URL: https://testrest.vload.expert REST API Production Environment URL: https://rest.vload.expert
| Parameter | Description |
| api_key | Merchant API Key |
| signature | The following data sha256 hashed with the Merchant Secret Request method (eg GET) Request URI (eg /Validate) nonce (eg 14333247747) JSON Body of the request |
| nonce | Unique number value for the api request |
The HMAC header is made up of your API Key, a signature and a nonce. To obtain the signature, you will need to append your payload data (Method, URI, Nonce) each separated by a new line(\n). Below is a sample payload: PUT(\n)/voucher/redeem/123456789/VLoad_Tester/Transaction_1(\n)1448933002796888(\n) Then hash it with your API Secret to obtain your signature: Eg. using a PHP example, it would look like this: hash_hmac('sha256', $payload, $this->secret); Finally a single HMAC header would typically look like this: AUTHENTICATION: HMAC YOUR_API_KEY:4d0067b8471ba820d7e3f9764ce1ac8be0f206f8b3cebd5814d41614dc:1448027968881232 During testing the API key and secret key will be provided to the participating merchant. Request API keys to your Sales Account Manager / Technical Support
Validate Voucher request contains the following data:
private $rootPath = "https://testrest.vload.expert";
$requestUri = "https://testrest.vload.expert/voucher/validate/"; // Validate URL
//$requestUri = "https://testrest.vload.expert/voucher/redeem/"; // Redeem URL
$requestMethod = "GET"; // GET : Validate our PUT : Redeem
$mt = explode(' ', microtime());
$nonce = $mt[1] . substr($mt[0], 2, 6);
$json=null;
if (isset($body)) {
$json = json_encode($body);
}
$payload = ''; //Notice that each line must be separated by a "\n"
$payload .= $requestMethod . "\n";
$payload .= $requestUri . "\n";
$payload .= $nonce . "\n";
$payload .= $json;
$signature = $this->get_signature($payload); //See get_signature function below
$headers = array('AUTHENTICATION: HMAC ' . 'API KEY' . ':' . $signature . ':' . $nonce); //This is what the header consists of
private function get_signature($payload) { //To obtain signature, hash your payload wirth your API secret
return hash_hmac('sha256', $payload, $this->secret);
}
Server Status
Retrieve the status of the API
| Parameter | Description |
| Action Method | GET |
| URL | https://testrest.vload.expert/status |
Request Sample
curl --include \
'https://testrest.vload.expert/status'
Response:
{
"status": "alive"
}
Response:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/status");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
Sending Customer IP and ID
Customer ID and IP should be send within redeem request URL and redeem function
| Parameter | Description | Required |
| customer_id | Merchant customer identifier | Yes |
| customer_ip | Client IP of the customer who has instigated the transactions | Yes |
| first_name | Client first name | Optional |
| last_name | Client last name | Optional |
| Client email address | Optional |
Request Sample
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"customer_id\": \"Customer\'s unique identifier\",
\"customer_ip\": \"Customer\'s IP address\",
}" \
'https://testrest.vload.expert/voucher/redeem/{pin}/{terminal_id}/{current_transaction_id}'
Response:
$customer_id = '3322111'; // Unique Customer ID
$customer_ip = '127.0.0.1';
$first_name = 'David';
$last_name = 'Ramirez';
$email = '[email protected]';
$body = [
"customer_id"=> $customerID, //Merchant customer identifier
"customer_ip" => $customer_ip, //Customer IP Address
"first_name" => $first_name, //Client first name
"last_name" => $last_name, //Client last name
"email" => $email Client email address
];
$res = $fp->voucherRedeem("pin","terminal_id","current_transaction_id",$body);
Single Voucher
Perform operations on vouchers for the purpose of validation and redemption
Validate Voucher
Query the validity and details of a voucher
Request URL : https://testrest.vload.expert/voucher/validate/pin/terminal_id/current_transaction_id
Send Request Data description:
| Parameter | Description |
| Action | GET |
| URL | https://testrest.vload.expert/voucher/validate/ |
| pin | VLoad 16-digit pin number |
| terminal_id | Set by you, the Merchant, the terminal ID or device ID indicates from where the transaction is instigated (eg, website, mobile app etc), MAX 32 unique Char |
| current_transaction_id | Set by you, the Merchant, the Current transaction ID is unique to your environment, MAX 32 unique Char |
Single Voucher Response Data description:
| Parameter | Description |
| serial | Serial number of the voucher (string) |
| value | Value of the voucher transaction (decimal) |
| cost | Commissioned value of the voucher (decimal) |
| currency | Currency code of the voucher (string) |
| status | Vload API will check the status of the PIN (ACTIVE or USED) |
| description | Description of the voucher type |
| ean | EAN of the voucher type |
| transaction_id | Merchant transaction ID |
| trans_no | VLoad transaction reference (string) |
| result | Result code (number) |
| result_description | Result description (string) |
| http_code | HTTP response codes (string) |
Validate Voucher request contains the following data:
curl --include \
'https://testrest.vload.expert/voucher/validate/{pin}/{terminal_id}/{current_transaction_id}'
Response contains the following data:
Array
(
[result] => 0
[result_description] => Success
[transaction_id] => Trans_No_123411
[trans_no] => 339352
[serial] => 54010500000270434
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
[http_code] => 200
)
Validate Voucher request contains the following data:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/voucher/validate/{pin}/{terminal_id}/{current_transaction_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
$response = curl_exec($ch);
curl_close($ch);
print_r(($response);
Response contains the following data:
Array
(
[result] => 0
[result_description] => Success
[transaction_id] => Trans_No_123411
[trans_no] => 339352
[serial] => 54010500000270434
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
[http_code] => 200
)
Redeem Voucher
The message body consists of a JSON structure containing data relevant to the transaction.
Request URL : https://testrest.vload.expert/voucher/redeem/pin/terminal_id/current_transaction_id
Send Request Data description:
| Parameter | Description |
| Action | PUT |
| URL | https://testrest.vload.expert/voucher/redeem/ |
| pin | VLoad 16-digit pin number |
| terminal_id | Set by you, the Merchant, the terminal ID or device ID indicates from where the transaction is instigated (eg, website, mobile app etc), MAX 32 unique Char |
| current_transaction_id | Set by you, the Merchant, the Current transaction ID is unique to your environment, MAX 32 unique Char |
Single Redeem Voucher Response Data description:
| Parameter | Description |
| serial | Serial number of the voucher (string) |
| value | Value of the voucher transaction (decimal) |
| cost | Commissioned value of the voucher (decimal) |
| currency | Currency code of the voucher (string) |
| status | USED (if it's successfully redeemed) |
| description | Description of the voucher type |
| ean | EAN of the voucher type |
| transaction_id | Merchant transaction ID |
| trans_no | VLoad transaction reference (string) |
| result | Result code (number) |
| result_description | Result description (string) |
| http_code | HTTP response codes (string) |
Validate Voucher request contains the following data:
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"customer_id\": \"Customer\'s unique identifier\",
\"customer_ip\": \"Customer\'s IP address\",
}" \
'https://testrest.vload.expert/voucher/redeem/{pin}/{terminal_id}/{current_transaction_id}'
Response contains the following data:
Array
(
[result] => 0
[result_description] => Success
[transaction_id] => Trans_No_123411
[trans_no] => 339352
[serial] => 54010500000270434
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
[http_code] => 200
)
Validate Voucher request contains the following data:
$ch = curl_init();
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/voucher/redeem/{pin}/{terminal_id}/{current_transaction_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, {
\"customer_id\": \"Customer's unique identifier\",
\"customer_ip\": \"Customer's IP address\",
});
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
Response contains the following data:
Array
(
[result] => 0
[result_description] => Success
[transaction_id] => Trans_No_123411
[trans_no] => 339352
[serial] => 54010500000270434
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
[http_code] => 200
)
Bundle Voucher
For customers purchasing VLoad vouchers directly at vload.expert(or one of the distributors) thefollowing amounts are available: * 10 EUR/USD * 20 EUR/USD * 30 EUR/USD * 50 EUR/USD * 100 EUR/USD * 150 EUR/USD * 200 EUR/USD * 250 EUR/USD * 500 EUR/USD As the client’s shopping cart total may not be equal to any of the predefined voucher denominations,your client can purchase a bundled voucher for the amount of his order/deposit, rounded up to 10.
Customer Redirection to buy Bundle Voucher
Description: Bundle Voucher is only available if customer redirect to vload.expert via POST Method
Bundle Voucher Data description:
| Parameter | Description |
| action url | TEST: https://test.vload.expert/cart/voucher_group PROD: https://www.vload.expert/cart/voucher_group |
| currency | Currency code of the voucher |
| amount | Full amount to charge in currency specified. The amount must be specified as a number with decimal point and 2 digits to the right of the decimal point. Decimal separator must be point (.). example: 3500.25 = Three thousand five hundred units of currency and twenty five hundredths of a single unit of currency. |
HTML POST Request Sample
<form action="https://test.vload.expert/cart/voucher_group" method="POST" target="_blank">
<input name="currency" value="EUR">
<input name="amount" value="20.00">
<input type="submit">
</form>
Validate Bundle Voucher
Query the validity and details of sub vouchers
Request URL : https://testrest.vload.expert/voucher/validate/pin/terminal_id/current_transaction_id
Send Request Data description:
| Parameter | Description |
| Action | GET |
| URL | https://testrest.vload.expert/voucher/validate/ |
| pin | VLoad 16-digit pin number |
| terminal_id | Set by you, the Merchant, the terminal ID or device ID indicates from where the transaction is instigated (eg, website, mobile app etc), MAX 32 unique Char |
| current_transaction_id | Set by you, the Merchant, the Current transaction ID is unique to your environment, MAX 32 unique Char |
Bundle Voucher Response Data description:
| Parameter | Description |
| serial | Serial number of the voucher (string) |
| 1stvalue | Sum of Bundle Value of the voucher transaction (decimal) |
| 2ndvalue | Single Voucher value (decimal) |
| cost | Commissioned value of the voucher (decimal) |
| currency | Currency code of the vouchers (string) |
| vouchers | Sub Single Vouchers List (Array) |
| status | Vload API will check the status of the PIN (ACTIVE or USED) |
| description | Description of the voucher type |
| ean | EAN of the voucher type |
| transaction_id | Merchant transaction ID |
| trans_no | VLoad transaction reference (string) |
| result | Result code (number) |
| result_description | Result description (string) |
| http_code | HTTP response codes (string) |
Validating Bundle Voucher request contains the following data:
curl --include \
'https://testrest.vload.expert/voucher/validate/{pin}/{terminal_id}/{current_transaction_id}'
Response contains the following data:
Array
(
[serial] => 62083704126453510235
[value] => 20.00
[currency] => EUR
[vouchers] => Array
(
[0] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338310
[serial] => 54010500000270469
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
)
[1] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338311
[serial] => 54010500000270470
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
)
)
[result] => 0
[result_description] => Success
[http_code] => 200
) Validate Voucher request contains the following data:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/voucher/validate/{pin}/{terminal_id}/{current_transaction_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
$response = curl_exec($ch);
curl_close($ch);
print_r(($response);
Response contains the following data:
Array
(
[serial] => 62083704126453510235
[value] => 20.00
[currency] => EUR
[vouchers] => Array
(
[0] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338310
[serial] => 54010500000270469
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
)
[1] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338311
[serial] => 54010500000270470
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => ACTIVE
)
)
[result] => 0
[result_description] => Success
[http_code] => 200
)
Redeem Bundle Voucher
Query the validity and details of sub vouchers
Request URL : https://testrest.vload.expert/voucher/redeem/pin/terminal_id/current_transaction_id
Send Request Data description:
| Parameter | Description |
| Action | GET |
| URL | https://testrest.vload.expert/voucher/redeem/ |
| pin | VLoad 16-digit pin number |
| terminal_id | Set by you, the Merchant, the terminal ID or device ID indicates from where the transaction is instigated (eg, website, mobile app etc), MAX 32 unique Char |
| current_transaction_id | Set by you, the Merchant, the Current transaction ID is unique to your environment, MAX 32 unique Char |
Redeem Bundle Voucher Response Data description:
| Parameter | Description |
| serial | Serial number of the voucher (string) |
| 1stvalue | Sum of Bundle Value of the voucher transaction (decimal) |
| 2ndvalue | Single Voucher value (decimal) |
| cost | Commissioned value of the voucher (decimal) |
| currency | Currency code of the vouchers (string) |
| vouchers | Sub Single Vouchers List (Array) |
| status | USED (if it's successfully redeemed) |
| description | Description of the voucher type |
| ean | EAN of the voucher type |
| transaction_id | Merchant transaction ID |
| trans_no | VLoad transaction reference (string) |
| result | Result code (number) |
| result_description | Result description (string) |
| http_code | HTTP response codes (string) |
Validating Bundle Voucher request contains the following data:
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"customer_id\": \"Customer\'s unique identifier\",
\"customer_ip\": \"Customer\'s IP address\",
}" \
'https://testrest.vload.expert/voucher/redeem/{pin}/{terminal_id}/{current_transaction_id}'
Response contains the following data:
Array
(
[serial] => 62083704126453510235
[value] => 20.00
[currency] => EUR
[vouchers] => Array
(
[0] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338310
[serial] => 54010500000270469
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
)
[1] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338311
[serial] => 54010500000270470
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
)
)
[result] => 0
[result_description] => Success
[http_code] => 200
) Validate Voucher request contains the following data:
$ch = curl_init();
$ch = curl_init();
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/voucher/redeem/{pin}/{terminal_id}/{current_transaction_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, {
\"customer_id\": \"Customer's unique identifier\",
\"customer_ip\": \"Customer's IP address\",
});
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
Response contains the following data:
Array
(
[serial] => 62083704126453510235
[value] => 20.00
[currency] => EUR
[vouchers] => Array
(
[0] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338310
[serial] => 54010500000270469
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
)
[1] => Array
(
[result] => 0
[result_description] => Success
[transaction_id] => 62083704126453510235
[trans_no] => 338311
[serial] => 54010500000270470
[value] => 10
[cost] => 9.4
[currency] => EUR
[description] => Vload EUR 10
[ean] => 9350233004018
[status] => USED
)
)
[result] => 0
[result_description] => Success
[http_code] => 200
)
Payout
The message body consists of a JSON structure containing data relevant to the transaction.
Request URL : https://testrest.vload.expert/payout/execute/current_transaction_id
Send Request Data description:
| Parameter | Description |
| Action | POST |
| URL | https://testrest.vload.expert/execute/payout |
| current_transaction_id | Body JSON |
| amount | The total amount paid for the transaction |
| currency | The currency used for the transaction |
| customer_id | Customer Id |
| first_name | Customer first name |
| last_name | Customer last name |
| Customer email address |
Payout Response Data description:
| Parameter | Description |
| code | Response data (string) |
| description | Description of the voucher type |
| http_code | HTTP response codes (string) |
Validate Voucher request contains the following data:
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{curl_init()
\"amount\": \"Amount paid by the customer\",
\"currency\": \"Currency in which the transaction is done\",
\"first_name\": \"First Name of the customer\",
\"last_name\": \"Last Name of the customer\",
\"email\": \"Email of the customer\"
}" \
'https://testrest.vload.expert/execute/payout/{current_transaction_id}'
Response contains the following data:
Array
(
[amount] => 60
[currency] => EUR
[customer_id] => 123456
[first_name] => David
[last_name] => Ramirez
[email] => [email protected]
)
Payout request contains the following data:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://testrest.vload.expert/execute/payout//{current_transaction_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
$body = [
"amount"=> 60,
"currency"=> 'EUR',
"customer_id"=>"123455",
"first_name" => "David",
"last_name" => "Ramirez",
"email" => "[email protected]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
Response contains the following data:
Array
(
[code] => 4087
[description] => Invalid customer id.
[http_code] => 200
)
EANs LIST
| EAN | Descripton | Amount |
| USD | ||
| 9350233000072 | VLOAD USD 10 | 10.00 |
| 9350233000089 | VLOAD USD 20 | 20.00 |
| 9350233000096 | VLOAD USD 30 | 30.00 |
| 9350233000102 | VLOAD USD 50 | 50.00 |
| 9350233000119 | VLOAD USD 100 | 100.00 |
| 9350233000126 | VLOAD USD 150 | 150.00 |
| 9350233000133 | VLOAD USD 200 | 200.00 |
| 9350233000140 | VLOAD USD 250 | 250.00 |
| 9350233000157 | VLOAD USD 500 | 500.00 |
| EUR | ||
| 9350233004117 | VLOAD EUR 10 | 10.00 |
| 9350233004124 | VLOAD EUR 20 | 20.00 |
| 9350233004179 | VLOAD EUR 30 | 30.00 |
| 9350233004186 | VLOAD EUR 50 | 50.00 |
| 9350233004131 | VLOAD EUR 100 | 100.00 |
| 9350233004148 | VLOAD EUR 150 | 150.00 |
| 9350233004155 | VLOAD EUR 200 | 200.00 |
| 9350233004162 | VLOAD EUR 250 | 250.00 |
| 9350233004278 | VLOAD EUR 500 | 500.00 |