Eine API, ein Hosted-Flow
CryptoPayIn bepreist eine Bestellung in Ihrer gewählten Anzeigewährung, sperrt geprüfte Fiat/USD- und Krypto/USD-Kurse, weist eine eigene Einzahlungsadresse zu und überwacht die Zahlung über eigene Blockchain-Nodes. Die interne Buchführung, Gebühren und Guthaben bleiben durchgehend in USD. Ihr Backend erhält sofort eine Checkout-URL und anschließend signierte Lifecycle-Events.
Dies ist eine Live-API. Es gibt kein Sandbox-Präfix. Jede erfolgreiche Erstellung weist eine echte On-Chain-Adresse zu. Verwenden Sie für End-to-End-Tests einen kleinen Betrag in einer unterstützten Währung, und bewahren Sie Secret Keys ausschließlich auf Ihrem Server auf.
So greift die Integration ineinander
Erzeugen Sie einmalig ein Secret unter Dashboard -> Entwickler.
Senden Sie Bestellwährung, Betrag und gewähltes Asset per POST.
Leiten Sie den Kunden zur zurückgegebenen Hosted-URL weiter.
Prüfen Sie den HMAC und aktualisieren Sie Ihre Bestellung idempotent.
Ihre erste Zahlung erstellen
Erzeugen Sie einen API-Schlüssel im Händler-Dashboard, speichern Sie das Secret in einer Umgebungsvariable und erstellen Sie anschließend eine Zahlung von Ihrem Backend aus. Das Beispiel verwendet ETH, damit es getestet werden kann, ohne ein Token-Netzwerk auswählen zu müssen.
curl --request POST https://cryptopayin.com/v1/payments \
--header "Authorization: Bearer $CPI_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: order_1042" \
--data '{
"amount": 49.99,
"currency": "USD",
"asset": "ETH",
"order_ref": "order_1042",
"redirect_url": "https://shop.example/orders/1042/paid"
}'
const response = await fetch("https://cryptopayin.com/v1/payments", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.CPI_SECRET_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "order_1042"
},
body: JSON.stringify({
amount: 49.99, currency: "USD", asset: "ETH",
order_ref: "order_1042",
redirect_url: "https://shop.example/orders/1042/paid"
})
});
if (!response.ok) throw new Error(await response.text());
const payment = await response.json();
$payload = json_encode([
'amount' => 49.99, 'currency' => 'USD', 'asset' => 'ETH',
'order_ref' => 'order_1042',
'redirect_url' => 'https://shop.example/orders/1042/paid',
]);
$ch = curl_init('https://cryptopayin.com/v1/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CPI_SECRET_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order_1042',
],
]);
$payment = json_decode(curl_exec($ch), true, flags: JSON_THROW_ON_ERROR);
import os, requests
response = requests.post(
"https://cryptopayin.com/v1/payments",
headers={
"Authorization": f"Bearer {os.environ['CPI_SECRET_KEY']}",
"Idempotency-Key": "order_1042",
},
json={
"amount": 49.99, "currency": "USD", "asset": "ETH",
"order_ref": "order_1042",
"redirect_url": "https://shop.example/orders/1042/paid",
}, timeout=15,
)
response.raise_for_status()
payment = response.json()Antwort weiterverwenden
Speichern Sie die id der Zahlung zusammen mit Ihrer Bestellung, und leiten Sie den Kunden anschließend an checkout_url weiter. Berechnen Sie Krypto-Betrag oder Einzahlungsadresse niemals selbst.
{
"id": "P-9F27C1E4KD",
"object": "payment",
"status": "created",
"amount": 49.99,
"amount_decimal": "49.99",
"amount_minor": 4999,
"currency": "USD",
"currency_minor_units": 2,
"amount_usd": 49.99,
"amount_usd_cents": 4999,
"fx_rate_usd": "1.000000000000",
"fx_source": "fixed:USD",
"fx_observed_at": "2026-07-17T13:00:00+00:00",
"fx_discrepancy_bps": 0,
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0",
"deposit_address": "0x71b8c3d4700000000000000000000000000084e2",
"exchange_rate": "3600.00000000",
"exchange_rate_currency": "USD",
"exchange_rate_source": "median:cb,cg,cl",
"exchange_rate_source_count": 3,
"exchange_rate_observed_at": "2026-07-17T13:00:00+00:00",
"exchange_rate_discrepancy_bps": 12,
"confirmations": 0,
"confirmations_required": 12,
"order_ref": "order_1042",
"checkout_url": "https://cryptopayin.com/i/P-9F27C1E4KD",
"expires_at": "2026-07-17T13:30:00+00:00",
"created_at": "2026-07-17T13:00:00+00:00",
"completed_at": null
}Authentifizierung
Jede API-Anfrage verwendet den Secret Key in einem HTTP-Bearer-Header. Secret Keys beginnen mit csk_live_. Der zugehörige cpk_live_-Wert ist eine öffentliche Kennung für Ihr Dashboard und darf nicht als Bearer-Anmeldedaten verwendet werden.
Authorization: Bearer csk_live_...Jeder EndpunktDas unverschlüsselte Secret wird nur bei der Erstellung des Schlüssels zurückgegeben. CryptoPayIn speichert einen Passwort-Hash sowie einen indizierten SHA-256-Lookup, niemals das Secret im Klartext.
Legen Sie pro Anwendung oder Umgebung einen eigenen Schlüssel an und widerrufen Sie diese unabhängig voneinander. Ein Konto kann bis zu 50 aktive Schlüssel besitzen.
Platzieren Sie einen csk_live_-Wert niemals in Browser-JavaScript, einer mobilen Binärdatei, einem öffentlichen Repository oder einer Checkout-Seite.
Ein Webhook-Endpunkt kann kontoweit gelten oder an einen einzelnen API-Schlüssel gebunden sein, sodass Integrationen voneinander getrennt bleiben.
Ein fehlendes, fehlerhaftes, widerrufenes oder unbekanntes Secret liefert 401 unauthorized. Ein gesperrtes oder geschlossenes Händlerkonto wird ebenso abgelehnt. Ein gültiger Schlüssel, der außerhalb seiner erteilten Berechtigungen verwendet wird, liefert 403 insufficient_scope.
Idempotenz
Senden Sie bei jeder Zahlungserstellung einen eindeutigen Idempotency-Key. Bricht Ihre Verbindung nach dem Absenden ab, wiederholen Sie dasselbe JSON mit demselben Schlüssel: CryptoPayIn gibt dann die ursprüngliche Zahlung zurück, statt eine weitere Adresse zuzuweisen.
| Fall | Ergebnis | HTTP |
|---|---|---|
| Erste Verwendung | Erstellt eine neue Zahlung und gibt sie zurück. | 201 |
| Gleicher Schlüssel + gleiches JSON | Gibt die bestehende Zahlung mit Idempotent-Replayed: true zurück. | 200 |
| Gleicher Schlüssel + abweichendes JSON | Weist die Anfrage als idempotency_conflict zurück. | 409 |
Schlüssel gelten jeweils für die API-Anmeldedaten und dürfen 1-128 Buchstaben, Ziffern, Punkte, Unterstriche, Doppelpunkte oder Bindestriche enthalten. Eine dauerhafte Bestell-UUID ist eine gute Wahl. Derselbe Mechanismus schützt auch Auszahlungen, sodass eine wiederholte Auszahlung niemals doppelt Guthaben bewegen kann.
API-Referenz
Die API deckt Zahlungen, Zahlungslinks, Shops, Produkte, Guthaben und Auszahlungen ab. Antworten verwenden UTF-8-JSON über HTTPS; jede Erstellung oder Aktualisierung erfordert Content-Type: application/json. Änderungen werden durch die Berechtigungen des aufrufenden Schlüssels kontrolliert. Ein Browser-CORS-Workflow ist bewusst nicht vorgesehen: Aufrufe gehören auf Ihr Backend.
/v1/assetsVerfügbare Assets ermitteln/v1/currenciesFiat-Anzeigewährungen ermitteln/v1/paymentsZahlung erstellen/v1/paymentsZahlungen auflisten und filtern/v1/payments/{id}Zahlung abrufenVersion 1 kann abwärtskompatible Felder und Endpunkte erhalten. Eine Breaking Change am Vertrag erfolgt über einen neuen Basispfad, statt /v1 stillschweigend zu ändern.
Assets auflisten
/v1/assetsBearer-Authentifizierung erforderlichVerwenden Sie diesen Endpunkt als maßgebliche Quelle für die Auswahl im Checkout. Er liefert aktivierte Katalogeinträge, aktuell unabhängig geprüfte Kurse, USD-Mindestbeträge sowie den Status, ob Node und Preis-Feed bereit sind. Ein Eintrag kann mit available: false gelistet bleiben, während ein Node synchronisiert oder sein Preis nicht verifiziert werden kann.
curl https://cryptopayin.com/v1/assets \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"data": [{
"asset": "USDT",
"network": "TRC20",
"type": "token",
"decimals": 6,
"minimum_amount": 1,
"currency": "USD",
"base_confirmations": 19,
"available": true,
"rate_usd": "1.00000000",
"rate_source": "median:cb,cg,cl",
"rate_source_count": 3,
"rate_discrepancy_bps": 4,
"rate_status": "healthy",
"rate_updated_at": "2026-07-17T13:00:00+00:00"
}]
}Katalog- und Netzwerkkennungen
| Asset | Netzwerkwert | Kurzform | Basis-Bestätigungen |
|---|---|---|---|
| BTC | mainnet | BTC | 2 |
| ETH | mainnet | ETH | 6 |
| USDT | TRC20 / ERC20 | USDT.TRC20 | 19 / 6 |
| USDC | ERC20 | USDC.ERC20 | 6 |
| DAI | ERC20 | DAI | 6 |
| SHIB | ERC20 | SHIB | 6 |
| PEPE | ERC20 | PEPE | 6 |
| LTC | mainnet | LTC | 6 |
| TRX | mainnet | TRX | 19 |
| DOGE | mainnet | DOGE | 20 |
| XMR | mainnet | XMR | 10 |
| SOL | mainnet | SOL | 32 |
Die Verfügbarkeit ist dynamisch. Verwenden Sie die obige Tabelle nicht fest codiert als Live-Allowlist. Senden Sie bei Symbolen mit mehreren Netzwerken wie USDT explizit network oder verwenden Sie die Kurzform ASSET.NETWORK.
Fiat-Währungen auflisten
/v1/currenciesBearer-Authentifizierung erforderlichLiefert die aktivierten Anzeigewährungen, deren ISO-Genauigkeit und den aktuellen Status der USD-Umrechnung. Bieten Sie nur Zeilen mit available: true an. USD ist intrinsisch; jede andere Währung benötigt einen aktuellen Live-Kurs und eine unabhängige Referenzprüfung. minimum_amount rechnet die niedrigste konfigurierte Mindestgrenze eines aktivierten Assets in diese Währung um; das gewählte Asset kann einen höheren Betrag erfordern, lesen Sie daher stets auch GET /v1/assets.
curl https://cryptopayin.com/v1/currencies \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"accounting_currency": "USD",
"data": [{
"currency": "EUR",
"name": "Euro",
"symbol": "€",
"minor_units": 2,
"available": true,
"minimum_amount": "0.86",
"rate_usd": "1.160000000000",
"rate_source": "coinbase+ecb",
"rate_source_count": 2,
"rate_discrepancy_bps": 18,
"rate_updated_at": "2026-07-17T13:00:00+00:00",
"rate_reference_at": "2026-07-16T00:00:00+00:00"
}]
}Fehlt die Währung bei POST /v1/payments, bedeutet dies aus Gründen der Abwärtskompatibilität weiterhin USD. Währungen ohne Dezimalstellen wie JPY lehnen gebrochene Beträge ab. Behandeln Sie Katalog-Mindestbeträge und -Kurse stets als Live-Daten, niemals als fest codierte Konstanten.
Zahlung erstellen
/v1/payments120 Anfragen / Minute / SchlüsselErstellt eine Rechnung in der angeforderten Anzeigewährung, sperrt aktuelle geprüfte Fiat/USD- und Krypto/USD-Kurse, berechnet den exakten Krypto-Betrag und bindet eine eigene On-Chain-Einzahlungsadresse.
Request-Body
| Feld | Typ | Anforderung | Beschreibung |
|---|---|---|---|
| amount | Zahl oder Dezimal-String | erforderlich | Wert in currency, mit der ISO-Genauigkeit dieser Währung. Der gesperrte USD-Gegenwert darf $1,000,000.00 nicht überschreiten; zusätzlich gelten die Asset-Mindestbeträge. |
| currency | string | optional | Aktivierte 3-stellige Währung aus GET /v1/currencies. Standardwert: USD. |
| asset | string | erforderlich | Symbol wie ETH oder Kurzform wie USDT.TRC20. |
| network | string | bedingt | Erforderlich, wenn ein Symbol in mehreren Netzwerken existiert. Beispiel: ERC20. |
| order_ref | string | optional | Ihre Bestellkennung, maximal 128 Zeichen. Wird in API-Antworten und Events zurückgegeben. |
| customer_email | string | optional | Gültige E-Mail-Adresse, maximal 190 Zeichen. Wird im Zahlungsdatensatz des Händlers gespeichert. |
| redirect_url | string | optional | HTTPS-URL, maximal 255 Zeichen, wird nach erfolgreichem Checkout angeboten. |
Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
| id | string | Stabile Zahlungskennung, beginnend mit P-. |
| status | string | Aktueller Lifecycle-Status. |
| amount / amount_decimal / amount_minor | number / string / integer | Angeforderter Anzeigewert in praktischer, exakter Dezimal- und ISO-Untereinheiten-Form. |
| currency / currency_minor_units | string / integer | Gesperrte Anzeigewährung und ihre Genauigkeit. |
| amount_usd / amount_usd_cents | number / integer | Unveränderlicher interner USD-Buchungswert. |
| fx_rate_usd / fx_source / fx_observed_at | decimal string / string / ISO 8601 | Gesperrter USD-Kurs pro Einheit der Anzeigewährung samt Audit-Metadaten. |
| asset / network | string | Aufgelöstes On-Chain-Asset. |
| crypto_amount | decimal string | Exakter Betrag, den der Kunde senden muss. Krypto-Dezimalwerte niemals als binäre Fließkommazahlen parsen. |
| crypto_received | decimal string | Aktuell an der Einzahlungsadresse beobachtete Gesamtsumme. |
| deposit_address | string | Für diese Zahlung zugewiesene eigene Adresse. |
| exchange_rate | decimal string | Gesperrter Krypto/USD-Kurs, der zur Berechnung von crypto_amount verwendet wird; dieses Feld behält seine ursprüngliche v1-Bedeutung. |
| exchange_rate_source / exchange_rate_observed_at | string / ISO 8601 | Unveränderlicher Audit-Snapshot des Krypto-Kurses. |
| confirmations | integer | Aktuelle Netzwerkbestätigungen. |
| confirmations_required | integer | Schwellenwert für diese Zahlung. Höhere USD-Stufen können zusätzliche Bestätigungen erfordern. |
| checkout_url | URL | Hosted-Rechnung zur Anzeige für den Kunden. |
| expires_at | ISO 8601 | Frist für eine unbezahlte Rechnung. |
| completed_at | ISO 8601 / null | Endgültiger Abwicklungszeitpunkt bei Abschluss. |
Beide Live-Umrechnungen werden vor der Erstellung auf Aktualität, Quellenanzahl und Abweichung geprüft. Schlägt die Prüfung fehl, liefert die Erstellung einen Fehler, statt einen veralteten Kurs zu verwenden. Der Krypto-Betrag wird auf eine sinnvolle Asset-Genauigkeit aufgerundet, sodass die Rundung den Händler niemals benachteiligt.
Zahlungen auflisten
/v1/payments240 Anfragen / Minute / SchlüsselGibt für das authentifizierte Händlerkonto die neuesten Zahlungen zuerst zurück. Verwenden Sie Cursor-Paginierung für den Abgleich und exakte Filter, um eine Bestellung zu finden, ohne den gesamten Verlauf zu durchlaufen.
Query-Parameter
| Parameter | Standard | Beschreibung |
|---|---|---|
| limit | 20 | Seitengröße von 1 bis 100. |
| starting_after | — | Zahlungs-ID aus dem next_cursor der vorherigen Seite. |
| status | — | Exakter Lifecycle-Status wie pending, completed oder expired. |
| order_ref | — | Exakte Bestellreferenz des Händlers, maximal 128 Zeichen. |
curl "https://cryptopayin.com/v1/payments?status=completed&limit=20" \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"data": [{
"id": "P-9F27C1E4KD",
"object": "payment",
"status": "completed",
"amount": 49.99,
"currency": "USD",
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0.01388612",
"order_ref": "order_1042",
"confirmations": 12,
"confirmations_required": 12,
"completed_at": "2026-07-17T13:12:42+00:00"
}],
"has_more": true,
"next_cursor": "P-9F27C1E4KD"
}Ist has_more gleich true, übergeben Sie next_cursor unverändert als starting_after. Unbekannte oder wiederholte array-artige Query-Parameter werden abgelehnt statt ignoriert.
Zahlung abrufen
/v1/payments/{id}240 Anfragen / Minute / SchlüsselGibt dasselbe Zahlungsobjekt wie bei der Erstellung zurück, mit aktuellem Status, empfangenem Betrag, Transaktions-Hash und Bestätigungen. Ein Schlüssel kann nur Zahlungen abrufen, die zu seinem Händlerkonto gehören.
curl https://cryptopayin.com/v1/payments/P-9F27C1E4KD \
--header "Authorization: Bearer $CPI_SECRET_KEY"Webhooks sollten reguläre Bestell-Updates steuern. Nutzen Sie den Abruf zum Abgleich nach einem Timeout, zur Verifikation eines Events, zur Darstellung einer Backend-Statusseite oder zur Behebung ausgebliebener Zustellungen.
Zahlungslebenszyklus
Behandeln Sie stets den API-Status als maßgeblich. Schließen Sie niemals aus einer Browser-Weiterleitung oder der Aussage des Kunden, er habe bezahlt, auf den Abschluss.
| Status | Bedeutung | Aktion des Händlers |
|---|---|---|
| created | Rechnung und Adresse zugewiesen; noch keine Zahlungseingänge erkannt. | Hosted Checkout anzeigen. |
| pending | Wartet auf eine verwertbare On-Chain-Zahlung. | Bestellung offen halten. |
| underpaid | Eingegangene Mittel liegen unter der Toleranz des Händlers. | Zahler bitten, den angezeigten Restbetrag zu senden. |
| confirming | Ausreichender Wert erkannt; wartet auf Bestätigungen. | Noch nicht ausliefern. |
| completed | Erforderlicher Wert und Bestätigungen erreicht. | Genau einmal ausliefern. |
| overpaid | Mehr als erwartet wurde bestätigt. | Ausliefern und den Überschuss prüfen. |
| expired | Vor Ablauf wurde keine ausreichende Zahlung erkannt. | Neue Zahlung erstellen. |
| failed | Adresszuweisung oder Verarbeitung fehlgeschlagen. | Fehler protokollieren und neue Zahlung erstellen. |
On-Chain-Übertragungen sind unumkehrbar, und CryptoPayIn verfügt über keinen Rückerstattungsmechanismus — eine bestätigte Zahlung ist endgültig. Eine Kulanzrückzahlung wird direkt zwischen Ihnen und Ihrem Kunden abgewickelt, außerhalb der Plattform.
Hosted Checkout
Jede API-Zahlung enthält eine responsive checkout_url. Sie zeigt den Händler, den angeforderten Anzeigebetrag, bei Relevanz den gesperrten USD-Gegenwert, den exakten Krypto-Betrag, die Einzahlungsadresse, den QR-Code, eine Netzwerkwarnung, einen Countdown und den Live-Fortschritt der Bestätigungen.
Der Kunde sieht für das Rechnungsfenster denselben crypto_amount, den die API zurückgegeben hat.
Der Zahler erstellt kein CryptoPayIn-Konto und gibt keine Zugangsdaten preis.
Die Seite fragt die Zahlung sicher ab und wechselt von wartend über bestätigend zu bezahlt.
Nach erfolgreichem Abschluss wird eine HTTPS-redirect_url angeboten; sie ist kein Zahlungsnachweis.
Die Auslieferung sollte stets auf Ihrem Backend erfolgen. Browser-Navigation kann abgebrochen, wiederholt oder gefälscht werden; nur ein verifizierter Webhook oder ein authentifiziertes GET belegt den Zahlungsstatus.
Berechtigungen & Scopes
Jeder API-Schlüssel trägt einen festen Satz an Berechtigungen, den Sie bei seiner Erstellung unter Dashboard → Entwickler festlegen. Jeder Endpunkt prüft die Scopes des Schlüssels, bevor er tätig wird; ein Aufruf außerhalb der Berechtigung eines Schlüssels liefert 403 insufficient_scope mit einem X-Required-Scope-Header, der die fehlende Berechtigung benennt. Scopes werden einmalig bei der Erstellung festgelegt und können später nicht erweitert werden — stellen Sie stattdessen einen neuen Schlüssel aus. Schlüssel, die vor Einführung der Scopes erstellt wurden, behalten genau ihre ursprüngliche Fähigkeit: payments:read und payments:write.
| Scope | Gewährt | Endpunkte |
|---|---|---|
payments:read | Zahlungen auflisten und abrufen | GET /v1/payments, GET /v1/payments/{id} |
payments:write | Hosted-Zahlungen erstellen | POST /v1/payments |
links:read | Zahlungslinks auflisten und abrufen | GET /v1/links, GET /v1/links/{id} |
links:write | Zahlungslinks erstellen, bearbeiten, pausieren und löschen | POST/PATCH/DELETE /v1/links |
shops:read | Shops und deren Produkte auflisten und abrufen | GET /v1/shops, GET .../products |
shops:write | Shops, Produkte und Varianten erstellen und bearbeiten | POST/PATCH/DELETE /v1/shops und Produkte |
balance:read | Krypto-Guthaben und USD-Schätzungen lesen | GET /v1/balance |
payouts:read | Auszahlungen auflisten und abrufen | GET /v1/payouts, GET /v1/payouts/{id} |
payouts:write | On-Chain-Auszahlungen anfordern | POST /v1/payouts |
payouts:write bewegt Guthaben on-chain und ist unumkehrbar. Erteilen Sie diese Berechtigung nur Schlüsseln, denen Sie voll vertrauen, bewahren Sie diese Schlüssel serverseitig auf, und bevorzugen Sie pro automatisiertem Prozess einen eigenen Schlüssel. GET /v1/account meldet die Scopes des aufrufenden Schlüssels sowie Ihre Kontolimits.
Zahlungslinks
Wiederverwendbare Hosted-Links, die ein Kunde beliebig oft bezahlen kann. Ein Link nutzt dieselbe Logik für Preise, Asset, Auslieferung und Checkout-Fragen wie der Link-Builder im Dashboard — die API steuert sie lediglich. Ein Konto kann bis zu 50 Zahlungslinks halten.
/v1/linkslinks:read/v1/linkslinks:write/v1/links/{id}links:read/v1/links/{id}links:write/v1/links/{id}links:writeRequest-Body
| Feld | Typ | Anforderung | Beschreibung |
|---|---|---|---|
| title | string | erforderlich | 3–120 Zeichen. |
| description | string | optional | Bis zu 2,000 Zeichen, wird im Checkout angezeigt. |
| template | string | optional | Checkout-Theme: signature (Standard), midnight, atelier, horizon, compact oder ledger. |
| public_label | string | optional | Öffentlicher Verkäufername, der Käufern angezeigt wird (2–80 Zeichen). Niemals eine Konto-ID. |
| amount_type | string | optional | fixed (Standard) oder open (Kunde wählt innerhalb von min/max). |
| currency | string | optional | Anzeigewährung aus GET /v1/currencies. Standardmäßig Ihre Kontowährung. |
| amount | number or string | bedingt | Erforderlich für fixed. In currency mit dessen ISO-Genauigkeit. |
| min / max | number or string | bedingt | Grenzwerte für open-Links. max kann 0 sein oder weggelassen werden, um keine Obergrenze zu setzen. |
| accepted_assets | array of strings | optional | Asset-Codes wie ["BTC","USDT.TRC20"]. Weglassen für alle verfügbaren Assets. |
| max_uses | integer | optional | Obergrenze abgeschlossener Zahlungen. 0 bedeutet unbegrenzt. |
| expires_at | ISO 8601 | optional | Mindestens 5 Minuten in der Zukunft, höchstens 12 Monate. UTC. |
| delivery_type | string | optional | none, text, url oder keys — digitale Güter, die nach Zahlung ausgeliefert werden. |
| delivery_text / delivery_url | string | bedingt | Inhalt (≤50,000 Zeichen) oder eine https-URL für den passenden Auslieferungstyp. |
| delivery_keys | array of strings | bedingt | Ein Schlüssel pro Element für die Auslieferung keys. Bis zu 10,000, jeweils ≤500 Zeichen. |
| checkout_fields | array | optional | Bis zu 5 Objekte {label, type, required}; Typ ist text, email, textarea oder number. |
| success_message / redirect_url | string | optional | Nachricht nach der Zahlung (≤500 Zeichen) sowie eine https-Weiterleitung. |
| status | string | optional | Nur PATCH: active oder paused. |
curl -X POST https://cryptopayin.com/v1/links \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Pro license",
"amount": 49.99,
"currency": "EUR",
"accepted_assets": ["BTC", "ETH", "USDT.TRC20"],
"delivery_type": "keys",
"delivery_keys": ["ABC-1", "ABC-2", "ABC-3"]
}'{
"id": "PL-N5PKTYB7",
"object": "payment_link",
"url": "https://cryptopaylink.co/pay/PL-N5PKTYB7",
"status": "active",
"title": "Pro license",
"amount_type": "fixed",
"currency": "EUR",
"amount": 49.99,
"amount_decimal": "49.99",
"accepted_assets": [{"asset":"BTC","network":"mainnet"},{"asset":"ETH","network":"mainnet"},{"asset":"USDT","network":"TRC20"}],
"uses": {"started": 0, "completed": 0, "in_flight": 0},
"delivery": {"type": "keys", "keys_available": 3, "keys_total": 3},
"expires_at": null,
"created_at": "2026-07-19T19:00:00+00:00"
}PATCH ist ein Teil-Update: Senden Sie nur die geänderten Felder, der Rest bleibt erhalten, einschließlich nicht verkaufter Lizenzschlüssel. Bei keys-Links ersetzt das Senden von delivery_keys den Pool der unverkauften Schlüssel; bereits ausgelieferte Schlüssel werden nie angetastet. Das Löschen eines Links mit vorhandenen Zahlungen wird implizit verweigert, da dessen Historie erhalten bleibt.
Agent-Checkout
Jeder aktive Zahlungslink ist zugleich ein maschinenlesbarer Checkout: Ein KI-Agent oder ein beliebiges Skript kann ihn erkennen, eine Rechnung erstellen und die Auslieferung ohne Browser auslesen — und ohne jeden API-Schlüssel, da es sich um öffentliche Käufer-Endpunkte auf der Link-Domain handelt, nicht um Händler-Endpunkte. Vollständiger Vertrag und ausgearbeitetes Beispiel: cryptopayin.com/agents.
https://cryptopaylink.co/pay/{link}.jsonöffentlich · DiscoveryLiefert Status, Preise, akzeptierte Assets und den exakten Eingabevertrag für den Rechnungsaufruf (Pflichtfelder, Versandschema, Varianten).
https://cryptopaylink.co/pay/{link}/invoiceöffentlich · unterstützt Idempotency-KeyErstellt die Rechnung über denselben Kern, Preis-Snapshot und dieselben Anti-Abuse-Limits wie die Hosted-Seite und liefert die Einzahlungsadresse, den exakten Krypto-Betrag, eine Wallet-URI und die Beleg-URL zurück. Der Agent bezahlt anschließend on-chain aus einem beliebigen von ihm kontrollierten Wallet.
https://cryptopaylink.co/pay/{link}/receipt?p={payment}öffentlich · Abfrage alle 5–10 sLive-Status und Bestätigungen; sobald die Zahlung abgeschlossen ist, enthält die Antwort die Auslieferung — Ihren Textinhalt, eine private URL oder einen für diese Zahlung reservierten Lizenzschlüssel — sowie Ihre Erfolgsmeldung und Weiterleitungs-URL.
Shops sprechen dasselbe Protokoll
Storefronts stellen auf ihrer eigenen Domain denselben Ablauf bereit: den Katalog mit Live-Bestand, gefolgt von einem einzigen Aufruf, der den Warenkorb validiert, den Bestand reserviert und die Rechnung zurückgibt.
https://shopycrypto.com/s/{shop}.jsonöffentlich · Kataloghttps://shopycrypto.com/s/{shop}/orderöffentlich · Warenkorb → Rechnung, unterstützt Idempotency-Keyhttps://shopycrypto.com/s/{shop}/o/{order}/receipt?p={payment}öffentlich · Abfrage alle 5–10 sVerkäufereinstellungen
Agent-Checkout ist standardmäßig aktiviert und kostet dieselbe pauschale 1%-Gebühr. Deaktivieren Sie ihn kontoweit unter Dashboard → Einstellungen → Allgemein → KI & Agent-Checkout: Maschinen-Endpunkte auf Links und Shops antworten dann mit 403 agents_disabled, während Ihre menschlichen Checkout-Seiten weiter funktionieren. Von Agenten erstellte Zahlungen tragen kein besonderes Kennzeichen — sie sind gewöhnliche Zahlungen in Ihrem Dashboard, Webhooks und Exporten.
Shops
Ein Hosted-Storefront, das Produkte auf einer gebrandeten Seite bündelt. Ein Konto kann bis zu 10 Shops halten. Produkte werden über die nachfolgenden verschachtelten Produkt-Endpunkte verwaltet.
/v1/shopsshops:read/v1/shopsshops:write/v1/shops/{id}shops:read/v1/shops/{id}shops:write/v1/shops/{id}shops:writeRequest-Body
| Feld | Typ | Anforderung | Beschreibung |
|---|---|---|---|
| name | string | erforderlich | 2–80 Zeichen. |
| tagline | string | optional | Bis zu 160 Zeichen. |
| theme | string | optional | light (Standard) oder dark. |
| accent | string | optional | Hex-Akzentfarbe aus der Shop-Palette, zurückgegeben als accent_palette bei GET /v1/shops. |
| accepted_assets | array of strings | optional | Standard-Assets für die Produkte des Shops, z. B. ["BTC","LTC","XMR"]. Wird bei Änderung auf alle Produkte angewendet. |
| status | string | optional | Nur PATCH: active oder paused. |
Ein von CryptoPayIn aus Richtliniengründen deaktivierter Shop kann über die API weder reaktiviert noch gelöscht werden und liefert admin_disabled (403). Das Löschen eines Shops entfernt dessen Produkte; vergangene Zahlungen bleiben unberührt.
Produkte & Varianten
Produkte gehören zu einem Shop. Jeder Shop kann bis zu 50 Produkte enthalten. Ein Produkt kann digital (mit sofortiger Auslieferung) oder physisch (mit Versandländern) sein und bis zu 30 Variantenkombinationen aus 1–3 Optionsgruppen anbieten.
/v1/shops/{shop}/productsshops:read/v1/shops/{shop}/productsshops:write/v1/shops/{shop}/products/{id}shops:read/v1/shops/{shop}/products/{id}shops:write/v1/shops/{shop}/products/{id}shops:writeRequest-Body
| Feld | Typ | Anforderung | Beschreibung |
|---|---|---|---|
| title | string | erforderlich | 3–120 Zeichen. |
| description / blurb | string | optional | Vollständige Beschreibung sowie eine ≤200-Zeichen-Zeile für die Shop-Karte. |
| emoji | string | optional | Einzelnes Emoji, das auf der Produktkarte angezeigt wird. |
| featured | boolean | optional | Höchstens ein hervorgehobenes Produkt pro Shop. |
| product_type | string | optional | digital (Standard) oder physical. |
| shipping_countries | array of strings | bedingt | Nur physisch: ISO-Codes wie ["FR","BE"], oder ["*"] für weltweit. |
| amount_type / currency / amount / min / max | mixed | bedingt | Basispreisgestaltung, identische Regeln wie bei Zahlungslinks. Physische Produkte müssen fixed sein. |
| max_uses | integer | optional | Gesamt-Verkaufsobergrenze (0 = unbegrenzt). |
| delivery_type + delivery_text/url/keys | mixed | optional | Digitale Auslieferung für das Basisprodukt, gleiche Struktur wie bei Zahlungslinks. |
| variant_options | array | optional | 1–3 Gruppen {name, values[]}, jeweils 2–10 Werte. Die Kombinationen dürfen 30 nicht überschreiten. |
| variants | array | bedingt | Ein Objekt pro Kombination (siehe unten). Erforderlich und vollständig, wenn variant_options vorhanden ist. |
| status | string | optional | Nur PATCH: active oder paused. |
Varianten-Objekt
| Feld | Typ | Beschreibung |
|---|---|---|
| options | array of strings | Ein Wert pro Optionsgruppe, in Gruppenreihenfolge, z. B. ["Pro","Lifetime"]. |
| price | number or string | Variantenpreis in der Produktwährung. |
| stock | integer or null | Verbleibende Einheiten, oder null für unbegrenzt. |
| delivery_type + delivery_text/url/keys | mixed | Optionale, variantenspezifische Überschreibung der digitalen Auslieferung (standardmäßig inherit). Schlüssel müssen über das gesamte Produkt hinweg eindeutig sein. |
curl -X POST https://cryptopayin.com/v1/shops/SH-JYRK8TFJ/products \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Software license",
"amount": 30,
"currency": "USD",
"variant_options": [
{"name": "Edition", "values": ["Standard", "Pro"]},
{"name": "Term", "values": ["1 year", "Lifetime"]}
],
"variants": [
{"options": ["Standard","1 year"], "price": 30, "delivery_type": "keys", "delivery_keys": ["S1Y-1"]},
{"options": ["Standard","Lifetime"], "price": 79, "stock": 10, "delivery_type": "keys", "delivery_keys": ["SLT-1"]},
{"options": ["Pro","1 year"], "price": 59, "delivery_type": "keys", "delivery_keys": ["P1Y-1"]},
{"options": ["Pro","Lifetime"], "price": 149, "stock": 5, "delivery_type": "keys", "delivery_keys": ["PLT-1"]}
]
}'PATCH bewahrt bestehende Bestellungen und ausgelieferte Schlüssel. Um Preise oder Bestand anzupassen, senden Sie das passende variants-Array erneut; ausgelassene Kombinationen werden pausiert, falls Bestellungen vorliegen, andernfalls entfernt. Ein Produkt kann über Basis und Varianten hinweg höchstens 10,000 aktive Lizenzschlüssel halten, und jeder Schlüssel muss innerhalb des Produkts eindeutig sein.
Guthaben
/v1/balancebalance:readLiefert Ihre abgewickelten Krypto-Guthaben pro Asset mit einer bestmöglichen USD-Schätzung sowie der bei einer Auszahlung berechneten Netzwerkgebühr. Die interne Buchführung erfolgt stets in USD; Guthaben entstehen aus abgeschlossenen Zahlungen abzüglich der Händlergebühr.
{
"object": "list",
"accounting_currency": "USD",
"minimum_payout_usd": 25,
"data": [{
"asset": "USDT",
"network": "TRC20",
"amount": "99.099",
"usd_estimate": 99.02,
"payout_network_fee": "2.445463"
}]
}usd_estimate ist null, wenn ein verifizierter Live-Kurs momentan nicht verfügbar ist; das zugrunde liegende Guthaben bleibt dennoch exakt. Verwenden Sie diese Werte, um über Auszahlungen zu entscheiden, nicht für die endgültige Buchführung.
Auszahlungen
Bewegt abgewickeltes Krypto-Guthaben zu einem externen Wallet. Auszahlungen sind unumkehrbar, daher erzwingt dieser Endpunkt dieselben Sicherungen wie das Dashboard: ein gültiges Ziel für das Asset, einen verifizierten Live-Kurs, den Kontomindestbetrag, ausreichendes Guthaben einschließlich der Netzwerkgebühr sowie eine Zwei-Faktor-Bestätigung, wenn 2FA für Ihr Konto aktiviert ist.
/v1/payoutspayouts:read/v1/payoutspayouts:write · 30 / Min. / Schlüssel/v1/payouts/{id}payouts:readRequest-Body
| Feld | Typ | Anforderung | Beschreibung |
|---|---|---|---|
| asset | string | erforderlich | Symbol oder Kurzform, z. B. LTC oder USDT.TRC20. |
| network | string | bedingt | Erforderlich, wenn das Symbol in mehreren Netzwerken existiert. |
| amount | number or string | erforderlich | Zu sendender Betrag, ohne Netzwerkgebühr, mit der Genauigkeit des Assets. Sein USD-Wert muss den Kontomindestbetrag erreichen. |
| address | string | erforderlich | Zieladresse, validiert für die Chain des Assets. |
| note | string | optional | Ihre eigene Referenz, bis zu 255 Zeichen. |
| totp_code | string | bedingt | Aktueller 6-stelliger Code oder Recovery-Code. Erforderlich, wenn 2FA für das Konto aktiviert ist. |
curl -X POST https://cryptopayin.com/v1/payouts \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: withdraw-2026-07-19-01" \
-d '{
"asset": "USDT.TRC20",
"amount": "50",
"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"note": "weekly settlement"
}'{
"id": "W-EM64ZCJB",
"object": "payout",
"status": "requested",
"asset": "USDT",
"network": "TRC20",
"amount": "50",
"fee": "2.445463",
"total_debited": "52.445463",
"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": null,
"confirmations": 0,
"created_at": "2026-07-19T19:10:00+00:00"
}Status-Lebenszyklus
| Status | Bedeutung |
|---|---|
requested | Aus Ihrem Guthaben reserviert; wartet auf Prüfung durch den Betreiber oder automatische Freigabe. |
approved / processing | Freigegeben und zur Übertragung durch den Executor eingereiht. |
sent | On-Chain übertragen; txid ist befüllt. |
confirmed | Hat die erforderlichen Bestätigungen erreicht. Endgültig. |
failed | Konnte nicht gesendet werden; failure_message erläutert den Grund, und das Guthaben wird zurückerstattet. |
cancelled | Vor der Übertragung storniert; das reservierte Guthaben wird zurückerstattet. |
Senden Sie einen Idempotency-Key, damit eine Netzwerkwiederholung niemals eine zweite Auszahlung erzeugen kann: Derselbe Schlüssel mit demselben Body liefert die ursprüngliche Auszahlung zurück (Idempotent-Replayed: true); derselbe Schlüssel mit abweichendem Body liefert 409 idempotency_conflict. Der 2FA-Code ist bewusst vom Idempotenz-Fingerabdruck ausgeschlossen, damit ein rotierender Code keinen falschen Konflikt auslöst. Die Reservierung belastet Ihr Guthaben sofort; eine fehlgeschlagene oder stornierte Auszahlung erstattet es zurück.
Konto
/v1/accountjeder gültige SchlüsselLiefert Ihr Kontoprofil, die Scopes des aufrufenden Schlüssels, Ihre Plattformgebühr und alle Live-Limits — nützlich für eine selbstkonfigurierende Integration oder eine Vorabprüfung.
{
"object": "account",
"id": "MC67T3PHQZ",
"fee_bps": 100,
"fee_percent": 1,
"default_currency": "USD",
"two_factor_enabled": false,
"api_key": {"label": "production", "scopes": ["payments:read","payments:write"]},
"limits": {
"shops": {"used": 1, "max": 10},
"payment_links": {"used": 0, "max": 50},
"products_per_shop_max": 50,
"variant_combinations_per_product_max": 30,
"license_keys_per_product_max": 10000,
"active_api_keys_max": 50,
"checkout_fields_per_link_max": 5
},
"minimum_payout_usd": 25
}Webhooks
Fügen Sie unter Dashboard -> Entwickler bis zu 10 öffentliche HTTPS-Endpunkte hinzu. Jeder Endpunkt erhält sein eigenes, nur einmal angezeigtes Signatur-Secret whsec_.... Er kann kontoweit lauschen oder an einen bestimmten aktiven API-Schlüssel gebunden sein; schlüsselgebundene Endpunkte erhalten nur Zahlungen, die mit diesem Schlüssel erstellt wurden.
Vor dem Parsen verifizieren
CryptoPayIn signiert den exakten Rohkörper der Anfrage mit dem Endpunkt-Secret. Version 1 signiert timestamp + "." + raw_body. Weisen Sie veraltete Zeitstempel zurück, bevor Sie das Event akzeptieren.
import crypto from "node:crypto";
const timestamp = req.headers["x-cpi-timestamp"];
const signature = req.headers["x-cpi-signature"];
const rawBody = req.rawBody; // Buffer captured before JSON parsing
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error("stale webhook");
}
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.CPI_WEBHOOK_SECRET)
.update(Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]))
.digest("hex");
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
if (!valid) throw new Error("invalid webhook signature");
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_CPI_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_CPI_SIGNATURE'] ?? '';
if (!ctype_digit($timestamp) || abs(time() - (int)$timestamp) > 300) {
http_response_code(400); exit('stale webhook');
}
$expected = 'sha256=' . hash_hmac(
'sha256', $timestamp . '.' . $rawBody, getenv('CPI_WEBHOOK_SECRET')
);
if (!hash_equals($expected, $received)) {
http_response_code(401); exit('invalid signature');
}
$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
import hashlib, hmac, os, time
raw_body = request.get_data() # bytes, before JSON decoding
timestamp = request.headers.get("X-CPI-Timestamp", "")
received = request.headers.get("X-CPI-Signature", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
raise ValueError("stale webhook")
signed = timestamp.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(
os.environ["CPI_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, received):
raise ValueError("invalid signature")Zustell-Header
| Header | Beispiel | Zweck |
|---|---|---|
| Content-Type | application/json | UTF-8-JSON-Body. |
| X-CPI-Timestamp | 1784293200 | Unix-Sekunden, enthalten in der signierten Nachricht. |
| X-CPI-Signature | sha256=... | Hex-HMAC-SHA256. |
| X-CPI-Signature-Version | v1 | Version des Signaturschemas. |
| X-CPI-Event-Id | evt_a12b... | Stabile logische Event-ID; bei Wiederholungen identisch. |
| X-CPI-Delivery-Id | 1842 | Stabile ID des Zustelldatensatzes des Endpunkts. |
Zahlungs-Payload
{
"event_id": "evt_a12b34c56d78e90f12345678",
"event": "payment.completed",
"id": "P-9F27C1E4KD",
"status": "completed",
"order_ref": "order_1042",
"amount": 49.99,
"amount_decimal": "49.99",
"amount_minor": 4999,
"currency_minor_units": 2,
"currency": "USD",
"amount_usd": 49.99,
"amount_usd_cents": 4999,
"fx_rate_usd": "1.000000000000",
"fx_source": "fixed:USD",
"fx_observed_at": "2026-07-17T13:00:00Z",
"fx_discrepancy_bps": 0,
"exchange_rate": "3600.00000000",
"exchange_rate_currency": "USD",
"exchange_rate_source": "median:cb,cg,cl",
"exchange_rate_source_count": 3,
"exchange_rate_observed_at": "2026-07-17T13:00:00Z",
"exchange_rate_discrepancy_bps": 12,
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0.01388612",
"txid": "0x9d81...75af",
"confirmations": 12,
"confirmations_required": 12,
"deposit_address": "0x71b8c3d4700000000000000000000000000084e2",
"sent_at": "2026-07-17T13:12:42Z"
}Wiederholungen und Endpunktsicherheit
Eine Zustellung gilt bei HTTP 200-299 als erfolgreich. Führen Sie aufwendige Arbeit asynchron aus und antworten Sie zügig.
Der exakte Body und die Event-ID bleiben erhalten; fehlgeschlagene Zustellungen werden nach etwa 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden wiederholt.
3xx-Antworten werden nicht verfolgt. Registrieren Sie direkt die endgültige HTTPS-URL.
Private, Loopback-, Link-Local- und reservierte IPs werden blockiert; jede DNS-Antwort wird validiert, und die Verbindung wird gepinnt.
Zustellungen erfolgen mindestens einmal. Machen Sie Ihren Handler idempotent, indem Sie event_id vor der Auslieferung mit einer Unique-Constraint erfassen. Rufen Sie beim Abgleich eines unerwarteten Events das API-Objekt ab.
Event-Referenz
payment.completedErwarteter Wert bestätigt.payment.overpaidMehr als erwartet bestätigt.payment.underpaidMittelzufluss unterhalb der Toleranz erkannt.payment.expiredZeitfenster einer unbezahlten Rechnung geschlossen.payment.failedEinrichtung oder Verarbeitung der Zahlung fehlgeschlagen.payout.sentAuszahlung on-chain übertragen.payout.confirmedAuszahlung hat Bestätigungen erreicht.payout.failedAuszahlung konnte nicht abgeschlossen werden.webhook.testManueller Verbindungstest.Struktur des Auszahlungs-Events
{
"event_id": "evt_b98c76d54e32a10f87654321",
"event": "payout.sent",
"id": "W-8J2K7M4RQP",
"status": "sent",
"asset": "ETH",
"network": "mainnet",
"amount": "0.25",
"fee": "0.00081768",
"address": "0x84f2...9bc1",
"txid": "0xa1c4...07ee",
"confirmations": 0,
"note": "weekly treasury",
"sent_at": "2026-07-17T14:08:31Z"
}Fehler und Rate-Limits
Fehler verwenden stets einen einheitlichen JSON-Umschlag. Verzweigen Sie anhand von error.type; die für Menschen lesbare Meldung kann ohne Versionswechsel verbessert werden. Geben Sie bei der Kontaktaufnahme mit dem Support error.request_id oder den passenden Antwort-Header X-Request-Id an.
{
"error": {
"type": "ambiguous_asset",
"message": "specify network (e.g. USDT.ERC20 or USDT.TRC20)",
"request_id": "b942e21f8dca4b06b8672eb9"
}
}| HTTP | Typische Typen | Bedeutung |
|---|---|---|
| 400 | invalid_request, unknown_parameter | Fehlerhaftes JSON, fehlerhafte Query oder fehlerhafter Idempotency-Header. |
| 401 | unauthorized | Fehlende, ungültige oder inaktive Anmeldedaten/Konto. |
| 403 | insufficient_scope, admin_disabled | Gültiger Schlüssel ohne die erforderliche Berechtigung (siehe X-Required-Scope), oder eine von einem Administrator gesperrte Ressource. |
| 404 | not_found | Unbekannter Endpunkt oder eine Ressource außerhalb dieses Händlerkontos. |
| 405 | method_not_allowed | Verwenden Sie die im Allow-Header angegebene Methode. |
| 409 | idempotency_conflict | Schlüssel mit abweichendem JSON wiederverwendet. |
| 413 | request_too_large | JSON-Body überschreitet 64 KiB. |
| 415 | unsupported_media_type | POST-Body ist nicht als application/json deklariert. |
| 422 | invalid, limit, invalid_amount, below_minimum, bad_address, 2fa_required, unsupported_asset | Wohlgeformte Anfrage hat die deterministische Validierung nicht bestanden oder eine Ressourcenobergrenze erreicht. |
| 429 | rate_limited | Warten Sie auf Retry-After. |
| 500 | server_error | Unerwarteter Fehler; sicher mit demselben Idempotency-Key wiederholen. |
| 503 | maintenance, temporarily_unavailable, asset_unavailable, no_rate, price_stale, fiat_rate_unavailable, fiat_rate_stale, derive_failed | Vorübergehender Ausfall der Plattform, eines Nodes, des Preises oder der Adresszuweisung. Es wird keine veraltete Umrechnung ersatzweise verwendet. |
Aktuelle Limits
| Scope | Limit | Zeitfenster |
|---|---|---|
| Nginx-Sicherheitsobergrenze pro IP | 10 Anfragen/Sekunde, Burst 30 | Fortlaufend |
| Obergrenze für nicht authentifizierte IPs | 300 Anfragen | 60 Sekunden |
| POST /v1/payments, links, shops, products | 120 Anfragen pro API-Schlüssel | 60 Sekunden |
| POST /v1/payouts | 30 Anfragen pro API-Schlüssel | 60 Sekunden |
| GET-Endpunkte | 240 Anfragen pro API-Schlüssel | 60 Sekunden |
Kontolimits
| Ressource | Obergrenze |
|---|---|
| Shops pro Konto | 10 |
| Zahlungslinks pro Konto | 50 |
| Produkte pro Shop | 50 |
| Variantenkombinationen pro Produkt | 30 |
| Lizenzschlüssel pro Produkt / Link | 10,000 |
| Checkout-Fragen pro Link | 5 |
| Aktive API-Schlüssel pro Konto | 50 |
Ihre aktuelle Nutzung im Verhältnis zu diesen Obergrenzen können Sie unter GET /v1/account einsehen.
Erfolgreiche, anwendungsseitig limitierte Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Wiederholen Sie 429, 500 und 503 mit exponentiellem Backoff und Jitter. Verwenden Sie bei POST stets denselben ursprünglichen Idempotency-Key und identisches JSON.
Integrationssicherheit
Laden Sie sie zur Laufzeit; protokollieren Sie niemals den vollständigen Wert und committen Sie ihn nicht in die Versionsverwaltung.
Ein Browser- oder Mobile-Client kann ein Händler-Secret nicht sicher aufbewahren.
Prüfen Sie die Aktualität des Zeitstempels und verwenden Sie einen zeitkonstanten Signaturvergleich, bevor Sie das JSON parsen.
Erfassen Sie verarbeitete Events/Bestellungen transaktional, damit Wiederholungen niemals doppelt ausliefern.
Rufen Sie die Zahlung ab, wenn ein Event unerwartet ist oder Ihr lokaler Status abweicht.
Erstellen Sie einen Ersatzschlüssel, stellen Sie ihn bereit, prüfen Sie den Traffic, und löschen Sie anschließend den alten Schlüssel.
Der Kontozugriff wird durch einen nicht wiederherstellbaren 16-stelligen Händlerschlüssel kontrolliert, optional zusätzlich durch TOTP geschützt. Bewahren Sie sowohl den Händlerzugriff als auch API-Secrets mit derselben Sorgfalt auf wie Wallet-Zugangsdaten.
Go-Live-Checkliste
Verwenden Sie nicht die persönliche Kopie eines Entwicklers über mehrere Dienste hinweg.
Verwenden Sie GET /v1/assets und GET /v1/currencies; stellen Sie nur Einträge dar, die vorhanden und available: true sind.
Speichern Sie das Signatur-Secret einmalig; verifizieren Sie Zeitstempel und Signatur, und deduplizieren Sie anschließend anhand der stabilen Event-ID.
Testen Sie eine doppelte Wiederholung und bestätigen Sie, dass nur eine Zahlungs-ID existiert.
Ihr Bestellstatus sollte bei veralteten Fiat-Kursen, nicht verfügbaren Assets, verzögerten Bestätigungen und jedem Nicht-Happy-Path stabil bleiben.
Gleichen Sie Ihre Bestellungen mit den API-Zahlungsstatus, Webhook-Protokollen und dem Händler-Ledger ab.
Bereit für die Integration?
Erstellen Sie in Sekunden ein Konto, generieren Sie einen Schlüssel, und halten Sie diese Referenz griffbereit neben Ihrem Code.