Reseller-API: Bestellungen

Bauen Sie Ihren eigenen Shop: Der Kunde bezahlt Sie, Sie rufen POST /orders auf und erhalten einen Schlüssel. Idempotenz über external_order_id und Aufladungen bestehender Schlüssel.

Der Verkaufsablauf

1. Ihr Kunde bezahlt Sie auf Ihrer Website über Ihren eigenen Checkout (OneProvider ist an dieser Zahlung nicht beteiligt).
2. Ihr Server erhält die Zahlungsbestätigung und ruft POST /orders auf.
3. OneProvider reserviert das Schlüssellimit auf Ihrem Reseller-Guthaben (das Geld wird beim Verbrauch abgebucht) und legt eine Bestellung mit dem Status completed an.
4. Sie geben dem Kunden den Schlüssel aus der Antwort und, wenn Sie möchten, die dashboard_url.

Eine Bestellung stellt entweder einen neuen Schlüssel aus (kind: "new_key") oder lädt einen bestehenden auf (kind: "topup", wenn key_id übergeben wird).

Eine Bestellung erstellen

Was geliefert wird, legt ein Tarif fest (plan_id, siehe Codes & Tarife ) oder direkt ein Betrag: limit_usd und expires_days oder expires_hours. Den Kunden können Sie als customer_id oder customer_external_id übergeben (ein früher angelegter Kunde). Die Felder charged_amount und charged_currency halten fest, was der Kunde Ihnen gezahlt hat; sie fließen in GET /stats ein und wirken sich nicht auf die Abbuchung aus.

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": 42,
"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": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key ist das Schlüsselobjekt (wie in der Antwort auf das Ausstellen), das Secret steht in key.key. Es kommt nur bei einem neuen Schlüssel, in der Antwort auf POST /orders (und in einer exakten Wiederholung davon); GET /orders und GET /orders/{id} enthalten es nicht. Speichern Sie das Secret in derselben Transaktion, in der Sie die Bestellung erfassen. Entsteht die Bestellung aus einem Tarif ohne Laufzeit (expires_never), hat der Schlüssel expires_at gleich null.

Idempotenz über external_order_id

external_order_id ist die Bestellnummer in Ihrem System. Wird eine Anfrage mit derselben Nummer und denselben Parametern wiederholt, entsteht kein zweiter Schlüssel und es wird nicht doppelt abgebucht: Sie erhalten dieselbe Bestellung und denselben Schlüssel zurück (mit demselben Secret, sodass sich eine unterwegs verlorene Antwort durch Wiederholen des Aufrufs wiederherstellen lässt). Dieselbe Nummer mit anderen Parametern ergibt 409 external_order_id_conflict. So ist ein erneuter Versuch nach einem Timeout oder einer abgebrochenen Verbindung unbedenklich. Eine Bestellung finden Sie mit GET /orders?external_order_id=shop-1042.

Einen bestehenden Schlüssel aufladen

Übergeben Sie key_id und einen Betrag (limit_usd oder einen Tarif):

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"}'

In der Antwort ist kind gleich topup, und es gibt kein Secret. Der Betrag wird zum Gesamtlimit des Schlüssels addiert und muss wie alles in „Verfügbar“ passen (er wird reserviert und beim Verbrauch abgebucht).

Beispiel für einen Zahlungs-Handler (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"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

Beobachten Sie available_usd und abonnieren Sie den Webhook balance.low, damit Sie aufladen, bevor eine Bestellung auf 409 insufficient_balance stößt. Siehe Webhooks .