NAV
JS PHP

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.

Website
WordPress
Landing

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>
...
  1. Include https://pay.itez.com/static/main/share/merchant.js
  2. 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 -<div id="widget-container"></div>.
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:

  1. 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.
  2. Strings are sorted alphabetically(ordinal).
  3. Sorted lines are joined into one line with a delimiter ";".
  4. 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).
  5. The resulting binary code is converted to a HEX-string.
  6. 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:

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.

  1. Strings must be encoded in UTF-8. Convert the data if the encoding is different from UTF-8.
  2. 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.
  3. Sort parameters alphabetically(ordinal).
  4. 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.
  5. 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.
  6. Calculate the HMAC of this string with SHA-512 hash and Itez Secret as key.
  7. Convert encoding result to HEX string.

DataRemoved nestingSorting
{
 "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

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:

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:

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:

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:

  1. Go to console (web-site admin panel)
  2. Click "Plugins", select "Add new"
  3. Press the "Load plugin" button (at the top of the screen) and select the previously downloaded plugin file
  4. Press the "Install" button
  5. Press the "Activate" button

Setting up the payment method:

  1. Go to "WooCommerce" -> "Settings" -> "Payments"
  2. 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:

  1. Go to console (site admin panel)
  2. Press "Plugins", select "Add new"
  3. Press the "Load plugin" button (at the top of the screen) and select the previously downloaded file with the plugin
  4. Press the "Install" button
  5. Press the "Activate" button

Adding to the widget area:

  1. Go to "Appearance" -> "Widgets"
  2. Select the "Itez WIdget" widget and drag it to the desired widget area
  3. 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:

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?

Primary fill

Primary text

Secondary text

Form stroke color

Box shadow

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

Currency List

Currency Symbol Sum (min) Sum (max)
Argentine peso ARS 10300 1400000
Armenian dram AMD 50000 3000000
Australian dollar AUD 100 10000
Azerbaijani manat AZN 150 10000
Bahraini dinar BHD 30 2000
Bulgarian lev BGN 150 9000
Brazilian Real BRL 500 20000
Canadian dollar CAD 100 6000
Czech koruna CZK 1500 100000
Danish krone DKK 500 30000
Euro EUR 50 5000
Hong Kong dollar HKD 500 500000
Hungarian forint HUF 12000 1800000
Israeli new shekel ILS 200 15000
Indian rupee INR 5000 400000
Kazakhstani tenge KZT 40000 2000000
Malaysian ringgit MYR 250 20000
Moldovan leu MDL 1000 100000
New Taiwan dollar TWD 2000 150000
Norwegian krone NOK 600 45000
New Zealand dollar NZD 100 8000
Polish zloty PLN 300 20000
Pound sterling GBP 50 5000
Romanian leu RON 300 20000
Saudi riyal SAR 150 20000
South Korean Won KRW 100000 20000000
Swedish krona SEK 500 50000
Swiss franc CHF 40 4800
Turkish lira TRY 600 150000
Ukrainian hryvnia UAH 2000 150000
Dollar US USD 50 5000
Vietnamese dong VND 2000000 150000000

Cryptocurrency List

Asset Chain Symbol
BTC Bitcoin BTC
Binance Coin Binance Smart Chain BNB
Tether USD Binance Smart Chain BEP20USDT
GoMining Token Binance Smart Chain BEP20GMT
USDT Everscale EVERTIP3USDT
Everscale Everscale TON
NEAR Near NEAR
BOB Polygon PERC20BOB
Matic Polygon MATIC
Toncoin TON TONCOIN
USD Coin TRON TRC20USDC
Tether USD TRON TRC20USDT
TRX TRON TRX
Ether Ethereum ETH
Tether USD Ethereum USDT
GoMining Token Ethereum ERC20GMT2
XCAD Network Ethereum 1E37B77-E0F5-4023-A98E-03156595A80B
Dai Stablecoin Ethereum 437102F1-80DA-475E-A033-E79A40E3E8A5
Euro Tether Ethereum F64F07D7-638C-497D-939C-833CF9024732
Bancor Ethereum 890BBA7A-0690-4A58-B831-CC55BF2CB90F
Curve DAO Token Ethereum 6FA79730-4DBB-4EE6-BC88-C8E5123CECAA
Merit Circle Ethereum FC1D920C-4C0F-49C6-89A9-D8F78CD48991
Yield Guild Games Ethereum 056075bf-715f-4174-b841-e9a77c18328e
Injective Ethereum 74a1df38-605d-46bc-9d4f-6af2e692add4
Render Ethereum 29391308-09b9-466e-a368-cac98942b3f2
Phala Network Ethereum edea2b7a-0032-4730-90b4-04b6c6ec5a3c
blur Ethereum 9ab09e1b-71e9-4fdc-8f98-a294733c0f44

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:

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.