Принимайте оплату картой, получайте USDC — с регистрацией и без

Как проходит платёж

Поток одинаков во всех режимах. Отличаются только место назначения денег и инструменты вокруг.

Базовый URL для всех вызовов: https://api.utopay.app. Запросы и ответы — JSON (content-type: application/json). Суммы — числа в валюте заказа, время — Unix в миллисекундах.

Быстрый старт

Реальный платёж одним запросом — без регистрации. Покупатель сразу попадает в PayPal; если PayPal не может принять этот платёж, откроется наша страница с другими способами.

curl -X POST https://api.utopay.app/v1/pay \
  -H "content-type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "payout_wallet": "0xYourPolygonWalletAddress000000000000000000",
    "provider": "paypal",
    "success_url": "https://yoursite.com/thanks"
  }'
# → { "id": "ord_…", "checkout_url": "https://api.utopay.app/pay/ord_…/go?provider=paypal", … }

Перенаправьте покупателя на checkout_url. После оплаты на кошелёк придёт около 95.5 USDC. С аккаунтом вместо этого вызывается POST /v1/payments с API-ключом — те же поля, плюс история, вебхуки и баланс.

Сравнение режимов

Без регистрации

POST /v1/pay

Заголовок Authorization не нужен. Деньги всегда уходят сразу на payout_wallet — EVM-адрес, способный принимать USDC в сети Polygon. Тело — как у POST /v1/payments, плюс:

• Всегда direct: "settlement": "custody" вернёт 400 — без аккаунта некуда зачислять баланс.
• Фиксированная комиссия 4.5%, без рефералки и вебхуков (callback_url сохраняется, но не вызывается), без тестового режима, стандартный дизайн чекаута.
• Отслеживание: опрашивайте публичный GET /api/checkout/:id/status (без ключа) или смотрите на кошелёк.

Аккаунт и API-ключи

В аккаунте до 20 проектов (по одному на сайт). У каждого свои ключи, вебхуки, кошелёк, бренд, режим денег и статистика; баланс общий на аккаунт.

Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx

Ключ показывается один раз, у нас хранится только хеш. Не размещайте секретный ключ в браузерном или мобильном коде.

Создание платежа

POST /v1/payments Bearer sk

curl -X POST https://api.utopay.app/v1/payments \
  -H "Authorization: Bearer utopay_sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "amount": 250,
    "currency": "EUR",
    "email": "[email protected]",
    "description": "Invoice #118",
    "provider": "revolut",
    "success_url": "https://yoursite.com/thanks"
  }'

{
  "id": "ord_Kd83mQp0aVxY",
  "status": "pending",
  "amount": 250, "currency": "EUR",
  "checkout_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY/go?provider=revolut",
  "payment_page_url": "https://api.utopay.app/pay/ord_Kd83mQp0aVxY",
  "provider": "revolut",
  "routing": { "mode": "direct_to_provider", "requested_provider": "revolut", "reason": null },
  "settlement": "direct",
  "payout_coin": "USDC", "payout_network": "polygon",
  …  full list in Order object
}

Всегда отправляйте покупателя на checkout_url. payment_page_url пригодится для ссылки «выбрать другой способ» — он всегда открывает нашу страницу.

Сразу к способу оплаты

Работает во всех режимах — с API-ключом, без аккаунта, в платёжных ссылках из кабинета и в форме без кода на /payment-links. Укажите provider — и покупатель попадёт прямо к провайдеру (например в PayPal), не видя нашу форму.

routing в ответе показывает, что произошло: mode — direct_to_provider или payment_page; reason — null, provider_offline, provider_below_minimum, provider_currency, provider_disabled или project_routing (выбран из предпочитаемых провайдеров проекта).

GET /v1/providers?amount=&currency= публичный

Способы, доступные прямо сейчас для этой суммы и валюты: id, name, region, status, minimum_amount и minimum_currency. Список меняется — запрашивайте его, а не зашивайте в код.

* Минимумы и доступность приходят от платёжной сети и меняются; перед сравнением сумма пересчитывается в валюту минимума. Некоторые провайдеры могут попросить у покупателя быструю разовую проверку личности.

Валюты и что вы получаете

currency — валюта, в которой платит покупатель. Какой бы она ни была, провайдер конвертирует деньги, и дальше они идут как USDC в сети Polygon.

GET /v1/currencies публичный

Любой другой код вернёт 400. Провайдер может показать покупателю цену в своей валюте (например Revolut — в EUR) — покупатель всё равно платит эквивалент вашей суммы. Некоторые способы принимают только определённые валюты — /v1/providers?currency=… их не вернёт.

Что и куда приходит

Точное количество пришедших USDC после оплаты — в поле value_coin заказа; оно может немного отличаться от оценки, так как курс конвертации задаёт провайдер. Балансы при хранении можно обменивать между валютами и выводить в USDC, USDT, BTC, ETH и др. — см. Хранение у нас.

Статус платежа

GET /v1/payments/:id Bearer sk

Заказ в том же формате. Пока он не paid, мы дополнительно сверяем статус у провайдера, поэтому опрос надёжен, даже если callback задержался — зачисление на баланс и ваш вебхук в любом случае происходят ровно один раз. Видны только заказы проекта ключа (иначе 404).

GET /v1/payments?limit=&offset=&status= Bearer sk

Заказы проекта, сначала новые. limit 1–500 (по умолчанию 50), status = pending | paid | failed.

GET /api/checkout/:id/status публичный

Без ключа: { "id", "status", "amount", "currency", "updated_at" }. Для заказов без аккаунта. Не считайте переход на success_url доказательством оплаты — проверьте статус.

Крипто-шлюз

Покупатель платит напрямую криптой — USDT, USDC, ETH, BTC и др. — на уникальный адрес заказа. Всё пришедшее сразу пересылается ончейн на ваш кошелёк. Комиссия 1.5% удерживается из полученной суммы, комиссия блокчейна — отдельно. Всегда напрямую: крипта не хранится на балансе UTOPAY.

GET /v1/crypto/coins публичный

Все монеты и сети: ticker (его передают в coin, например polygon/usdc, bep20/usdt, erc20/usdt, base/usdc, eth, btc, trc20/usdt), network, family (тип адреса), minimum и available. EVM-сети работают; сети с available: false (Tron, Bitcoin, Solana, TON…) подключаются.

POST /v1/crypto/payments Bearer sk · POST /v1/crypto/pay без аккаунта

curl -X POST https://api.utopay.app/v1/crypto/pay \
  -H "content-type: application/json" \
  -d '{ "coin": "bep20/usdt", "amount": 100, "currency": "USD",
        "payout_address": "0xYourWallet0000000000000000000000000000000" }'
# → { "id": "ord_…", "kind": "crypto", "checkout_url": "https://api.utopay.app/pay/ord_…",
#     "crypto": { "coin": "bep20/usdt", "network": "BNB Smart Chain (BEP-20)", "symbol": "USDT",
#                 "address": "0x…", "amount_coin": 100.02, "minimum": 1.66, "detected": false, "underpaid": false } }

• Отправьте покупателя на checkout_url (сумма, сеть, адрес, QR, живой статус) — или покажите crypto.address и crypto.amount_coin на своей странице.
• Статусы: pending (с crypto.detected: true, когда перевод замечен, до подтверждений) → paid. Если пришло меньше запрошенного (больше чем на 1%), статус underpaid и событие payment.underpaid — деньги уже у вас на кошельке, решение за вами.
• Вебхуки, GET /v1/payments/:id и тестовые ключи работают как для карт. Переводы ниже minimum или в другой монете/сети не обрабатываются — страница оплаты предупреждает покупателя.

Примеры интеграции

Создайте заказ на сервере (никогда не с секретным ключом в браузере), отправьте покупателя на checkout_url и отметьте заказ оплаченным по вебхуку. Пошаговый гайд: приём крипты на сайте; сети и тикеры для Tether: приём USDT.

const res = await fetch('https://api.utopay.app/v1/crypto/payments', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.UTOPAY_SK}`, 'content-type': 'application/json' },
  body: JSON.stringify({ coin: 'bep20/usdt', amount: 49.9, currency: 'EUR', description: 'Order #1042',
    success_url: 'https://shop.example/thanks', cancel_url: 'https://shop.example/cart' })
});
const order = await res.json();
if (!res.ok) throw new Error(order.error);
// save order.id with your order, then redirect the buyer
reply.redirect(order.checkout_url);

import os, requests

r = requests.post('https://api.utopay.app/v1/crypto/payments',
    headers={'Authorization': f'Bearer {os.environ["UTOPAY_SK"]}'},
    json={'coin': 'erc20/usdt', 'amount': 120, 'currency': 'USD', 'description': 'Invoice 77'},
    timeout=20)
order = r.json()
r.raise_for_status()
print(order['id'], order['checkout_url'], order['crypto']['address'], order['crypto']['amount_coin'])

$ch = curl_init('https://api.utopay.app/v1/crypto/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('UTOPAY_SK'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['coin' => 'polygon/usdt', 'amount' => 25, 'currency' => 'USD']),
]);
$order = json_decode(curl_exec($ch), true);
header('Location: ' . $order['checkout_url']);

Прямая отправка на кошелёк

Деньги не задерживаются у нас: каждый платёж делится ончейн в момент поступления USDC.

• Включение: кабинет → проект → Funds & payouts → Direct to wallet, укажите адрес USDC (Polygon). Или в запросе: "settlement": "direct".
• USDC приходит с каждого платежа; плюс история, статистика, вебхуки и Telegram. Выводить нечего.
• Один кошелёк на проект — нужно несколько кошельков, заведите несколько проектов.

Хранение у нас

USDC приходит на кошелёк платформы. При paid ваша доля зачисляется на внутренний баланс — дальше вы держите, обмениваете, свопаете или выводите.

• Включение: Funds & payouts → Stored on UTOPAY (кошелёк не нужен) или "settlement": "custody" в запросе.
• Зачисление: сумма × 95.5% в валюте заказа (USD, EUR, GBP, CAD, INR, SEK), любая другая валюта — в USD по текущему курсу. Ровно один раз.
• Один баланс на аккаунт: все проекты в этом режиме копят в одном месте; в журнале виден проект-источник.

Сети для вывода: USDC_POLYGON, USDT_POLYGON, USDT_TRC20, USDT_ERC20, ETH, BTC, BNB, TRX. Сумма резервируется сразу (pending), перевод отправляет команда UTOPAY, обычно в течение рабочего дня (done с txid). Отклонённые заявки возвращаются на баланс. API-ключом вывод не запустить.

Платёжные ссылки

Без кода: создайте ссылку, отправьте в чат или на почту — получите оплату. Кабинет → проект → Payment links → + Link.

• Сумма фиксированная или пустая — тогда вводит покупатель. Валюта — любая из списка.
• Способ (необязательно): закрепите провайдера. С фиксированной суммой ссылка сразу уводит покупателя к нему; со свободной — покупатель видит только поле суммы и кнопку «Pay with PayPal». Если способ недоступен — показывается обычный выбор способа.
• Return URL — куда вернуть покупателя после оплаты. Одноразовая ссылка после первого заказа становится used (повторное открытие ведёт в этот заказ); многоразовая работает до архивации.
• Деньги идут по режиму проекта. Заказы по ссылкам попадают в историю и вызывают вебхуки так же, как заказы из API.

Публичная ссылка — https://api.utopay.app/i/lnk_…. Без аккаунта используйте форму на /payment-links — она создаёт заказ /v1/pay с тем же выбором способа.

Вебхуки и уведомления

С аккаунтом. Когда заказ меняет состояние, UTOPAY шлёт POST на каждый эндпоинт проекта с подписью HMAC-SHA256.

Регистрация: кабинет → Webhooks → + Endpoint или POST /api/merchants/:id/webhooks с { "url": "https://you.com/hooks/utopay" }. Секрет whsec_… — в кабинете.

POST https://you.com/hooks/utopay
content-type: application/json
x-utopay-event: payment.succeeded
x-utopay-signature: t=1759660123,v1=<hex hmac-sha256>
user-agent: UTOPAY-Webhooks/1.0

{
  "event": "payment.succeeded",
  "created_at": 1759660123456,
  "data": { /* the Order object */ }
}

import crypto from 'node:crypto';
// use the RAW body, not re-serialised JSON
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const a = Buffer.from(v1 || ''), b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// raw body + x-utopay-signature header + your whsec_… secret
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_UTOPAY_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('UTOPAY_WHSEC'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'payment.succeeded') { /* mark $event['data']['id'] as paid */ }
http_response_code(200);

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t', ''), parts.get('v1', '')
    expected = hmac.new(secret.encode(), f'{t}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = t.isdigit() and abs(time.time() - int(t)) < 300
    return fresh and hmac.compare_digest(expected, v1)

• Отвечайте 2xx в течение 10 с. Повторы через 30 с, 2 мин, 15 мин, 1 ч, 6 ч — 6 попыток. Доставки видны в кабинете.
• Будьте идемпотентны — дедуплицируйте по data.id.
• Telegram: оплаченные заказы приходят в чат с суммой, описанием и id (Notifications).

Тестовый режим

1. Создайте тестовый секретный ключ (utopay_sk_test_…) и вызывайте POST /v1/payments как обычно — вся валидация (валюта, провайдер) та же.
2. checkout_url ведёт на песочницу (/sandbox/ord_test_…). Нажмите Simulate payment или Simulate failure.
3. Вебхуки и Telegram срабатывают как в продакшене, с "is_test": true. Деньги не двигаются, баланс не зачисляется.

Команда, бренд, роутинг

Команда: приглашение по email (Team). Роли admin, developer, finance, viewer; создатель — owner.

Бренд: название, логотип, цвет фона и кнопки в Settings — применяется к странице оплаты, страницам ссылок и экрану успешной оплаты.

Роутинг проекта: в Routing перечислите предпочитаемых провайдеров по приоритету. Для API-платежей без provider берётся первый онлайн-провайдер, подходящий по сумме и валюте (routing.reason = "project_routing"); если подходящих нет — покупатель выбирает на нашей странице. Явный provider всегда важнее.

Объект заказа

Возвращается при создании, получении, в списке и внутри вебхуков.

Все публичные эндпоинты

Комиссии

• Вы получаете 95.5% — одинаково с аккаунтом и без, при прямой отправке и хранении, для любой валюты и способа. Без платы за подключение и абонентской платы.
• Крупным мерчантам — индивидуальная ставка, свяжитесь с нами. Точное разделение каждого заказа — в fees.

Партнёрская программа

• 1-й уровень: 25% нашей комиссии с приглашённых вами мерчантов; 2-й уровень: 10% с приглашённых ими.
• Выплачивается ончейн при каждом платеже на реферальный кошелёк из Referrals. Берётся из нашей комиссии — рефералы не платят сверху.

Ошибки

Любая ошибка — { "error": "message" } с соответствующим HTTP-статусом.