API Documentation - Tomatopay

1. Authentication

All API requests must be signed with HMAC-SHA256.

Signature parameters (sorted alphabetically):

All request parameters except api_key, signature, timestamp
All URL path parameters, such as uid in /api/invoices/{uid}
Array parameters are flattened recursively, for example project_ids[0]=1 and currencies[0][networkAlias]=trc20
Parameters are sorted alphabetically and joined as key=value&...
The timestamp is appended to the end of the string

Signature calculation:

stringToSign = "key1=value1&key2=value2&timestamp=1234567890"
signature = HMAC-SHA256(secret, stringToSign)

If there are no request or URL path parameters to sign, the string starts with &timestamp=....

Signature Example

# Signature calculation (same for all languages)
stringToSign="amount=100.00&source_currency=USDT&source_network=trc20&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "your_secret_key" | cut -d' ' -f2)
echo $signature

<?php
$secret = 'your_secret_key';
$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 = 'your_secret_key';
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 = 'your_secret_key'
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. Base URL

https://tomatopay.online/api

3. Endpoints

Create Invoice

POST /api/invoices

Create a new invoice for payment

Request Parameters

Parameter	Type	Required	Description
api_key	string	Yes	Your project API key
signature	string	Yes	HMAC-SHA256 signature
timestamp	integer	Yes	Unix timestamp
source_network	string	Yes	Network alias (e.g., "trc20", "erc20", "sberbank")
source_currency	string	Yes	Currency alias (e.g., "USDT", "BTC", "RUB")
amount	number	Yes	Invoice amount
order_number	string	No	Your internal order number
order_name	string	No	Order description
recipient_email	string	No	Customer email for notifications
return_url_type	string	No	Payment URL type: `telegram` (default) or `web`

Example Request

# First calculate signature
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 "your_secret_key" | cut -d' ' -f2)

curl -X POST https://tomatopay.online/api/invoices \
  -d "api_key=your_api_key" \
  -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 = 'your_api_key';
$secret = 'your_secret_key';
$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 = 'your_api_key';
const secret = 'your_secret_key';

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 = 'your_api_key'
secret = 'your_secret_key'

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'])

Response

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

Get Invoice Status

GET /api/invoices/{uid}

Get invoice status and details

Path Parameters

Parameter	Type	Required	Description
uid	string	Yes	Invoice UID from creation response

Request Parameters (Query)

Parameter	Type	Required	Description
api_key	string	Yes	Your project API key
signature	string	Yes	HMAC-SHA256 signature
timestamp	integer	Yes	Unix timestamp

Example Request

# First calculate signature
stringToSign="uid=inv_abc123def456&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "your_secret_key" | cut -d' ' -f2)

curl "https://tomatopay.online/api/invoices/inv_abc123def456?api_key=your_api_key&signature=$signature&timestamp=1234567890"

<?php
$apiKey = 'your_api_key';
$secret = 'your_secret_key';
$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 = 'your_api_key';
const secret = 'your_secret_key';
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 = 'your_api_key'
secret = 'your_secret_key'
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'])

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "uid": "inv_abc123def456",
    "status": "New",
    "status_text": "New",
    "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"
  }
}

Invoice Statuses

Status	Description
New	Invoice created, awaiting payment
Opened	Customer initiated payment
PartiallyFilled	Partial payment received
Completed	Payment fully received
Expired	Invoice expired without full payment
AwaitedIncome	Waiting for bank transfer confirmation

List Networks

GET /api/networks

Get list of supported networks

Request Parameters (Query)

Parameter	Type	Required	Description
api_key	string	Yes	Your project API key
signature	string	Yes	HMAC-SHA256 signature
timestamp	integer	Yes	Unix timestamp

Example Request

# First calculate signature
stringToSign="&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "your_secret_key" | cut -d' ' -f2)

curl "https://tomatopay.online/api/networks?api_key=your_api_key&signature=$signature&timestamp=1234567890"

<?php
$apiKey = 'your_api_key';
$secret = 'your_secret_key';
$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 = 'your_api_key';
const secret = 'your_secret_key';

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 = 'your_api_key'
secret = 'your_secret_key'

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'])

Response

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

Network Types

Type	Description
1	Cryptocurrency network
2	Bank transfer network

List Currencies

GET /api/currencies

Get list of supported currencies

Request Parameters (Query)

Parameter	Type	Required	Description
api_key	string	Yes	Your project API key
signature	string	Yes	HMAC-SHA256 signature
timestamp	integer	Yes	Unix timestamp
network_id	integer	No	Filter by network ID

Example Request

# First calculate signature
stringToSign="&timestamp=1234567890"
signature=$(echo -n "$stringToSign" | openssl dgst -sha256 -hmac "your_secret_key" | cut -d' ' -f2)

curl "https://tomatopay.online/api/currencies?api_key=your_api_key&signature=$signature&timestamp=1234567890"

<?php
$apiKey = 'your_api_key';
$secret = 'your_secret_key';
$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 = 'your_api_key';
const secret = 'your_secret_key';

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 = 'your_api_key'
secret = 'your_secret_key'

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'])

Response

{
  "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 Notifications

When invoice status changes, we send a POST request to your callback_url:

Callback 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..."
}

Signature Verification

The sign field is HMAC-SHA256 of these fields (sorted alphabetically):

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"

Important: Callback signature differs from API signature:

API: All parameters except api_key, signature, timestamp; then append &timestamp=...
Callback: Only these specific invoice fields (no timestamp, uses created_at instead)

5. Error Responses

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

Possible error codes: 401 (Invalid signature), 404 (Invoice not found), 422 (Validation error)

🍅
Tomatopay API Documentation

Contents

1. Authentication

Signature Example

2. Base URL

3. Endpoints

Create Invoice

Request Parameters

Example Request

Response

Get Invoice Status

Path Parameters

Request Parameters (Query)

Example Request

Response

Invoice Statuses

List Networks

Request Parameters (Query)

Example Request

Response

Network Types

List Currencies

Request Parameters (Query)

Example Request

Response

4. Callback Notifications

Callback Payload

Signature Verification

5. Error Responses

🍅 Tomatopay API Documentation

Contents

1. Authentication

Signature Example

2. Base URL

3. Endpoints

Create Invoice

Request Parameters

Example Request

Response

Get Invoice Status

Path Parameters

Request Parameters (Query)

Example Request

Response

Invoice Statuses

List Networks

Request Parameters (Query)

Example Request

Response

Network Types

List Currencies

Request Parameters (Query)

Example Request

Response

4. Callback Notifications

Callback Payload

Signature Verification

5. Error Responses

🍅
Tomatopay API Documentation