Приймайте оплату карткою, отримуйте USDC — з реєстрацією і без

Як проходить платіж

Схема однакова в усіх режимах. Відрізняються лише місце, куди йдуть гроші, та інструменти довкола.

Базова URL-адреса для всіх викликів API: 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, що надійшла, після оплати є в полі received_amount замовлення; вона може трохи відрізнятися від оцінки, бо курс конвертації встановлює провайдер. Збережені баланси можна обмінювати між валютами й виводити в USDC, USDT, BTC, ETH тощо — див. Зберігання в UTOPAY.

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

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 та іншими — на унікальну адресу замовлення. Усе, що надійшло, одразу пересилається on-chain на ваш гаманець — або, з settlement: "custody", зараховується на ваш баланс UTOPAY (гаманці не потрібні). Комісія 1.5%, утримується з отриманої суми; комісія блокчейну — окремо.

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

Кожна монета/мережа з ticker (те, що ви передаєте як coin, напр. polygon/usdc, bep20/usdt, erc20/usdt, base/usdc, eth, btc, trc20/usdt), network, family (тип адреси), minimum і available. Працюють EVM-мережі, Tron, Bitcoin, Solana, TON та інші; available: false — мережа тимчасово недоступна.

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

Пряма виплата

Гроші ніколи не залишаються в нас: кожен платіж розподіляється on-chain у момент надходження USDC.

• Увімкнути: кабінет → проєкт → Кошти й виплати → Напряму на гаманець, вставте адресу USDC (Polygon). Або в запиті: "settlement": "direct".
• Ви отримуєте USDC з кожного платежу; зверху — історія, статистика, вебхуки й сповіщення в Telegram. Нічого виводити не треба.
• Один гаманець на проєкт — потрібно кілька гаманців, створіть кілька проєктів.

Зберігання в UTOPAY

USDC надходить на гаманець платформи UTOPAY. Після paid ваша частка зараховується на внутрішній баланс — далі зберігайте, обмінюйте, конвертуйте чи виводьте.

• Увімкнути: Кошти й виплати → Зберігання в UTOPAY (гаманець не потрібен), або "settlement": "custody" у запиті.
• Зарахування: amount × 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-ключем.

Платіжні посилання

Без коду: створіть посилання, надішліть у чат чи email — отримайте оплату. Кабінет → проєкт → Платіжні посилання → + Посилання.

• Сума фіксована або порожня — її вводить покупець. Валюта — будь-яка зі списку.
• Метод (необов'язково): закріпіть провайдера. З фіксованою сумою посилання відправляє покупця одразу до нього; з вільною сумою покупець бачить лише поле суми й кнопку «Оплатити через PayPal». Якщо метод недоступний, показується звичайний вибір методів.
• URL повернення — куди покупець потрапляє після оплати. Одноразові посилання стають used після першого замовлення (повторне відкриття веде до цього замовлення); багаторазові працюють, доки їх не архівують.
• Кошти йдуть за режимом коштів проєкту. Замовлення з посилань з'являються в історії й надсилають вебхуки так само, як замовлення з API.

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

Вебхуки та сповіщення

З акаунтом. Коли замовлення змінює стан, UTOPAY надсилає його POST-запитом на кожен ендпоінт проєкту з підписом HMAC-SHA256.

Реєстрація: кабінет → Вебхуки → + Ендпоінт, або 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 (Сповіщення).

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

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

Команда, брендинг, маршрутизація

Команда: запрошення за email (Команда). Ролі admin, developer, finance, viewer; творець — owner.

Брендинг: назва, логотип, колір фону й кнопки в Налаштуваннях — застосовуються до сторінки оплати, сторінок посилань і екрана успішної оплати.

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

Об'єкт замовлення

Повертається create/get/list і передається у вебхуках.

Усі публічні ендпоінти

Комісії

• Ви отримуєте 95.5% — однаково з акаунтом і без, у режимах «напряму» та «зберігання», для будь-якої валюти й методу. Без плати за підключення й абонплати.
• Великі мерчанти можуть отримати індивідуальну ставку — напишіть нам. Точний розподіл кожного замовлення — у fees.

Реферальна програма

• Рівень 1: 25% нашої комісії з мерчантів, яких запросили ви; рівень 2: 10% з мерчантів, яких запросили вони.
• Виплачується on-chain з кожного платежу на реферальний гаманець, указаний у Рефералах. Береться з нашої комісії — реферали нічого не доплачують.

Помилки

Кожна помилка — { "error": "message" } з відповідним HTTP-статусом.