API реселлера: заказы

Свой сайт на API: клиент платит вам, вы вызываете POST /orders и получаете ключ. Идемпотентность по external_order_id и пополнение ключей.

Схема продажи

1. Клиент платит вам на вашем сайте вашей кассой (OneProvider в этом платеже не участвует).
2. Ваш сервер получил подтверждение оплаты и вызывает POST /orders.
3. OneProvider резервирует лимит ключа на вашем балансе реселлера (деньги спишутся по мере расхода) и создаёт заказ со статусом completed.
4. Вы отдаёте клиенту ключ из ответа и, при желании, ссылку dashboard_url.

Заказ либо выпускает новый ключ (kind: "new_key"), либо пополняет существующий (kind: "topup", если передан key_id).

Создать заказ

Что выдать, задаётся тарифом (plan_id, см. Коды и тарифы ) или напрямую суммой limit_usd и сроком expires_days или expires_hours. Клиента можно указать через customer_id или customer_external_id (клиент, созданный ранее). Поля charged_amount и charged_currency записывают, сколько клиент заплатил вам: они попадают в GET /stats и никак не влияют на списание.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": "<order id>",
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": "sk-..."
}

Секрет key приходит только для нового ключа и только в первом ответе. Сохраните его в той же транзакции, в которой записываете заказ.

Идемпотентность по external_order_id

external_order_id это номер заказа в вашей системе. Повтор запроса с тем же номером и теми же параметрами не выпускает второй ключ и не списывает деньги второй раз: вы получите тот же заказ (уже без секрета ключа). Тот же номер с другими параметрами даёт 409 external_order_id_conflict. Поэтому безопасно повторять запрос после таймаута или обрыва соединения. Найти заказ можно через GET /orders?external_order_id=shop-1042.

Пополнить существующий ключ

Передайте key_id и сумму (limit_usd или тариф):

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

В ответе kind равен topup и секрета нет. Сумма добавляется к общему лимиту ключа и, как всё, должна помещаться в «Свободно» (резервируется, списывается по мере расхода).

Пример обработчика оплаты (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] is present only on the first response of a new_key order
return order

Следите за available_usd и подпишитесь на вебхук balance.low, чтобы пополнять баланс раньше, чем заказ упрётся в 409 insufficient_balance. См. Вебхуки .