API криптоплатежей для разработчиков

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

Каждый запрос с вашего сервера использует HTTP Basic auth: ID проекта как имя пользователя и секрет проекта как пароль. Храните секрет на сервере; им же подписываются ваши вебхуки.

https://payments.rubysoft.io/api

HTTP

Authorization: Basic base64(PROJECT_ID:PROJECT_SECRET)

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

Используйте счёт, когда клиент оплачивает один заказ. Передайте свой 24-символьный ID заказа в payload, цену в USD, допустимую недоплату (от 0 до 5%), срок действия и URL, на который придут вебхуки этого счёта.

payloadID вашего заказа, 24 шестнадцатеричных символа (подойдёт MongoDB ObjectId)

meta[price]Цена в USD

meta[tolerancePercent]Допустимая недоплата, от 0 до 5

meta[expiresAt]Срок действия, ISO 8601, в будущем

meta[webhookUrl]Куда отправляются события этого счёта

curl -G https://payments.rubysoft.io/api/invoice/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=65f2c1a9e4b0d3f7a2c91e04" \
  --data-urlencode "meta[price]=120" \
  --data-urlencode "meta[tolerancePercent]=1" \
  --data-urlencode "meta[expiresAt]=2026-12-01T12:00:00Z" \
  --data-urlencode "meta[webhookUrl]=https://shop.example/webhooks/rubynex"

В ответе есть объект addresses с ключами по сетям. Покажите клиенту те сети, которые хотите предложить.

200 OK

{
  "id": "0b6f3c1e-8a52-4d7e-9c41-2f6a8d0e5b17",
  "payload": "65f2c1a9e4b0d3f7a2c91e04",
  "meta": {
    "type": "invoice",
    "status": "pending",
    "price": "120",
    "paid": "0",
    "expiresAt": "2026-12-01T12:00:00.000Z"
  },
  "addresses": {
    "tron": "T…",
    "ethereum": "0x…",
    "bsc": "0x…",
    "bitcoin": "bc1q…"
  }
}

Постоянные адреса для пополнения

Используйте постоянные адреса для пополнений: кошельки, игры, биржи, подписки. Передайте 24-символьный ID клиента в payload и каждый раз получайте одни и те же адреса.

cURL

curl -G https://payments.rubysoft.io/api/charge/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=66a0b7d2c5e8f1a3b6d904c7"

# the same customer ID always returns the same addresses

Статусы счёта

pendingОжидает оплаты

paidПоступила полная сумма

underpaidПоступило меньше цены

overpaidПоступило больше цены более чем на 1%

expiredОплата не поступила до истечения срока

Вебхуки

Каждое событие отправляется POST-запросом с телом в JSON и заголовком X-Webhook-Signature: это HMAC-SHA256 от исходного тела с ключом из секрета проекта, декодированного из hex, записанный в hex. Ответьте любым статусом 2xx. Иначе запрос повторяется: события счетов каждые 15 секунд до доставки, события платежей каждые 10 минут, до 150 раз.

События

invoice:<status>Счёт сменил статус

pending-paymentПлатёж обнаружен и ждёт подтверждений

confirmed-paymentПлатёж подтверждён и зачислен

failed-paymentПлатёж не удалось обработать

Webhook

POST /webhooks/rubynex
Content-Type: application/json
X-Webhook-Signature: 9c1fd2…e07a

{
  "id": "4e1a…c93f",
  "message": {
    "event": "invoice:paid",
    "data": { "id": "0b6f3c1e-…", "payload": "65f2c1a9e4b0d3f7a2c91e04" }
  },
  "attempt": 0,
  "timestamp": 1764590400
}

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

import crypto from 'node:crypto';
import express from 'express';

const secret = Buffer.from(process.env.RUBYNEX_SECRET, 'hex');

// keep the raw body: the signature covers its exact bytes
app.post('/webhooks/rubynex', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const given = req.get('X-Webhook-Signature') ?? '';
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { message } = JSON.parse(req.body);
  if (message.event === 'invoice:paid') markOrderPaid(message.data.payload);
  res.sendStatus(200);
});

Подтверждения по сетям

Сеть	Монеты	Подтверждения	Время зачисления
TRON	TRXUSDT	1	около 3 с
Ethereum	ETHUSDTUSDCDAI	5	около 1 мин
BNB Smart Chain	BNBUSDTUSDCDAI	10	около 8 с
Polygon	POLUSDTUSDCDAI	20	около 40 с
Base	ETHUSDTUSDC	10	около 20 с
Bitcoin	BTC	1	около 10 мин
XRP Ledger	XRP	1	около 4 с
Dogecoin	DOGE	3	около 3 мин

Лимиты, которые стоит знать

Платежи до $1 включительно игнорируются как пыль
Допустимая недоплата по счёту: до 5%
Счёт считается переплаченным, если поступило больше цены более чем на 1%
Секрет проекта можно менять раз в 5 минут

Готовы получить ключи?

Мы создадим ваш проект и пришлём его ID и секрет.

Получить API-ключи

API криптоплатежей, который можно прочитать за десять минут