Инструкция по подключению API для разработчиков
- Получите ключ API в нашей системе в разделе «Настройки». Регистрация занимает около 5 секунд, предварительная модерация магазина не требуется. Mitilena Pay работает по некастодиальной схеме (non-custodial): платежи поступают напрямую от покупателя на ваш собственный адрес кошелька.
- Когда покупатель оформляет заказ в вашем интернет-магазине и известна итоговая сумма заказа, ваш сервер формирует JSON-объект и отправляет его POST-запросом на наш сервер.
- Мы регистрируем заявку на оплату и в ответе возвращаем внутренний номер счёта (
invoiceId) и ссылку на страницу оплаты (paymentPage). - Вы перенаправляете покупателя на полученную страницу оплаты, он производит оплату в блокчейне и автоматически возвращается обратно на ваш сайт (
redirectUrl_yours). - Наш сервер отправляет скрытый POST-запрос (вебхук) на указанный вами адрес (
webHookPostUrl_yours) и сообщает, что заказ оплачен. Ваш обработчик проверяет секретный ключ и переводит заказ в базе данных в статус оплаченного.
Если ваш интернет-магазин работает на WordPress (WooCommerce), программировать ничего не нужно — у нас есть готовый плагин для приёма криптовалюты: перейдите по ссылке к инструкции и скачиванию плагина.
Описание API:
Шаг 2. Создание объекта JSON (пример на JavaScript).
Возможные значения для поля blockchain — укажите строку из кавычек (например, tether-trc20):
'tether-erc20' (ERC20 Ethereum USDT, contract: 0xdac17f958d2ee523a2206206994597c13d831ec7)
'tether-bep20' (BEP20 Binance smart chain USDT, contract: 0x55d398326f99059ff775485246999027b3197955)
'tether-trc20' (TRC20 Tron USDT, contract: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)
'bitcoin' (Bitcoin native, BTC)
'mitilena-own' (Vanishing Mitilena, VMT token)
'apfcoin' (ERC20 Ethereum APFC, contract: 0x8eD955a2b7d2C3a17a9d05dACa95E01818f8C11e)
'verdan-token-bep20' (BEP20 Binance smart chain VERDT, contract: 0x2ea26d54ba80fe908621428ed7d4aa42ca9b81b5)
Важно (Холодный кошелёк / Non-Custodial): Все платежи идут напрямую на ваш собственный кошелёк. Вы обязаны передать параметр receiveAddress с вашим адресом кошелька, соответствующим выбранной сети blockchain (например, ваш Tron-адрес T... для tether-trc20, ваш адрес 0x... для tether-bep20 / tether-erc20 / apfcoin / verdan-token-bep20 или ваш Bitcoin-адрес для bitcoin).
let createPaymentObj =
{
userSecret: 'your_API_key', // required
userPaymentId: 'your_payment_id_usually_order_id', // required
blockchain: 'tether-trc20', // required
receiveAddress: 'your_wallet_address_for_selected_blockchain', // required (non-custodial: payments go directly to your wallet)
fiatCode: '3x_ISO_code_of_your_fiat_currency_for example_EUR', // required
customerEmail: 'customer_mail', // required
fiatAmount: 'digit_amount_in_fiat_currency_for_example_100', // number, required
userProductId: 'your_product_id_if_any', // not required
language: 'two_digit_ISO_language_code', // default en, not required [available: en, cz, ru, fr, de, zh, tr, my, hr, si, ar, swa]
// redirectUrl_yours: 'thank_you_page or success_page',
redirectUrl_yours: 'url_on_your_site_where_to_send_user_after_successful_payment', // not required, but very desirable
webHookPostUrl_yours: 'url_on_your_site_where_the_hidden_POST_request_will_go_on_successful_payment' // required, clean URL path without query string (?param=...)
}
В заголовках (headers) запроса также необходимо передать ваш API-ключ в поле 'mitilena-signature': 'your_api_key':
Выглядит это следующим образом:
headers: {
'Content-Type': 'application/json',
accept: 'application/json',
'mitilena-signature': 'your_key',
}
Отправьте запрос методом POST по адресу:
https://mitilena.com/api/generatePayment
Если счёт успешно создан, сервер вернёт код 200 и JSON-объект следующего вида:
Из этого ответа вам нужны только 2 поля: invoiceId и paymentPage. Вы должны перенаправить (redirect) пользователя на страницу оплаты Mitilena Pay из поля [paymentPage]!
Примечание: если вы передаёте код языка в поле language (например, 'cz', 'de', 'fr', 'ru'), возвращаемый URL в поле paymentPage будет содержать соответствующий языковой поддомен (например, https://ru.mitilena.com/pay/.../fast/). Если ваш код проверяет хост ссылки paymentPage, разрешите как mitilena.com, так и *.mitilena.com.
{
usdtOverAmount: '1.580437',
invoiceId: 'auto-e80099-ef456c-e0de42',
invoiceVs: '0437',
fiatAmount: '1.450',
fiatCurrency: 'EUR',
rateLocalCurrencyToNeededCrypto: '0.917',
rateNeededCryptoToUSD: '0.99959700',
isTrc20: 1,
isErc20: 0,
isBep20: 0,
whenInit: '2023-08-22T11:30:05.000Z',
contractAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
customerEmail: 'email_customer@email.com',
productId: 85,
expiresAt: '2023-09-05T11:30:05.000Z',
blockchainHash: null,
cryptoShortCode: 'USDT',
cryptoValue: '1.580437',
fiatValue: '1.450',
receivedOnAddress: 'TRHpcBugcdEdD6BdW6k1Grtof6LBvRGWWJ',
txId: 'auto-e80099-ef456c-e0de42',
fiatShortCode: 'EUR',
wasPaid: null,
redirectUrl: 'https://google.com',
paymentPage: 'https://mitilena.com/pay/auto-e80099-ef456c-e0de42/fast/' // or https://<lang>.mitilena.com/pay/.../fast/
}
В случае ошибки сервер вернёт статус 400 и текстовую строку с описанием ошибки.
Срок действия созданной ссылки на оплату — 14 дней.
Пример запроса на JavaScript (Node.js 16.8+):
const https = require('https');
const url = require('url');
const data = JSON.stringify({
userSecret: '',
userPaymentId: 'userPaymentdId111',
blockchain: 'tether-trc20',
receiveAddress: 'TRHpcBugcdEdD6BdW6k1Grtof6LBvRGWWJ', // your wallet address
fiatCode: 'EUR',
customerEmail: 'email_customer@email.com',
fiatAmount: 1.45,
userProductId: 'new_someGoodsOk',
language: 'en', // default en, not neccessary
// redirectUrl_yours: 'https://google.com',
redirectUrl_yours: 'https://google.com',
webHookPostUrl_yours: 'https://mitilena.com/mi_webhook/'
});
const myURL = url.parse('https://mitilena.com/api/generatePayment');
const options = {
hostname: myURL.hostname,
port: myURL.port,
path: myURL.pathname,
method: 'POST',
headers: {
'Content-Type': 'application/json',
accept: 'application/json',
'mitilena-signature': '',
},
};
requestAsync(options, data)
.then(dataFObj => {
if (dataFObj.statusCode === 200) {
let tokensObj = JSON.parse(dataFObj.dataRaw);
console.log('success:', tokensObj)
} else {
console.log('error dataFObj', dataFObj);
throw new Error('some errror in postToWebHook ' + dataFObj.dataRaw);
}
})
.catch(e => {
console.log('error request:', e)
})
function requestAsync(optionsArr, dataToPost = false) {
return new Promise((resolve, reject) => {
const req = https.request(optionsArr, (resp) => {
// console.log(`statusCode: ${resp.statusCode}`);
let dataF = '';
// A chunk of data has been received.
resp.on('data', (chunk) => {
dataF += chunk;
});
resp.on('end', () => {
resolve({statusCode: resp.statusCode, dataRaw: dataF});
}).on('error', (err) => {
console.log('Error: ' + err);
reject(err);
});
});
if (dataToPost) {
req.write(dataToPost);
}
req.end();
});
}
В версиях Node.js выше 16 модуль url можно заменить на стандартный класс new URL(...) или передать хост и путь вручную.
Пример запроса на PHP и WordPress:
Отправка запроса через функцию WordPress wp_remote_post():
<?php
$request_body = [
'userSecret' => $this->mitilenaToken,
'userPaymentId' => $order->id,
'blockchain' => 'tether-trc20',
'receiveAddress' => 'TRHpcBugcdEdD6BdW6k1Grtof6LBvRGWWJ', // your wallet address for this blockchain
'fiatCode' => $order->currency,
'customerEmail' => $order->get_billing_email(),
'fiatAmount' => $order->get_total(),
'userProductId' => $orderids,
'language' => 'en', // default en, not neccessary
'redirectUrl_yours' => $order->get_checkout_order_received_url(),
'webHookPostUrl_yours' => 'https://mywebsite.com/post-handler.php'
];
$request_headers = [
'content-type' => 'application/json',
'mitilena-signature' => $this->mitilenaToken,
];
$args = [
'method' => 'POST',
'httpversion' => '1.0',
'timeout' => 90,
'headers' => $request_headers,
'body' => ''
];
$environment_url = 'https://mitilena.com/api/generatePayment/';
$result = wp_remote_post($environment_url, array(
'method' => 'POST',
'headers' => $request_headers,
'timeout' => 60, // added
'redirection' => 5, // added
'blocking' => true, // added
'httpversion' => '1.0',
'sslverify' => false,
'body' => json_encode($request_body))
);
$fullObj = json_decode($result['body']);
if (isset($result['response']) && isset($result['response']['code']) && $result['response']['code'] != 200) {
$mi__err_message = 'Unknown error';
if (isset($result['body'])) {
$mi__err_message = 'Error: ' . $result['body'];
}
// error handling + exit
exit;
}
if (!isset($fullObj->paymentPage)) {
http_response_code(400); // Bad Request
echo "Error: No payment page specified";
exit;
}
$paymentPage = $fullObj->paymentPage;
if (strlen($paymentPage) < 5) {
http_response_code(400); // Bad Request
echo "Error: payment page is too short.";
exit;
}
?>
Шаг 5. Создание обработчика WebHook на стороне вашего сайта (сервера):
Когда оплата обнаружена в блокчейне (независимо от того, был ли счёт создан по API через POST /api/generatePayment или через форму генератора счетов на странице mitilena.com/get-payment-eshop/, где указываются Product name, Product ID и Webhook URL), наш сервер отправляет POST-запрос на ваш webhook URL с заголовком mitilena-signature: your_api_key и следующим JSON-телом:
{
statusObj: {
mitilenaInvoiceId: 'auto-683dc5-03f2c0-e3f06a', // string, never undefined
yourPaymentId: 'your_order_id', // string (order ID from API, or '' if created via /get-payment-eshop/ form), never undefined
yourProductName: 'stringOrNull', // string (Product name from /get-payment-eshop/ form), never undefined
yourProductId: 'stringOrNull', // string (Product ID from /get-payment-eshop/ form or userProductId from API), never undefined
secretKey: 'your-unique-secret-key', // string, never undefined (must match your API key!)
stableCoinAmount: 10.55, // number | string, crypto amount paid, never undefined
stableCoinSymbol: 'USDT', // string ('USDT', 'BTC', 'ETH', etc.), never undefined
stableCoinBlockchain: 'Tron', // string ('Tron', 'Ethereum', 'Binance Smart Chain (BSC)', 'tron', 'eth', 'bsc', etc.), never undefined
stableCoinContractAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // string | null
localCurrencyAmount: 10, // number, amount in your fiat currency, never undefined
localCurrencyCode: 'EUR', // ISO 4217 currency code, never undefined
wasPaid: true, // boolean true | false, never undefined
blockchainHash: '0x...' // string, transaction hash in the blockchain, never undefined
}
}
Пример обработчика на Node.js 16.8 и Express.js 4 (JavaScript):
const bodyParser = require('body-parser');
const Big = require('big.js')
let endpointSecret = 'copy of the api key value'
// an object called statusObj arrives
app.post('/mi_webhook/', bodyParser.json(), (request, response) => {
try {
let eventObj = request.body;
const signature = request.headers['mitilena-signature'];
console.log({eventObj});
// compare the incoming secret key with your real one
if (signature === endpointSecret) {
if (!eventObj.statusObj) {
return response.status(400).send('Error, no object.');
}
let hookObj = eventObj.statusObj;
if (
typeof hookObj.mitilenaInvoiceId === 'undefined' ||
typeof hookObj.yourPaymentId === 'undefined' ||
typeof hookObj.yourProductName === 'undefined' ||
typeof hookObj.yourProductId === 'undefined' ||
typeof hookObj.secretKey === 'undefined' ||
typeof hookObj.stableCoinAmount === 'undefined' ||
typeof hookObj.stableCoinSymbol === 'undefined' ||
typeof hookObj.stableCoinBlockchain === 'undefined' ||
typeof hookObj.stableCoinContractAddress === 'undefined' ||
typeof hookObj.localCurrencyAmount === 'undefined' ||
typeof hookObj.localCurrencyCode === 'undefined' ||
typeof hookObj.wasPaid === 'undefined' ||
typeof hookObj.blockchainHash === 'undefined' ||
hookObj.secretKey !== endpointSecret
) {
return response.status(400).send('Error, incomplete object.');
}
if (hookObj.wasPaid === true) {
let centsAmount = Big(hookObj.localCurrencyAmount).times(Big(100)).round(0).toNumber();
// put the order in your database as paid and return the status code 200
// this is an example of our code, yours may look different
paymentsModel
.completeUserPayment(hookObj.mitilenaInvoiceId, centsAmount)
.then((okString) => {
return response.status(200).send('all good Mitilena token');
})
.catch((e) => {
console.log('err in completeUserCardPayment', e.message);
return response.status(400).send('error, contact support');
});
} else {
return response.status(400).send('invoice was not paid');
}
} else {
return response.status(400).send('bad Mitilena token');
}
} catch (e) {
console.log('webhook err:', e.message);
return response.status(400).send('bad request, error');
}
});
Пример обработчика на PHP:
Создайте файл-обработчик на вашем веб-сервере так, чтобы он был доступен извне по HTTPS, например https://yourwebsite.com/webhook.php (или через роутинг вашего фреймворка; не добавляйте в адрес вебхука GET-параметры вида ?action=...).
Укажите этот адрес при создании счёта в поле:webHookPostUrl_yours: 'https://yourwebsite.com/webhook.php'
Содержимое файла:
<?php
$mi__jsonData = file_get_contents('php://input');
if (!$mi__jsonData) {
http_response_code(400); // Bad Request
echo 'bad input data';
exit;
}
// Decode the JSON data into a PHP associative array
$mitilena_data = json_decode($mi__jsonData, true);
// Check if decoding was successful
if ($mitilena_data !== null && isset($mitilena_data['statusObj'])) {
$mitilena_data = $mitilena_data['statusObj'];
if (!isset($mitilena_data['secretKey']) || !is_string($mitilena_data['secretKey'])) {
http_response_code(400); // Bad Request
echo "Error: Api key of Mitilena (Mitilena Token) is not specified. We can't verify if the request is genuine. Cancellation of a transaction.";
exit;
}
$mitilenaToken = $mitilena_data['secretKey'];
// compare your real API key with the one you received (always use strict comparison / hash_equals!)
$realMitilenaToken = 'your_api_key';
if (!is_string($realMitilenaToken) || !hash_equals($realMitilenaToken, $mitilenaToken)) {
http_response_code(400); // Bad Request
echo "Error: API token does not match. The website owner must specify the correct Api Mitilena token.";
exit;
}
// For API invoices, your order ID is in 'yourPaymentId'; for invoices created on mitilena.com/get-payment-eshop/, your ID is in 'yourProductId'
$mi__paymentId = '';
if (isset($mitilena_data['yourPaymentId']) && is_string($mitilena_data['yourPaymentId']) && strlen($mitilena_data['yourPaymentId']) > 0) {
$mi__paymentId = $mitilena_data['yourPaymentId'];
} elseif (isset($mitilena_data['yourProductId']) && is_string($mitilena_data['yourProductId']) && strlen($mitilena_data['yourProductId']) > 0) {
$mi__paymentId = $mitilena_data['yourProductId'];
}
if (strlen($mi__paymentId) < 1) {
http_response_code(400); // Bad Request
echo "Error: No payment id or product id specified.";
exit;
}
function mi__pay_escapeString($var)
{
$var = stripslashes($var);
$var = htmlentities($var);
$var = strip_tags($var);
return $var;
}
// yourPaymentId
try {
$mi__order = ''; // search your database for this order, mi__pay_escapeString($mi__paymentId)
} catch (Throwable $e) {
http_response_code(400); // Bad Request
echo "Error: wrong payment id (order id). {yourPaymentId: \"\"}";
exit;
}
if (!isset($mitilena_data['wasPaid'])) {
http_response_code(400); // Bad Request
echo "Error: No payment status specified";
exit;
}
$mi__wasPaid = $mitilena_data['wasPaid'];
if ($mi__wasPaid === true) {
$blockchainHash = '';
if (isset($mitilena_data['blockchainHash'])) {
$blockchainHash = mi__pay_escapeString($mitilena_data['blockchainHash']);
}
// set the order as paid in your database
// reduce inventory if required
// send the user an email if required
echo 'success';
} else {
echo 'unpaid status received';
}
} else {
// JSON decoding failed
http_response_code(400); // Bad Request
echo "Invalid JSON data";
}
exit;
?>
Вот и всё — если у вас остались вопросы, задавайте их в комментариях.
Нет разработчика для интеграции? Напишите нам на support@mitilena.com, и мы подготовим предложение по подключению криптоплатежей под ключ.