🍅
Документация API Tomatopay

Подключайте подписанные криптоплатежи: счета, кошельки, проекты, callback-уведомления и статусы оплат в одном компактном API.

Начать интеграцию Создать счет

Оглавление

Начало
Аутентификация Базовый URL Callback-уведомления Ошибки
Счета
Создание счёта Статус счёта
Справочники
Список сетей Список монет

1. Аутентификация

Все запросы к API должны быть подписаны с помощью HMAC-SHA256.

Параметры для подписи (в алфавитном порядке):
  • Все параметры запроса, кроме api_key, signature, timestamp
  • Все параметры пути URL, например uid в /api/invoices/{uid}
  • Массивы разворачиваются рекурсивно, например project_ids[0]=1 и currencies[0][networkAlias]=trc20
  • Параметры сортируются по алфавиту и объединяются как key=value&...
  • Timestamp добавляется в конец строки

Расчёт подписи: 
stringToSign = "key1=value1&key2=value2&timestamp=1234567890"
signature = HMAC-SHA256(secret, stringToSign)

Если нет параметров запроса и пути для подписи, строка начинается с &timestamp=....

Пример подписи

# Расчёт подписи (одинаково для всех языков)
stringToSign="amount=100.00&source_currency=USDT&source_network=trc20&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "ваш_секретный_ключ" | cut -d' ' -f2)
echo $signature
<?php
$secret = 'ваш_секретный_ключ';
$params = [
    'source_network' => 'trc20',
    'source_currency' => 'USDT',
    'amount' => '100.00',
];
$timestamp = time();
ksort($params);

$pairs = [];
foreach ($params as $key => $value) {
    $pairs[] = $key . '=' . $value;
}
$stringToSign = implode('&', $pairs) . '&timestamp=' . $timestamp;

$signature = hash_hmac('sha256', $stringToSign, $secret);
echo $signature;?>
const crypto = require('crypto');

const secret = 'ваш_секретный_ключ';
const params = {
    source_network: 'trc20',
    source_currency: 'USDT',
    amount: '100.00',
};
const timestamp = Math.floor(Date.now() / 1000);

const sortedKeys = Object.keys(params).sort();
const stringToSign = sortedKeys.map(k => `${k}=${params[k]}`).join('&') + `&timestamp=${timestamp}`;

const signature = crypto
    .createHmac('sha256', secret)
    .update(stringToSign)
    .digest('hex');
console.log(signature);
import hashlib
import hmac
import time

secret = 'ваш_секретный_ключ'
params = {
    'source_network': 'trc20',
    'source_currency': 'USDT',
    'amount': '100.00',
}
timestamp = int(time.time())

sorted_params = dict(sorted(params.items()))
string_to_sign = '&'.join(f"{k}={v}" for k, v in sorted_params.items()) + f"&timestamp={timestamp}"

signature = hmac.new(
    secret.encode(),
    string_to_sign.encode(),
    hashlib.sha256
).hexdigest()
print(signature)

2. Базовый URL

https://tomatopay.online/api

3. Эндпоинты

Создание счёта

POST /api/invoices

Создать новый счёт для оплаты

Параметры запроса

ПараметрТипОбязательныйОписание
api_keystringДаAPI ключ вашего проекта
signaturestringДаHMAC-SHA256 подпись
timestampintegerДаUnix timestamp
source_networkstringДаАлиас сети (например, "trc20", "erc20", "sberbank")
source_currencystringДаАлиас валюты (например, "USDT", "BTC", "RUB")
amountnumberДаСумма счёта
order_numberstringНетВаш внутренний номер заказа
order_namestringНетОписание заказа
recipient_emailstringНетEmail покупателя для уведомлений
return_url_typestringНетТип ссылки оплаты: telegram (по умолчанию) или web

Пример запроса

# Сначала вычислим подпись
stringToSign="amount=100.00&order_name=Premium Subscription&order_number=ORDER-123&recipient_email=user@example.com&source_currency=USDT&source_network=trc20&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "ваш_секретный_ключ" | cut -d' ' -f2)

curl -X POST https://tomatopay.online/api/invoices \
  -d "api_key=ваш_api_ключ" \
  -d "signature=$signature" \
  -d "timestamp=1234567890" \
  -d "source_network=trc20" \
  -d "source_currency=USDT" \
  -d "amount=100.00" \
  -d "order_number=ORDER-123" \
  -d "order_name=Premium Subscription" \
  -d "recipient_email=user@example.com"
<?php
$apiKey = 'ваш_api_ключ';
$secret = 'ваш_секретный_ключ';
$baseUrl = 'https://tomatopay.online/api';

$params = [
    'source_network' => 'trc20',
    'source_currency' => 'USDT',
    'amount' => '100.00',
    'order_number' => 'ORDER-123',
    'order_name' => 'Premium Subscription',
    'recipient_email' => 'user@example.com',
];
$timestamp = time();
$params['api_key'] = $apiKey;
$params['timestamp'] = $timestamp;

$signParams = $params;
unset($signParams['api_key'], $signParams['signature'], $signParams['timestamp']);
ksort($signParams);

$pairs = [];
foreach ($signParams as $key => $value) {
    $pairs[] = $key . '=' . $value;
}
$stringToSign = implode('&', $pairs) . '&timestamp=' . $timestamp;
$params['signature'] = hash_hmac('sha256', $stringToSign, $secret);

$ch = curl_init($baseUrl . '/invoices');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result['data']);?>
const crypto = require('crypto');
const https = require('https');

const apiKey = 'ваш_api_ключ';
const secret = 'ваш_секретный_ключ';

const params = {
    source_network: 'trc20',
    source_currency: 'USDT',
    amount: '100.00',
    order_number: 'ORDER-123',
    order_name: 'Premium Subscription',
    recipient_email: 'user@example.com',
};
params.api_key = apiKey;
params.timestamp = Math.floor(Date.now() / 1000);

const signParams = { ...params };
delete signParams.api_key;
delete signParams.signature;
delete signParams.timestamp;

const sortedKeys = Object.keys(signParams).sort();
const stringToSign = sortedKeys.map(k => `${k}=${signParams[k]}`).join('&') + `&timestamp=${params.timestamp}`;
params.signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('hex');

const postData = Object.entries(params).map(([k,v]) => `${k}=${encodeURIComponent(v)}`).join('&');

const options = {
    hostname: 'tomatopay.com',
    path: '/api/invoices',
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
};

const req = https.request(options, res => {
    let data = '';
    res.on('data', chunk => data += chunk);
    res.on('end', () => console.log(JSON.parse(data).data));
});
req.write(postData);
req.end();
import hashlib
import hmac
import urllib.request
import urllib.parse
import time
import json

api_key = 'ваш_api_ключ'
secret = 'ваш_секретный_ключ'

params = {
    'source_network': 'trc20',
    'source_currency': 'USDT',
    'amount': '100.00',
    'order_number': 'ORDER-123',
    'order_name': 'Premium Subscription',
    'recipient_email': 'user@example.com',
}
params['api_key'] = api_key
params['timestamp'] = int(time.time())

sign_params = {k: v for k, v in params.items() if k not in ('api_key', 'signature', 'timestamp')}
sorted_params = dict(sorted(sign_params.items()))
string_to_sign = '&'.join(f"{k}={v}" for k, v in sorted_params.items()) + f"&timestamp={params['timestamp']}"
params['signature'] = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

data = urllib.parse.urlencode(params).encode()
req = urllib.request.Request('https://tomatopay.online/api/invoices', data=data, method='POST')
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read())
    print(result['data'])

Ответ

{
  "status": "success",
  "data": {
    "id": "inv_abc123def456",
    "url": "https://tomatopay.online/invoice/abc123def456"
  }
}

Получение статуса счёта

GET /api/invoices/{uid}

Получить статус и детали счёта

Параметры пути (Path)

ПараметрТипОбязательныйОписание
uidstringДаUID счёта из ответа при создании

Параметры запроса (Query)

ПараметрТипОбязательныйОписание
api_keystringДаAPI ключ вашего проекта
signaturestringДаHMAC-SHA256 подпись
timestampintegerДаUnix timestamp

Пример запроса

# Сначала вычислим подпись
stringToSign="uid=inv_abc123def456&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "ваш_секретный_ключ" | cut -d' ' -f2)

curl "https://tomatopay.online/api/invoices/inv_abc123def456?api_key=ваш_api_ключ&signature=$signature&timestamp=1234567890"
<?php
$apiKey = 'ваш_api_ключ';
$secret = 'ваш_секретный_ключ';
$invoiceUid = 'inv_abc123def456';
$baseUrl = 'https://tomatopay.online/api';

$params = ['api_key' => $apiKey, 'timestamp' => time()];

$signParams = ['uid' => $invoiceUid];
ksort($signParams);

$pairs = [];
foreach ($signParams as $key => $value) {
    $pairs[] = $key . '=' . $value;
}
$stringToSign = implode('&', $pairs) . '&timestamp=' . $params['timestamp'];
$params['signature'] = hash_hmac('sha256', $stringToSign, $secret);

$url = $baseUrl . '/invoices/' . $invoiceUid . '?' . http_build_query($params);
$response = file_get_contents($url);
$result = json_decode($response, true);
print_r($result['data']);?>
const crypto = require('crypto');
const https = require('https');

const apiKey = 'ваш_api_ключ';
const secret = 'ваш_секретный_ключ';
const invoiceUid = 'inv_abc123def456';

const params = { api_key: apiKey, timestamp: Math.floor(Date.now() / 1000) };
const signParams = { uid: invoiceUid };
const sortedKeys = Object.keys(signParams).sort();
const stringToSign = sortedKeys.map(k => `${k}=${signParams[k]}`).join('&') + `&timestamp=${params.timestamp}`;
params.signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('hex');

const queryString = Object.entries(params).map(([k,v]) => `${k}=${encodeURIComponent(v)}`).join('&');
const options = {
    hostname: 'tomatopay.com',
    path: `/api/invoices/${invoiceUid}?${queryString}`,
    method: 'GET'
};

const req = https.request(options, res => {
    let data = '';
    res.on('data', chunk => data += chunk);
    res.on('end', () => console.log(JSON.parse(data).data));
});
req.end();
import hashlib
import hmac
import urllib.request
import urllib.parse
import time
import json

api_key = 'ваш_api_ключ'
secret = 'ваш_секретный_ключ'
invoice_uid = 'inv_abc123def456'

params = {'api_key': api_key, 'timestamp': int(time.time())}
sign_params = {'uid': invoice_uid}
sorted_params = dict(sorted(sign_params.items()))
string_to_sign = '&'.join(f"{k}={v}" for k, v in sorted_params.items()) + f"&timestamp={params['timestamp']}"
params['signature'] = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

query_string = urllib.parse.urlencode(params)
url = f'https://tomatopay.online/api/invoices/{invoice_uid}?{query_string}'
req = urllib.request.Request(url)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read())
    print(result['data'])

Ответ

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "inv_abc123def456",
    "status": "New",
    "status_text": "Новый",
    "source_currency": "USDT",
    "source_amount": "100.00",
    "source_rate": "1.00",
    "amount_in_usd": "100.00",
    "dest_network": "trc20",
    "dest_currency": "USDT",
    "dest_amount": "95.00",
    "dest_rate": "1.00",
    "filled_amount": "0.00",
    "filled_amount_in_usd": "0.00",
    "order_number": "ORDER-123",
    "order_name": "Premium Subscription",
    "recipient_email": "user@example.com",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "expired_at": "2024-01-15T11:30:00.000000Z"
  }
}

Статусы счетов

СтатусОписание
НовыйСчёт создан, ожидает оплаты
ОткрытПокупатель инициировал оплату
Частично оплаченПолучена частичная оплата
ЗавершёнОплата полностью получена
ИстёкСрок счёта истёк без полной оплаты
Ожидание поступленияОжидание подтверждения банковского перевода

Список сетей

GET /api/networks

Получить список поддерживаемых сетей

Параметры запроса (Query)

ПараметрТипОбязательныйОписание
api_keystringДаAPI ключ вашего проекта
signaturestringДаHMAC-SHA256 подпись
timestampintegerДаUnix timestamp

Пример запроса

# Сначала вычислим подпись
stringToSign="&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "ваш_секретный_ключ" | cut -d' ' -f2)

curl "https://tomatopay.online/api/networks?api_key=ваш_api_ключ&signature=$signature&timestamp=1234567890"
<?php
$apiKey = 'ваш_api_ключ';
$secret = 'ваш_секретный_ключ';
$baseUrl = 'https://tomatopay.online/api';

$params = ['api_key' => $apiKey, 'timestamp' => time()];
$stringToSign = '&timestamp=' . $params['timestamp'];
$params['signature'] = hash_hmac('sha256', $stringToSign, $secret);

$url = $baseUrl . '/networks?' . http_build_query($params);
$response = file_get_contents($url);
$result = json_decode($response, true);
print_r($result['data']);?>
const crypto = require('crypto');
const https = require('https');

const apiKey = 'ваш_api_ключ';
const secret = 'ваш_секретный_ключ';

const params = { api_key: apiKey, timestamp: Math.floor(Date.now() / 1000) };
const stringToSign = `&timestamp=${params.timestamp}`;
params.signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('hex');

const queryString = Object.entries(params).map(([k,v]) => `${k}=${encodeURIComponent(v)}`).join('&');
const options = {
    hostname: 'tomatopay.com',
    path: `/api/networks?${queryString}`,
    method: 'GET'
};

const req = https.request(options, res => {
    let data = '';
    res.on('data', chunk => data += chunk);
    res.on('end', () => console.log(JSON.parse(data).data));
});
req.end();
import hashlib
import hmac
import urllib.request
import urllib.parse
import time
import json

api_key = 'ваш_api_ключ'
secret = 'ваш_секретный_ключ'

params = {'api_key': api_key, 'timestamp': int(time.time())}
string_to_sign = f"&timestamp={params['timestamp']}"
params['signature'] = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

query_string = urllib.parse.urlencode(params)
url = f'https://tomatopay.online/api/networks?{query_string}'
req = urllib.request.Request(url)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read())
    print(result['data'])

Ответ

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "TRON",
      "alias": "trc20",
      "type": 1
    },
    {
      "id": 2,
      "title": "Ethereum",
      "alias": "erc20",
      "type": 1
    }
  ]
}

Типы сетей

ТипОписание
1Криптовалютная сеть
2Банковская сеть

Список монет

GET /api/currencies

Получить список поддерживаемых монет

Параметры запроса (Query)

ПараметрТипОбязательныйОписание
api_keystringДаAPI ключ вашего проекта
signaturestringДаHMAC-SHA256 подпись
timestampintegerДаUnix timestamp
network_idintegerНетФильтр по ID сети

Пример запроса

# Сначала вычислим подпись
stringToSign="&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "ваш_секретный_ключ" | cut -d' ' -f2)

curl "https://tomatopay.online/api/currencies?api_key=ваш_api_ключ&signature=$signature&timestamp=1234567890"
<?php
$apiKey = 'ваш_api_ключ';
$secret = 'ваш_секретный_ключ';
$baseUrl = 'https://tomatopay.online/api';

$params = ['api_key' => $apiKey, 'timestamp' => time()];
$stringToSign = '&timestamp=' . $params['timestamp'];
$params['signature'] = hash_hmac('sha256', $stringToSign, $secret);

$url = $baseUrl . '/currencies?' . http_build_query($params);
$response = file_get_contents($url);
$result = json_decode($response, true);
print_r($result['data']);?>
const crypto = require('crypto');
const https = require('https');

const apiKey = 'ваш_api_ключ';
const secret = 'ваш_секретный_ключ';

const params = { api_key: apiKey, timestamp: Math.floor(Date.now() / 1000) };
const stringToSign = `&timestamp=${params.timestamp}`;
params.signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('hex');

const queryString = Object.entries(params).map(([k,v]) => `${k}=${encodeURIComponent(v)}`).join('&');
const options = {
    hostname: 'tomatopay.com',
    path: `/api/currencies?${queryString}`,
    method: 'GET'
};

const req = https.request(options, res => {
    let data = '';
    res.on('data', chunk => data += chunk);
    res.on('end', () => console.log(JSON.parse(data).data));
});
req.end();
import hashlib
import hmac
import urllib.request
import urllib.parse
import time
import json

api_key = 'ваш_api_ключ'
secret = 'ваш_секретный_ключ'

params = {'api_key': api_key, 'timestamp': int(time.time())}
string_to_sign = f"&timestamp={params['timestamp']}"
params['signature'] = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

query_string = urllib.parse.urlencode(params)
url = f'https://tomatopay.online/api/currencies?{query_string}'
req = urllib.request.Request(url)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read())
    print(result['data'])

Ответ

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "alias": "USDT",
      "network_id": 1,
      "usd_rate": "1.000000",
      "is_private": false
    },
    {
      "id": 2,
      "alias": "BTC",
      "network_id": 2,
      "usd_rate": "50000.000000",
      "is_private": false
    }
  ]
}

4. Callback уведомления

При изменении статуса счёта мы отправляем POST запрос на ваш callback_url:

Payload

{
  "id": 123,
  "uid": "inv_abc123def456",
  "status": "Completed",
  "source_currency": "USDT",
  "source_amount": "100.00",
  "source_rate": "1.0",
  "dest_network": "trc20",
  "dest_currency": "USDT",
  "dest_amount": "99.00",
  "dest_rate": "1.0",
  "amount_in_usd": "100.00",
  "filled_amount": "100.00",
  "filled_amount_in_usd": "100.00",
  "order_number": "ORDER-123",
  "order_name": "Premium Subscription",
  "recipient_email": "user@example.com",
  "created_at": "2024-01-15T10:30:00+00:00",
  "expired_at": "2024-01-15T11:30:00+00:00",
  "transactions": [...],
  "sign": "abc123signature..."
}

Проверка подписи

Поле sign - это HMAC-SHA256 от следующих полей (сортировка по алфавиту):

created_at, filled_amount, filled_amount_in_usd, id, source_amount, source_currency, source_rate, status

stringToSign="created_at=2024-01-15T10:30:00+00:00&filled_amount=100.00&filled_amount_in_usd=100.00&id=123&source_amount=100.00&source_currency=USDT&source_rate=1.0&status=Completed"
Важно: Подпись callback ОТЛИЧАЕТСЯ от подписи API:

  • API: Все параметры, кроме api_key, signature, timestamp; затем в конец добавляется &timestamp=...
  • Callback: Только определённые поля инвойса (без timestamp, вместо него created_at)

5. Ошибки

{
  "status": "error",
  "message": "Unauthorized"
}

Коды ошибок: 401 (Неверная подпись), 404 (Счёт не найден), 422 (Ошибка валидации)