Itez widget integration
ITEZ - Fast and secure way to purchase Bitcoin with a bank card. You can place a ready-made widget for buying cryptocurrencies with a bank card on your website or integrate into your application.
Step 1 - Get your token.
Contact to your personal manager or fill the onboarding form and get credentials for the integration.
Step 2 - Install the solution.
Installing the widget on your service, you agree to the following rules.
Itez credentials
Contact to your personal manager or fill the onboarding form.
Partner token
Token - Itez partner's unique token. Token provide your identification and access to Itez services.
Itez secret
Itez secret - its a key for generating and check parameters signature. Itez secret is needed to integrate the widget on the webpage, sign API messages and check incoming callback data.
Website integration
...
<script src="https://pay.itez.com/static/main/share/merchant.js"></script>
<script>
function runItezWidget() {
ItezWidget.run({
partner_token:'...',
target_element:'widget-container',
timestamp: ...,
signature: '...'
}, 'POST');
}
window.onload = runItezWidget;
</script>
...
<div id="widget-container"></div>
...
- Include https://pay.itez.com/static/main/share/merchant.js
- Call ItezWidget.run. The first parameter must be an object containing the widget's settings. Minimum list of object fields:
Field | Type | Description |
---|---|---|
target_element | string | The ID of the HTML element into which Itez Widget is embedded. In our example - . |
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Рartner_token, target_element, timestamp и signature are required fields to run. You can also setup the widget using additional options.
Widget settings
ItezWidget.run
parameters can be divided into three groups: required, optional, and event handlers.
Required settings
Parameter | Type | Description |
---|---|---|
target_element | string | The ID of the HTML element into which Itez Widget is embedded. |
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Optional settings
Parameter | Type | Description |
---|---|---|
from_currency | string | The currency code (ISO 4217) that is being converted. For example: USD. |
from_amount | number | Amount in the source currency (in minimum currency units, for USD, 1 USD = 100 minimum units - cents). the input field will be filled by value from_amount, if it is set. From_amount can not be passed without from_currency. |
to_currency | string | Resulting Currency Code (ISO 4217 - like). For example: BTC |
to_amount | number | Amount in the resulting currency (in minimum currency units, for BTC, 1 BTC = 100,000,000 minimum units - Satoshi). It can not be passed without to_currency. |
to_account | string | Client’s crypto wallet address. |
lang | string | The language in which the displayed payment page will be open to the user. The language is transmitted in ISO 639-1 alpha-2 format. If this parameter is not passed, then the default value is “en”. |
user_login | string | Itez customer login (email address). |
partner_operation_id | string | Opertaion ID at partners system. |
partner_css | string | CSS-file location. it defines the widget element colors setting. See more... |
Event handlers
All event handlers are optional.
Event handler | Description |
---|---|
onLoaded | Finish loading widget content. |
onResize | Resizing the document inside the iframe widget. |
onExit | Close the widget, contains no data. |
onError | An error in the work of the widget, which does not allow the process to continue. |
onStarted | The widget started from the starting point (called at each reset to the beginning). Contains no data. |
onOperationCreated | Registration of transactions in processing. |
onPaymentSent | Sending payment data - the user clicked on Pay, does not contain data. |
onOperationSuccess | Successful purchase operation. |
onOperationPending | Purchase operation in progress. |
onOperationFail | Unsuccessful purchase operation. |
onLoaded
// Example.
// Console output of the length and width of the widget after loading.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onLoaded = (data) => {
console.log('width', data.width);
console.log('height', data.height);
};
ItezWidget.run(data, 'POST');
// Input data example
{
width: 372,
height: 352
}
Event handler. Event raised when widget has loaded its loading content.
Handler recive parameter with fields:
Field | Type | Description |
---|---|---|
width | number | Widget width in pixels. |
height | number | Widget height in pixels. |
onResize
// Example.
// Console output of the length and width
// of the widget after resize.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onLoaded = (data) => {
console.log('width', data.width);
console.log('height', data.height);
};
ItezWidget.run(data, 'POST');
// Input data example
{
width: 372,
height: 352
}
Event handler. Event raised when widget has resized. Its may happens when the set of elements in the widget changed. If user goes through the purchase steps, for example. The widget changes its height, in most cases.
Handler recive JSON with fields:
Field | Type | Description |
---|---|---|
width | number | Widget width in pixels. |
height | number | Widget height in pixels. |
onExit
Event hanlder on close widget. Function has no parameters.
onError
// Example.
// Console output of the error text.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onError = (data) => console.log('error', data.message);
ItezWidget.run(data, 'POST');
// Input data example
{
message: "Application error Network Error"
}
Event handler. An error in the work of the widget, which does not allow the process to continue.
Handler recive JSON with field:
Field | Type | Description |
---|---|---|
message | string | Error description. |
onStarted
Event handler. Event rises when the widget started from the starting point (called at each reset to the beginning). Function has no parameters.
onOperationCreated
// Example.
// Console output of the purchase ID.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onOperationCreated = (id) => console.log('operation ID', id);
ItezWidget.run(data, 'POST');
// Input data example
id == "1234567890"
Event handler on registration transaction in processing.
Handler recive string parameter of the purchase ID.
onPaymentSent
Event handler. Event rises when widget sent payment data - the user clicked on "Pay" button. Function has no parameters.
onOperationSuccess
// Example.
// Console output of the status and operation ID.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onOperationSuccess = (data) => {
console.log('ID', data.operation_info.id);
console.log('status', data.status);
}
ItezWidget.run(data, 'POST');
Event handler. Event raised when operation status set to "success". Handler recive operation_data parameter.
onOperationPending
// Example.
// Console output of the status and operation ID.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onOperationPending = (data) => {
console.log('ID', data.operation_info.id);
console.log('status', data.status);
}
ItezWidget.run(data, 'POST');
Event handler. Purchase operation in progress.
Handler recive operation_data parameter.
onOperationFail
// Example.
// Console output of the status and operation ID.
const data = {
partner_token: '...',
target_element: 'widget-container',
timestamp: ...,
signature: '...'
};
data.onOperationFail = (data) => {
console.log('ID', data.operation_info.id);
console.log('status', data.status);
}
ItezWidget.run(data, 'POST');
Event handler. Unsuccessful purchase operation.
Handler recive operation_data parameter.
Widget parameters signature
// This is simple server example for node.js
// It's generate empty web page with Itez widget only.
const { createServer } = require('http');
const { createHmac } = require('crypto');
// yor partner token
const partner_token = '';
// Itez Secret - secret code for make widget signature.
const itez_secret = '';
// Generate html page
function getDocument() {
const params = {
partner_token: partner_token, // partner token
target_element: 'widget-container', // id html item that contains itez widget
timestamp: Date.now(), // current time
};
const jsonToString = (obj) => {
return Object.entries(obj)
.sort()
.map((items) => `${items[0]}:${items[1]}`)
.join(';');
};
function signHmacSha512(obj, secret) {
return createHmac('sha512', secret)
.update(jsonToString(obj))
.digest('hex');
}
// Make signature
params.signature = signHmacSha512(params, itez_secret);
// signed - JSON-object that contains parameters + signature
const signed = JSON.stringify(params);
// empty page with widget
return `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script src="https://pay.itez.com/static/main/share/merchant.js"></script>
<title>Widget integration sample</title>
<script type="text/javascript">
function runItezWidget() {
ItezWidget.run( ${signed}, 'POST');
}
window.onload=runItezWidget;
</script>
</head>
<body >
<div id="widget-container"></div>
</body>
</html>`;
}
createServer((req, res) => {
if (req.url === '/') {
res.end(getDocument());
}
}).listen(80);
// PHP
// creating parameters and signatures
$token = '';
$secret = '';
$params = [
'partner_token' => $token,
'target_element' => 'widget-container',
'timestamp' => (int) (microtime(true) * 1000),
'from_amount' => '3000',
'from_currency' => 'USD',
'lang' => 'EN',
];
ksort($params);
$data = [];
foreach ($params as $key => $value) {
$data[] = "$key:$value";
}
$data = join(";", $data);
$hash = hash_hmac('sha512', $data, $secret);
$params['signature'] = $hash;
<!-- add js script -->
<script src="https://pay.itez.com/static/main/share/merchant.js"></script>
<!-- add container: id of container may be various
but you must set it into parameters -->
<div id="widget-container"></div>
<!-- initialise the widget -->
<script type="text/javascript">
ItezWidget.run(
<?php echo json_encode($params); ?>
);
</script>
Use ItezWidget.run method to run widget. The first parameter of this method is an object that contains the widget settings. This parameter has а signture filed, that contain signature string.
Signature - is a string based on the remaining parameters and Itez Itez Secret. Parameter "signature" is not use in signature creation.
Signature algorithm:
- For each of the signed parameters (the signature parameter is not involved) there is a line like:
"< name >:< value >".
All quotation marks and apostrophes surrounding string values are removed.
Strings must be encoded in UTF-8. - Strings are sorted alphabetically(ordinal).
- Sorted lines are joined into one line with a delimiter ";".
- The HMAC code (SHA-512) of the received string is calculated using Itez Secret, the HMAC code must be generated as raw binary data (raw BINARY-array).
- The resulting binary code is converted to a HEX-string.
- The HEX-string is written to the signature field;
There is a general algorithm that can also be used to sign widget parameters.
Itez API
https://api.itez.com - Itez API URL. The following requests are available:
- Supported countries
- Partner's commission
- Exchange price
- Fixing the rate before purchase
- Getting of operation info
- Operation confirmation
- Operation cancellation
Requests errors you can find here.
Supported countries
https://api.itez.com/api/partner/countries
POST https://api.itez.com/api/partner/countries
Request
// Request exsample
{
"partner_token":"c0aaee39-...",
"timestamp":1661161559871,
"signature":"8190f8227d68c8af1..."
}
Parameter | Type | Description |
---|---|---|
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
// Response example
{
"countries": [
{
"code": 10001,
"name": "Abhazia",
"alpha2": "AB",
"alpha3": "ABH"
},
{
"code": 372,
"name": "Ireland",
"alpha2": "IE",
"alpha3": "IRL"
},
{
"code": 833,
"name": "Isle of Man",
"alpha2": "IM",
"alpha3": "IMN"
},
{
"code": 376,
"name": "Israel",
"alpha2": "IL",
"alpha3": "ISR"
},
...
{
"code": 876,
"name": "Wallis and Futuna Islands",
"alpha2": "WF",
"alpha3": "WLF"
}
],
"signature": "7332c5349fb6d54424c..."
}
Parameter | Type | Description |
---|---|---|
countries | object | Supported countries list. |
signature | string | Sign. |
Every countries item consists.
Parameter | Description |
---|---|
code | ISO 3166-1 numeric. |
name | Country name. |
alpha2 | ISO 3166-1 alpha-2. |
alpha3 | ISO 3166-1 alpha-3. |
Partner's commission
https://api.itez.com/api/partner/params
POST https://api.itez.com/api/partner/params
Request
// Request example
{
"partner_token":"c0aaee39-...",
"timestamp":1661161559871,
"signature":"8190f8227d68c8af1..."
}
Parameter | Type | Description |
---|---|---|
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
// Response example
{
"service_fee": 0.05,
"signature": "8aa916e7d979f4d5c16..."
}
Parameter | Type | Description |
---|---|---|
service_fee | object | Service fee (0.01 = 1%) |
signature | string | Sign. |
Exchange price
https://api.itez.com/api/partner/exchange
POST https://api.itez.com/api/partner/exchange
Request
// Request exsample
{
"partner_token":"c0aaee39-...",
"timestamp":1661161559871,
"signature":"8190f8227d68c8af1..."
}
Parameter | Type | Description |
---|---|---|
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
// Response example
{
"pairs": [
{
"from": {
"amount": 50,
"min_amount": 50,
"max_amount": 300,
"min_kyc_amount": 50,
"max_kyc_amount": 5000,
"code": "EUR",
"name": "Euro",
"symbol": "€",
"minor_unit": 2
},
"to": {
"amount": 0.00234279,
"code": "BTC",
"name": "Bitcoin",
"symbol": "₿",
"minor_unit": 8
}
},
{
"from": {
"amount": 50,
"min_amount": 50,
"max_amount": 300,
"min_kyc_amount": 50,
"max_kyc_amount": 5000,
"code": "EUR",
"name": "Euro",
"symbol": "€",
"minor_unit": 2
},
"to": {
"amount": 0.041908,
"code": "ETH",
"name": "Ethereum ",
"symbol": "Ξ",
"minor_unit": 6
}
},
...
],
"signature": "..."
}
Parameter | Type | Description |
---|---|---|
pairs | object | Currency pairs parameters. |
signature | string | Sign. |
Pairs
Every pairs item conists of two parts: From - part with fiat security data and to with crypto security parameters.
From
Parameter | Type | Description |
---|---|---|
amount | number | Fiat security value |
min_amount | number | Minimum purchase value |
max_amount | number | Maximum purchase value |
min_kyc_amount | number | Minimum purchase value if customer was identified with KYC |
max_kyc_amount | number | Maximum purchase value if customer was identified with KYC |
code | string | ISO-4217 currency code |
name | string | Currency name |
symbol | string | Currency symbol |
minor_unit | string | Minimum currency units |
To
Parameter | Type | Description |
---|---|---|
amount | number | Price in crypto currency for from.amount |
code | string | ISO-4217 like crypto currency code |
name | string | Currency name |
symbol | string | Currency symbol |
minor_unit | string | Minimum currency units |
Fixing the rate before purchase
https://api.itez.com/api/partner/exchange/calculate
POST https://api.itez.com/api/partner/exchange/calculate
Request
// Request example
{
"from_currency":"USD",
"from_amount":100,
"to_currency":"BTC",
"partner_token":"c0aaee39-...",
"signature":"2cc3acf3253065741..."
}
Parameter | Type | Description |
---|---|---|
from_currency | string | The currency code (ISO 4217) that is being converted. In uppercase (USD). |
to_currency | string | Resulting currency code (ISO 4217 - like). In uppercase (BTC). |
from_amount | number | Amount in the source currency (in minimum currency units, for USD, 1 USD = 100 minimum units - cents). |
to_amount | number | Amount in the resulting currency (in minimum currency units, for BTC, 1 BTC = 100,000,000 minimum units - Satoshi). |
partner_token | string | Itez partner token. |
signature | string | Sign. |
Response
// Response example
{
"from_currency":"USD",
"to_currency":"BTC",
"from_amount":100,
"to_amount":4477,
"calculation_id":"8dcecbc5-c272-4247-bbf5-b812e507ec9a",
"expired_at":"2022-08-22T12:52:47.3181644Z",
"signature":"17a310b7f40af89342e02e747..."
}
Parameter | Type | Description |
---|---|---|
calculation_id | string | Rate ID. You can make a purchase at the received rate, if you send the calculation_id to the widget. |
expired_at | string | Expiration time calculation_id. The date is returned in the format 2021-02-12T11:12:57.2695721Z |
from_currency | string | Source currency. |
to_currency | string | Resulting currency. |
from_amount | number | Amount in the source currency. |
to_amount | number | Amount in the resulting currency. |
signature | string | Sign. |
Getting of operation info
https://api.itez.com/api/partner/operation
POST https://api.itez.com/api/partner/operation
Request
// Request exsample
{
"partner_operation_id":"7076b531-...",
"partner_token":"c0aaee39-...",
"timestamp":1661164641882,
"signature":"6c5f9a8e63a9e4e18b..."
}
Parameter | Type | Description |
---|---|---|
partner_operation_id | string | Opertaion ID at partners system. |
operation_id | string | Opertaion ID at Itez system. |
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
// Rsponse example
{
"operation_data": {
"status": "pending",
"status_code": 1,
"operation_info": {
"id": "ccb862f4-4a91-4840-98fd-302cb7282f46",
"created_at": "2022-08-22T10:49:55.891Z",
"from": {
"payment_method": 1,
"payment_method_info": {},
"currency": {
"code": "USD",
"decimals": 2
},
"amount": 3000
},
"to": {
"withdrawal_method": 1,
"withdrawal_method_info": {
"blockchain_address": "0:cc98aec4730127..."
},
"currency": {
"code": "TON",
"decimals": 6
},
"amount": 312237799
},
"currency_rate": 10,
"status_url": "https://pay.itez.com/status/ccb862f4-4a91-4840-98fd-302cb7282f46"
},
"partner_info": {
"operation_id": "4af49ebd-...",
"token": "1a13dc56-..."
},
"customer_info": {
"id": 115372,
"account": "[email protected]",
"country": {
"code": "IT",
"name": "Italy"
}
}
},
"signature": "b3a9071f6e4292ec..."
}
Parameter | Type | Description |
---|---|---|
operation_data | object | Оperation data. |
signature | string | Sign. |
Operation confirmation
https://api.itez.com/api/partner/params/confirm
POST https://api.itez.com/api/partner/params/confirm
Request
// Request exsample
{
"partner_operation_id":"7076b531-...",
"partner_token":"c0aaee39-...",
"timestamp":1661164641882,
"signature":"6c5f9a8e63a9e4e18b..."
}
Parameter | Type | Description |
---|---|---|
partner_operation_id | string | Opertaion ID at partners system. |
operation_id | string | Opertaion ID at Itez system. |
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
No data. You can check the HTTP response code.
Operation cancellation
https://api.itez.com/api/partner/params/cancel
POST https://api.itez.com/api/partner/params/cancel
Request
// Request exsample
{
"partner_operation_id":"7076b531-...",
"partner_token":"c0aaee39-...",
"timestamp":1661164641882,
"signature":"6c5f9a8e63a9e4e18b..."
}
Parameter | Type | Description |
---|---|---|
partner_operation_id | string | Opertaion ID at partners system. |
operation_id | string | Opertaion ID at Itez system. |
partner_token | string | Itez partner token. |
timestamp | number | Current time. |
signature | string | Sign. |
Response
No data. You can check the HTTP response code.
API parameters
API response signature
// NodeJS example
const { createHmac } = require('crypto');
const flat = require('flat');
// Itez Secret must be issued by Itez support.
const itez_secret = '';
const jsonToString = (obj) => {
obj = JSON.parse(JSON.stringify(obj));
return Object
.entries(flat(obj, {
delimiter: ':'
}))
.sort()
.map(items => {
let val = items[1];
if (val === true) val = 1;
else if (val === false) val = 0;
return `${items[0]}:${val}`;
})
.join(';');
}
// Check signature
// data - response JSON-object signed by "signature" field
function checkSignature(data) {
let data_copy = Object.assign({}, data);
delete data_copy.signature;
return (
data.signature ===
createHmac('sha512', itez_secret)
.update(jsonToString(data_copy))
.digest('hex')
);
}
// Flat implementation example. Removes nesting.
function flat(obj) {
const flat_r = (res, key, val, p = '') => {
const prefix = [p, key].filter((v) => v).join(':');
return typeof val === 'object'
? Object.keys(val).reduce(
(prev, curr) => flat_r(prev, curr, val[curr], prefix),
res
)
: Object.assign(res, { [prefix]: val });
};
return Object.keys(obj).reduce(
(prev, curr) => flat_r(prev, curr, obj[curr]),
{}
);
}
Signature is a string based on the remaining parameters and Itez Secret. Signature field is not use in signature creation.
JSON object signing algorithm
This algorithm is a more general version of the widget options signing algorithm. It can be used to sign widget options.
- Strings must be encoded in UTF-8. Convert the data if the encoding is different from UTF-8.
- Remove nesting.
- All parameters from nested objects and arrays are moved to the root object. Change the names of such parameters. The parameter name is the path of this parameter. The colon ":" is used as a separator.
- Array elements are written in separate lines, indicating the number of each element, starting from zero. In the example countries.
- Empty arrays are completely ignored and not included in the lineset.
- Parameters with zero and empty values remain in the string. Replacing empty values with spaces or null is not allowed. In the example empty_value.
- Sort parameters alphabetically(ordinal).
- Convert boolean parameter values. False is replaced by 0, true by 1. In the example disabled. Warning: this only for boolean values: string parameters (if they contain the values false or true) do not change! In the example bool_str.
- Concatenate parameters into a string. Semicolon is used as separator ";". In the concatenation does not add commas between parameters, and removes quotes around parameter values and names.
- Calculate the HMAC of this string with SHA-512 hash and Itez Secret as key.
- Convert encoding result to HEX string.
Data | Removed nesting | Sorting |
---|---|---|
{ "disabled": false, "bool_str": "false", "empty_value": "", "status": "success", "from": { "method": 1, "currency": { "code": "USD", "decimals": 2, } }, "countries": [ { "code": 10001, "name": "Abhazia" }, { "code": 372, "name": "Ireland" }, { "code": 833, "name": "Isle of Man", } ] } |
{ "disabled": false, "bool_str": "false", "empty_value": "", "status": "success", "from:method": 1, "from:currency:code": "USD", "from:currency:decimals": 2, "countries:0:code": 10001, "countries:0:name": "Abhazia", "countries:1:code": 372, "countries:1:name": "Ireland", "countries:2:code": 833, "countries:2:name": "Isle of Man" } |
{ "bool_str": "false", "countries:0:code": 10001, "countries:0:name": "Abhazia", "countries:1:code": 372, "countries:1:name": "Ireland", "countries:2:code": 833, "countries:2:name": "Isle of Man", "disabled": false, "empty_value": "", "from:currency:code": "USD", "from:currency:decimals": 2, "from:method": 1, "status": "success" } |
Combining parameters into a string, converted boolean values, removed quotes and commas |
---|
bool_str:false;countries:0:code:10001;countries:0:name:Abhazia;countries:1:code:372;countries:1:name:Ireland;countries:2:code:833;countries:2:name:Isle of Man;disabled:0;empty_value:;from:currency:code:USD;from:currency:decimals:2;from:method:1;status:success |
Result. HMAC(SHA-512) calculated, result converted to HEX string |
---|
07e11c5e76314dd8647dc85248a0ecf43bc91140af27a23ba88fd37f4a29acc7cf0507ecae7be1a1a94f64e04cff24a204228e564ca1ed844d87e799d817dc43 |
Current time
// Get current time
const timestamp = Date.now();
Timestamp - Current time. Number of milliseconds since January 1, 1970 00:00:00 по UTC.
The difference between timestamp and real time is allowed no more than 30 seconds up and 5 seconds down.
Operation data
{
"operation_data":
{
"status": "success",
"status_code": 0,
"operation_info":
{
"id": "f4cef8f5-8bab-...",
"created_at": "2020-07-21T11:45:01.235259",
"paid_at": "2020-07-21T11:55:17",
"from":
{
"payment_method": 1,
"payment_method_info":
{
"number": "535175******1234",
"type": "mastercard",
"card_holder": "CUSTOMER NAME",
"expiry_month": "02",
"expiry_year": "2025",
"country":
{
"code": "RO",
"name": "Romania"
}
},
"currency":
{
"code": "EUR",
"decimals": 2
},
"amount": 3000
},
"to":
{
"withdrawal_method": 1,
"withdrawal_method_info":
{
"blockchain_address": "tb1q20gz7d35k...",
"blockchain_tx_id": "1baa1bf5962b570d...",
"blockchain_explorer_url": "https://blockchair.com/bitcoin/transaction/1baa1bf5962b570d69f7..."
},
"currency":
{
"code": "BTC",
"decimals": 8
},
"amount": 348372
},
"currency_rate": 861148,
"status_url": "https://pay.itez.com/status/f4cef8f5-..."
},
"partner_info":
{
"operation_id": "partnerOperationId",
"token": "dddaf979-fe4c-46fb-934c-f052900a0abe",
"fee_info":
{
"withdrawal_method": 1,
"withdrawal_method_info":
{
"blockchain_address": "tb1qglzn75m0d...",
"blockchain_tx_id": "1baa1bf5962b570...",
"blockchain_explorer_url": "https://blockchair.com/bitcoin/transaction/1baa1bf5962b57..."
},
"currency":
{
"code": "BTC",
"decimals": 8
},
"amount": 3657
}
},
"customer_info":
{
"id": 6,
"account": "[email protected]",
"country":
{
"code": "RO",
"name": "Romania"
}
}
},
"signature": "c1e5256c0636c2..."
}
Operation_data - an object containing data about the operation. It can be received in callbacks or some event handlers. It is an input parameter in event handlers: onOperationSuccess, onOperationPending, onOperationFail.
Description
- status - string. Operation status.
- status_code - number. Operation status code.
- operation_info - object
- id - string. Operation ID.
- created_at - string. Creation date/time of the operation.
- paid_at - string. Date/time of paid.
- from - object
- payment_method - number. Payment type, values: 1 - cash.
- payment_method_info - object
- number - string. User's bank masked card number.
- type - string. Type of a bank card.
- card_holder - string. Cardholder name.
- expiry_month - string. Card expiry month.
- expiry_year - string. Card expiry year.
- country - object
- code - string. Users bank card country code.
- name - string. Full country name of users bank card.
- currency - object
- code - string. Currency code.
- decimals - number. Number of decimal.
- amount - number. Transaction amount in a specified currency.
- to - object
- withdrawal_method - number. Withdrawal method.
- withdrawal_method_info - object
- blockchain_address - string. Users bitcoin wallet address.
- blockchain_tx_id - string. Transaction ID.
- blockchain_explorer_url - string. Blockchain explorer url.
- currency - object
- code - string. Currency code.
- decimals - number. Number of decimal.
- amount - number. Transaction amount in a specified currency.
- currency_rate - number. Transaction rate.
- status_url - string. ITEZ status url.
- partner_info - object
- operation_id - string. Operation ID.
- token - string. Operation token.
- fee_info - object
- withdrawal_method - Withdrawal type, values: 1 - cash.
- withdrawal_method_info - object
- blockchain_address - string. Partner bitcoin wallet address
- blockchain_tx_id - string. Transaction ID
- blockchain_explorer_url - string. Blockchain explorer url
- currency - object
- code - string. Currency code.
- decimals - Number of decimal.
- amount - Transaction amount in specified currency.
- customer_info - object
- account - string. User email.
- country - object
- code - string. Users bank card country code.
- name - string. Full country name of users bank card.
Status
Status | Description |
---|---|
success | Blockchain transaction were created |
pending | Funds were debited with the client's card |
declined | Cancellation |
awaiting confirm | Pending partner confirmation |
Status code
Status code | Description |
---|---|
0 | Complete. Withdrawal transaction completed |
1 | Created. The operation has just been created |
2 | Received money from the user |
3 | User verified |
4 | Order executed on the exchange |
6 | Withdrawal transaction created |
7 | Withdrawal request created |
8 | Waiting for partner confirmation |
9 | Verified by partner |
101 | Refused payment |
102 | User opt out. Declined by customer. Causes: timeout, payment was not finalized, user goes back via page navigation. Bank card data have not reached itez payment processor. |
103 | User failed verification |
104 | User's bank card failed verification |
105 | Rate hold time expired |
106 | Cancellation by the partner |
API errors
HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8
Wrong signature
HTTP/1.1 200 OK
Content-Type: application/json
{
"service_fee": 0.05,
"signature": "..."
}
If the response code is not "200 OK", the body contains the error description.
Possible error codes:
Code | Description |
---|---|
400 Bad Request | Invalid request parameters. |
401 Unauthorized | Wrong signature. |
403 Forbidden | Partner blocked. |
404 Not Found | Partner not found. |
429 Too Many Requests | Too many requests. |
500 Internal Server Error | Request processing error. |
Callbacks
When a operation is created our system sends you a callback with information about the last operation status.
Method
Callback is a HTTP POST request in JSON format sent to your system (to the provided URL) after processing the operation. Callbacks are signed, for more information read Signature
Conditions for sending callbacks
We sends callbacks in the following cases:
- Payment system refuse in accepting payment
- Pending partner confirmation (sent in case of an operation requiring partner approval by auth)
- Operation cancellation by the partner
- Funds were debited with the client's card
- Blockchain withdrawal transaction were created
Callback delivery
We record the fact of callback delivery to your system after receiving the response from your system. The response must contain HTTP header with code 200 OK
If the callback was not delivered it is resent according to the following schedule:
- 6 times with the 10 sec. period;
- then the period is increased in accordance with the formula 70 + 10·1,12n-4, where n is the serial number of the attempt, until the period does not exceed 4 hours;
- after that, every 4 hours until the maximum number of attempts is achieved (maximum 120 attempts to deliver a callback within 11 days).
Callback delivery addresses
Callbacks are sent to URLs that are unique for each partner. URL setting up with the ITEZ support service.
Callback processing
When processing callbacks your system must follow these rules:
- Accept callbacks only from the IP address received from the ITEZ support service.
- On a successfully received callback, your system must respond with HTTP 200 OK.
- If a callback has been already received by your system, your system must respond with HTTP 200 OK also.
- If a callback was not received your system must respond with HTTP 400 Bad Request (for example, if you were unable to convert a parameter string to an array) or HTTP 500 Internal Server
- Error (for example, if a callback was sent to the wrong URL).
- For reminders that were not previously received, your system must try to accept the callback again.
- Your system should not limit the delivery time for callbacks, because deliveries can occur with delays.
CMS integration
WordPress
WooCommerce Payment Method
Using WooCommerce you can accept payment for orders in BTC.
To do this just install a ready-made plugin that adds a new payment method and make the necessary settings.
You can download the plugin at this link.
Installation:
- Go to console (web-site admin panel)
- Click "Plugins", select "Add new"
- Press the "Load plugin" button (at the top of the screen) and select the previously downloaded plugin file
- Press the "Install" button
- Press the "Activate" button
Setting up the payment method:
- Go to "WooCommerce" -> "Settings" -> "Payments"
- Click on the "Itez Pay" method
- In the section that opens, you will see the following fields:
- Enable / Disable - a checkbox that activates or deactivates the payment method
- Title - the name of the payment method that the user will see when choosing payment methods in the checkout
- Description - a description of the payment method that the user will see when choosing payment methods in the checkout
- BTC wallet address - your BTC wallet, where funds from buyers will be received
- Store currency - the currency in which the user will pay
- Itez Secret (Key) - unique partner key, you must request from Itez technical support
- Partner Token - partner token, you must request from Itez technical support
After making changes, they must be saved by clicking on the appropriate button below the fields.
Widget plugin
The plugin allows you to quickly and easily embed the Itez widget anywhere on your WordPress site. You can download the plugin at this link.
Installation:
- Go to console (site admin panel)
- Press "Plugins", select "Add new"
- Press the "Load plugin" button (at the top of the screen) and select the previously downloaded file with the plugin
- Press the "Install" button
- Press the "Activate" button
Adding to the widget area:
- Go to "Appearance" -> "Widgets"
- Select the "Itez WIdget" widget and drag it to the desired widget area
- The following fields are available in the widget settings:
- Title - the title of the widget
- Itez Partner token and secret key in the Itez system, you need to get it from Itez technical support
- Standard amount - the amount entered in the widget by default
- Currency from - the default fiat currency
- Currency to - the default crypto currency
Landing
You can use the Itez payment widget on your landing page. To create a landing page, please contact your personal presence or Itez support.
Widget parameters and redirect URLs when widget complete can be passed to the page.
Switching to a landing page without parameters is allowed. The widget is initialized the required parameters only, in this case.
Widget parameters
// Example of the JSON with initial landing parameters
{
"params": {
"partner_token": "...",
"target_element": "widget-container",
"timestamp": 1604047440000,
"from_currency": "USD",
"from_amount": 30000,
"partner_operation_id": "12345",
"signature": "..."
},
"callbacks": {
"success": "https://itez.com/?success",
"fail": "https://itez.com/?fail"
}
}
Widget parameters must be passed in the params object. Its description you can find here.
Redirect
You can set the redirect URL for some events. In the callback object, you can specify the redirect URLs in the following fields:
- success - redirect in case of successful completion of the purchase. Corresponds to the onOperationSuccess event.
- fail - redirect in case of failure completion of the purchase. Corresponds to the onOperationFail event.
Forming a GET request
// Example of forming a GET request
const data = {
params:{...},
calbacks:{...}
}
const url = 'https://buy.itez.com/?i=' +
Buffer.from(JSON.stringify(data)).toString('base64');
JSON with parameters must be converted to base64 and passed as a GET parameter i.
https://buy.itez.com/?i=ewogICAgInBhcmFtcyI6IHsKICAgICAgICAicGFydG5lcl90b2tlbiI6ICIyOWE0OGY0MC03ZGY3LTQ5ZDMtODMwZS1iZTY4NGQ3Yjg4NjEiLAogICAgICAgICJ0YXJnZXRfZWxlbWVudCI6ICJ3aWRnZXQtY29udGFpbmVyIiwKICAgICAgICAidGltZXN0YW1wIjogMTYwNDA0NzQ0MCwKICAgICAgICAiZnJvbV9jdXJyZW5jeSI6ICJVU0QiLAogICAgICAgICJmcm9tX2Ftb3VudCI6IDMwMDAwLAogICAgICAgICJwYXJ0bmVyX29wZXJhdGlvbl9pZCI6IDEyMzQ1LAogICAgICAgICJzaWduYXR1cmUiOiAiMzZkMTFkZWUwYmU5ZDIwM2RkNTBkZWU1MWQ0YTI4YjEwOTgzZmUwMTU0ZmI5OWMwMzM2ZjI0OTZmMDg3NDk4Mzc0OTFjZGQ5OWM2ZWI5Y2E0YzY0NDQ0NzliZDcxOGFlMjQxNzQ5NmMwNTA4NGRhNzFmYjljYTcxYTQ1NDVlMjciCiAgICB9LAogICAgImNhbGxiYWNrcyI6IHsKICAgICAgICAic3VjY2VzcyI6ICJodHRwczovL2l0ZXouY29tLz9zdWNjZXNzIiwKICAgICAgICAiZmFpbCI6ICJodHRwczovL2l0ZXouY29tLz9mYWlsIgogICAgfQp8Cg== |
Widget customisation
To make the payment widget looks better with your design we have provided the ability to customize the color of some elements of the widget interface.
What design elements can be changed?
- primaryFill – large buttons, back arrow, cross, links, chosen line in currency combobox. Default value #6a42e9.
- primaryText – amount, currency short name, menu button, menu items, window’s name. Default value #28334e.
- secondaryText – field’s names, placeholders, additional text, currency’s names. Default value #a2a9b9.
- formStrokeColor – border’s color. default #e6e6eb. On the picture #aa0000(red).
- backgroundColor – background color. Default value #ffffff.
- successColor – color of verification status icon (tier2). Default value #00d2a8.
- warningColor – color of session timeout icon. Default value #df3e6f.
- boxShadow – widget shadow, edit shadow. Default value - rgba(40, 51, 78, 0.3). on picture rgba(0, 100, 0, 0.7)(green). We recommend to set field values as RGBA to set transparency.
How it works?
// CSS example
.widgetColor {
--primaryFill: #6a42e9;
--primaryText: #28334e;
--secondaryText: #a2a9b9;
--successColor: #00d2a8;
--warningColor: #df3e6f;
--backgroundColor: #ffffff;
--formStrokeColor: #e6e6eb;
--boxShadow: rgba(40, 51, 78, 0.3);
}
You should create a css-file for defining colors of the elements, and include it using partner_css parameter. In partner_css you can specify css-file location. Widget colors are specified in the widgetColor. Undefined field’s values are set by default. If partner_css is not set or unaccessible, field’s values are set by default.
Partner.Itez.com
How to get access to Partner.Itez.com
In this tutorial, we will tell you how to get access to partner.itez.com.
Go to itez.com and enter "BUY".
Enter your email in the following window.
Verify your email with a 6-digit code.
You need to click here.
And to click "Verify identity".
Create and set a new password.
It’s done! Now you can enter partner.itez.com using this email and password.
Supported assets and currencies
Supported payment methods
- Visa
- Maestro
- MasterCard
- SEPA
Currency List
Currency | Symbol | Sum (min) | Sum (max) |
---|---|---|---|
Argentine peso | ARS | 10300 | 1400000 |
Dollar US | USD | 50 | 5000 |
Euro | EUR | 50 | 5000 |
Ukrainian hryvnia | UAH | 2000 | 150000 |
Indian rupee | INR | 5000 | 400000 |
British pound | GBP | 50 | 5000 |
South Korean won | KRW | 100000 | 20000000 |
Kazakhstani tenge | KZT | 40000 | 2000000 |
Australian dollar | AUD | 100 | 10000 |
Brazilian Real | BRL | 500 | 20000 |
Hong Kong dollar | HKD | 500 | 500000 |
Taiwan dollar | TWD | 2000 | 150000 |
Armenian dram | AMD | 50000 | 3000000 |
Polish zloty | PLN | 300 | 20000 |
Singapore dollar | SGD | 100 | 5000 |
Vietnamese dong | VND | 2000000 | 150000000 |
Swedish krona | SEK | 500 | 50000 |
Moldovan leu | MDL | 1000 | 100000 |
Azerbaijani manat | AZN | 150 | 10000 |
Canadian dollar | CAD | 100 | 6000 |
Danish krone | DKK | 500 | 30000 |
Norwegian krone | NOK | 600 | 45000 |
Hungarian forint | HUF | 20000 | 1500000 |
Croatian Kuna | HRK | 500 | 30000 |
Romanian leu | RON | 300 | 20000 |
Czech crown | CZK | 1500 | 100000 |
Bulgarian lev | BGN | 150 | 9000 |
Israeli shekel | ILS | 200 | 15000 |
Bahraini dinar | BHD | 30 | 2000 |
New Zealand dollar | NZD | 100 | 8000 |
Malaysian ringgit | MYR | 250 | 20000 |
South Korean Won | KRW | 100000 | 20000000 |
Cryptocurrency List
Asset | Chain | Symbol |
---|---|---|
BTC | Bitcoin | BTC |
BNB | Binance Smart Chain | BNB |
USDT | Binance Smart Chain | BEP20USDT |
BUSD | Binance Smart Chain | BEP20BUSD |
GMT | Binance Smart Chain | BEP20GMT |
ETH | Ethereum | ETH |
USDT | Ethereum | USDT |
GMT | Ethereum | ERC20GMT2 |
USDT | Everscale | EVERTIP3USDT |
EVER | Everscale | TON |
NEAR | Near | NEAR |
BOB | Polygon | PERC20BOB |
MATIC | Polygon | MATIC |
TON | Ton | TONCOIN |
USDC | Tron | TRC20USDC |
USDT | Tron | TRC20USDT |
TRX | Tron | TRX |
Disclaimer of the ITEZ Widget (hereinafter - the Widget) software copyright owner
The Widget is a software, the copyright holder of which is Beamloop UAB, Lithuania (company registration number: 306029168) - hereinafter the Copyright Holder. The Copyright Holder transfers a non-exclusive royalty free license to a legal entity with which the Copyright Holder enters into a service contract - hereinafter the Widget User. The Widget User implements (installs) the Widget (performs integration on a Website, downloads, copies the installation files and data, receives integration tokens from the Copyright Holder) and through that Website organizes interaction of the Website users with the Widget, including internal links and integrations with third- parties software owned by another copyright holders.
Installation of the Widget, as well as access of Website users to the Widget is carried out at the own discretion and risks of the Widget user. The Widget User relieves the Copyright Holder of any responsibility for the entire time of interaction with the Widget and until it is deleted.
The Widget User is solely responsible for backing up any data and adequate protection of any equipment used to interact with the Widget and the Copyright Holder is not responsible for any losses the Widget User or the Website User's site user may incur in connection with downloading, installing, using, modifying or distributing the Widget, including for any damage to any computer system and loss of any data. No advice or information, oral or written, received from the Copyright Holder or its employees or contractors, does not represent any warranty of technical functionality or correct performance of the Widget.
The Widget and its components shall be supplied by the Copyright Holder of the Widget on an "as is" principals and without any warranties, either express or implied.
In addition to above-mentioned, the Copyright Holder does not give any guarantees that:
- The Widget, its components and third-party software will be compatible and meet technical requirements of the Widget User.
- Widget or the third-party software shall be integrated and (supplied) secure or error-free.
- The results of the use of third-party software, built-in or with which interaction is carried out during the operation of the Widget, will be effective, accurate, reliable and in line with any expectations of the Widget user or Website users.
- The quality of the Widget will meet any expectations.
- The Widget does not contain technical or other errors, inaccuracies or typographical errors.
At any time, without prior notice, the Copyright Holder shall make changes to the Widget or its components, links to third-party software or documentation available on Widget user’s or third-party website.
The software may be out of date and the Copyright holder is under no obligation to update any outdated material.
The user bears the risk for special, punitive, incidental, consequential damages of any kind or any damages in general, including but not limited to those arising from loss of use, loss of data and (or) profit, including any liabilities arising from or in connection with the use of the Widget.