Python SDK

Официальная библиотека для Python. Пакет oblodai. Синхронный и асинхронный клиенты, типы (pydantic v2).

Требования: Python 3.9+.

---

​

Установка

pip install oblodai

Новое в v1.1.0 (текущая версия в PyPI): группы batches / links / splits / payout_links, методы create_batch / refund_batch / send_email / resolve — и ломающее изменение идемпотентности: вместо авто-order_id теперь заголовок Idempotency-Key (см. «Ошибки и повторы»).

---

​

Аутентификация (ключи из окружения)

Ключи берутся в кабинете my.oblodai.com — см. Регистрация и ключи.

export OBLODAI_PUBLIC_ID=oblodai_ваш_public_id
export OBLODAI_SECRET=oblodai_ваш_secret
# необязательно: export OBLODAI_BASE_URL=https://api.oblodai.com

from oblodai import OblodaiClient

client = OblodaiClient.from_env()  # OBLODAI_PUBLIC_ID / OBLODAI_SECRET / OBLODAI_BASE_URL

Или явно:

client = OblodaiClient(public_id="...", secret="...", base_url="https://api.oblodai.com")

---

​

Быстрый старт: принять платёж

payment = client.payments.create(
    amount="10",
    currency="USD",
    order_id="order-1",
    to_currency="USDT",
    network="tron",
    url_callback="https://ваш-сайт.ру/oblodai/webhook",
    url_success="https://ваш-сайт.ру/thanks",
)

# редиректите покупателя на payment.url
print(payment.address, payment.url)

Не хотите указывать валюту/сеть за покупателя? Не передавайте to_currency и network — получится «валюто-агностичная» ссылка, где покупатель сам выберет монету на странице оплаты.

​

Асинхронно

from oblodai import AsyncOblodaiClient

async with AsyncOblodaiClient.from_env() as client:
    payment = await client.payments.create(amount="10", currency="USD", order_id="order-1")

---

​

Ресурсы и методы

Группа	Методы
client.payments	create, info, history, services, qr, resend, refund, list_accepted, set_accepted, get_accuracy, set_accuracy, get_autorefund, set_autorefund, set_discount, list_discounts · с v1.1.0: create_batch, refund_batch, send_email, resolve
client.payouts	create, create_mass, info, history, services, calculate, approve, get_fee_config, set_fee_config, get_refund_fee_config, set_refund_fee_config, refund · с v1.1.0: create_batch
client.batches (v1.1.0)	info
client.links (v1.1.0)	create, list, info, toggle, public_get, checkout
client.payout_links (v1.1.0)	create, create_batch (до 500), list, info, cancel + публичные без подписи: claim_info(token), claim(token, address=…, memo=…)
client.splits (v1.1.0)	split_to_address, split_to_merchant, list_rules, delete_rule, get_config, set_config
client.wallets	create, block, blocked_address_refund, qr
client.account	balance, referral, transfer_to_personal, vrcs
client.webhooks	register, deliveries, test_payment, test_wallet, test_payout
client.settings	list_auto_withdraw, set_auto_withdraw, delete_auto_withdraw, list_allowlist, add_allowlist, remove_allowlist, enable_allowlist
client.rates	list (курсы), currencies (публичный каталог)

Точные поля — в Справочнике. У синхронного и асинхронного клиента API одинаков.

Всё, что помечено «с v1.1.0», доступно начиная с версии 1.1.0 — если у вас стоит v1.0.x, обновите пакет (pip install -U oblodai). Свой ключ идемпотентности в методах создания — kwarg idempotency_key (уйдёт в заголовок).

# Массовые операции: до 5000 элементов одним подписанным запросом (одна отметка rate-limit).
sub = client.payments.create_batch([
    {"amount": "10", "currency": "USD", "order_id": "a-1", "to_currency": "USDT", "network": "tron"},
    {"amount": "20", "currency": "EUR", "order_id": "a-2", "to_currency": "USDT", "network": "tron"},
], on_error="continue")            # "continue" (по умолчанию) или "stop"

info = client.batches.info(sub.batch_id, limit=100)   # прогресс и результат по каждому элементу
if info.done:
    print(info.succeeded, info.failed)

# Платёжная ссылка: платят многие, каждый платёж — свой инвойс. Работает без вашего бэкенда.
link = client.links.create(amount_mode="open", currency="USD")

# Сплит: доля каждого входящего платежа автоматически уходит партнёру.
client.splits.split_to_address(address="T...", network="tron", percent=10, note="партнёр А")

# Счёт на e-mail (письмо с кнопкой «Оплатить»).
client.payments.send_email(uuid=payment.uuid, email="[e-mail]")

# Резолв недоплаты: принять частичную оплату (глушит авто-возврат) или вернуть плательщику.
client.payments.resolve(uuid=payment.uuid, action="accept")   # или action="refund"

Крипто-чек за 4 строки — выплата без адреса получателя (заберёт сам по ссылке):

check = client.payout_links.create(
    amount="25", currency="USDT", network="tron",
    reference="bonus-42", expires_in_hours=72, email="[e-mail]",
)
print(check.claim_url)  # отдайте получателю — он введёт свой адрес сам

• Задавайте expires_in_hours явно: без него чек живёт всего 1 час.
• claim_url / claim_token возвращаются только из create, один раз — сохраните сразу.
• Дедупликация — поле reference (заголовок Idempotency-Key на этих эндпоинтах не действует).

Подробности — Массовые операции, Платёжные ссылки, Сплит-платежи, Счета на e-mail, Крипто-чеки, Резолв платежа.

---

​

Валюта цены и валюта расчёта

В примере выше currency="USD" — валюта цены, а to_currency="USDT" — валюта расчёта. Это разные вещи:

• currency (цена) — одна из 23 фиатных валют: USD, EUR, GBP, RUB, UAH, PLN, CZK, TRY, CNY, INR, BRL, CAD, AUD, CHF, AED, ZAR, MXN, IDR, THB, VND, NGN, JPY, KRW — или любая монета (USDT, BTC, TRX, …).
• to_currency (расчёт) — только крипта. Фиата здесь не бывает: баланс, выплаты и возвраты всегда в монете, шлюз не хранит фиат.
• У JPY и KRW ноль знаков после запятой (amount="10000", не "10000.00"); у остальных — 2.
• KZT, KGS, UZS пока не поддерживаются → payment.unknown_currency.
• Фиатная цена + только network без to_currency → 400 payment.to_currency_required. Либо задайте to_currency, либо не задавайте ни то, ни другое (тогда монету выберет покупатель).

Полный список валют цены — client.rates.currencies(), поле pricing_currencies.

---

​

Проверьте, что заработало

1. Запустите код создания платежа из «Быстрого старта». В ответе должен прийти url — это ссылка на hosted-страницу оплаты. Откройте её в браузере: если страница открылась, приём платежей настроен.
2. Чтобы реально поймать вебхук об оплате на локальной машине, нужен публичный HTTPS-адрес — поднимите туннель (ngrok / cloudflared) и укажите его URL в url_callback. Подробнее — в Тестировании и Настройке вебхуков.

---

​

Вебхуки

Шаг 1. Регистрация (один раз)

endpoint = client.webhooks.register("https://ваш-сайт.ру/oblodai/webhook")
webhook_secret = endpoint.secret  # сохраните — им проверяются вебхуки (не API-секрет!)

Шаг 2. Приём (Flask, сырое тело)

from flask import Flask, request
from oblodai import verify_webhook, OblodaiSignatureError

app = Flask(__name__)

@app.post("/oblodai/webhook")
def webhook():
    raw = request.get_data()  # сырые байты, не request.json!
    if b'"is_test"' in raw:   # тестовые вебхуки не подписаны
        return "", 200
    try:
        # третий аргумент — сами заголовки (mapping); функция сама достанет
        # X-Webhook-Timestamp / X-Webhook-Signature и проверит окно свежести.
        verify_webhook(webhook_secret, raw, request.headers)
    except OblodaiSignatureError:
        return "", 403

    event = request.get_json()
    info = client.payments.info(uuid=event["uuid"])
    if info.payment_status in ("paid", "paid_over"):
        ...  # пометить заказ info.order_id оплаченным (идемпотентно)
    return "", 200

Оплаченными считайте только paid и paid_over.

---

​

Ошибки и повторы

from oblodai import OblodaiAPIError

try:
    client.payouts.create(...)
except OblodaiAPIError as e:
    e.code       # "payout.insufficient_funds" — ветвитесь по коду
    e.status     # HTTP-статус
    e.is_retriable

Клиент сам повторяет 5xx/429/сетевые сбои с backoff и учётом Retry-After — повторы включены по умолчанию. Отключить: retry=None.

Повтор безопасен, но механизм зависит от версии:

	v1.0.x (предыдущая)	v1.1.0 (текущая, в PyPI)
Защита от дублей	order_id: не задали — SDK подставит свой	заголовок Idempotency-Key, одинаковый во всех внутренних повторах
Ваш order_id	если не задан — в платеже будет сгенерированный SDK	уходит как есть, SDK не подставляет и не переписывает
Свой ключ	idempotency_key не существует	можно передать idempotency_key — уйдёт в заголовок

В обеих версиях таймаут/обрыв сети не создаст дубль счёта или перевода. Для выплат order_id обязателен всегда — его задаёте вы (иначе payout.order_id_required).

---

​

Логи и отладка

Включите логи одной переменной окружения — увидите каждый запрос/ответ/ретрай:

export OBLODAI_LOG=debug   # уровни: debug · info · warning · error

Строки идут в stderr с префиксом oblodai: (метод, путь, статус, номер попытки, задержка ретрая). Секреты, подпись и тела запросов в лог не попадают. Вместо переменной можно задать свой логгер: настройте логгер logging.getLogger("oblodai").

Проверяете подпись вебхука статичным (старым) вектором? По умолчанию действует окно свежести 5 минут — старый timestamp отклонит replay-защита (валидная подпись → всё равно ошибка). Для офлайн-проверки задайте окно 0: verify_webhook(secret, raw, headers, max_age_seconds=0).

---

​

Если не получилось

Симптом	Причина и что делать
OblodaiAPIError 401 на каждый вызов	Не заданы OBLODAI_PUBLIC_ID/OBLODAI_SECRET или перепутаны. SDK подписывает сам.
ValueError при from_env()	Обязательная переменная окружения не задана (её имя — в тексте ошибки).
Вебхук не проходит проверку	Нужно сырое тело — request.get_data(), а не request.json; и webhook‑секрет из webhooks.register(), не API‑секрет.
Вебхук вообще не приходит	Не зарегистрировали endpoint (webhooks.register(url)) или сайт недоступен из интернета.
429	SDK повторяет сам с учётом Retry-After. Не поллите payments.info() в цикле. Много операций — шлите их пачкой.

Полная диагностика — Что делать, если не работает.

​

Связанные страницы

Обзор SDK

Приём первого платежа

Настройка вебхуков

Коды ошибок