CryptoPayIn
Entwicklerdokumentation

Zahlungen entwickeln, die on-chain abgewickelt werden.

Alles Notwendige, um eine Zahlung zu erstellen, einen Kunden zum Hosted Checkout zu leiten, Bestätigungen zu verfolgen und signierte Webhooks im Produktivbetrieb zu verarbeiten.

API-Basis-URLVersion 1
https://cryptopayin.com/v1
ProtokollREST / JSON
AuthentifizierungBearer-Secret
ModusNur live
Einführung

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.

Basis-URL/v1
Fiat-BeträgeISO-Untereinheiten
Krypto-WerteDezimal-Strings
Standardablauf30 Minuten
!

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

1Schlüssel erstellen

Erzeugen Sie einmalig ein Secret unter Dashboard -> Entwickler.

2Zahlung erstellen

Senden Sie Bestellwährung, Betrag und gewähltes Asset per POST.

3Checkout öffnen

Leiten Sie den Kunden zur zurückgegebenen Hosted-URL weiter.

4Event verarbeiten

Prüfen Sie den HMAC und aktualisieren Sie Ihre Bestellung idempotent.

Jetzt starten

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

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
}
Zugangsdaten

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.

AUTHAuthorization: Bearer csk_live_...Jeder Endpunkt
Wird nur einmal angezeigt

Das 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.

Unabhängige Schlüssel

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.

Nur serverseitig

Platzieren Sie einen csk_live_-Wert niemals in Browser-JavaScript, einer mobilen Binärdatei, einem öffentlichen Repository oder einer Checkout-Seite.

Webhook-Bindung

Ein Webhook-Endpunkt kann kontoweit gelten oder an einen einzelnen API-Schlüssel gebunden sein, sodass Integrationen voneinander getrennt bleiben.

i

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.

Sichere Wiederholungen

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.

FallErgebnisHTTP
Erste VerwendungErstellt eine neue Zahlung und gibt sie zurück.201
Gleicher Schlüssel + gleiches JSONGibt die bestehende Zahlung mit Idempotent-Replayed: true zurück.200
Gleicher Schlüssel + abweichendes JSONWeist 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.

REST-API

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.

GET/v1/assetsVerfügbare Assets ermitteln
GET/v1/currenciesFiat-Anzeigewährungen ermitteln
POST/v1/paymentsZahlung erstellen
GET/v1/paymentsZahlungen auflisten und filtern
GET/v1/payments/{id}Zahlung abrufen
i

Version 1 kann abwärtskompatible Felder und Endpunkte erhalten. Eine Breaking Change am Vertrag erfolgt über einen neuen Basispfad, statt /v1 stillschweigend zu ändern.

API-Referenz

Assets auflisten

GET/v1/assetsBearer-Authentifizierung erforderlich

Verwenden 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

AssetNetzwerkwertKurzformBasis-Bestätigungen
BTCmainnetBTC2
ETHmainnetETH6
USDTTRC20 / ERC20USDT.TRC2019 / 6
USDCERC20USDC.ERC206
DAIERC20DAI6
SHIBERC20SHIB6
PEPEERC20PEPE6
LTCmainnetLTC6
TRXmainnetTRX19
DOGEmainnetDOGE20
XMRmainnetXMR10
SOLmainnetSOL32
!

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.

API-Referenz

Fiat-Währungen auflisten

GET/v1/currenciesBearer-Authentifizierung erforderlich

Liefert 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"
  }]
}
i

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.

API-Referenz

Zahlung erstellen

POST/v1/payments120 Anfragen / Minute / Schlüssel

Erstellt 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

FeldTypAnforderungBeschreibung
amountZahl oder Dezimal-StringerforderlichWert 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.
currencystringoptionalAktivierte 3-stellige Währung aus GET /v1/currencies. Standardwert: USD.
assetstringerforderlichSymbol wie ETH oder Kurzform wie USDT.TRC20.
networkstringbedingtErforderlich, wenn ein Symbol in mehreren Netzwerken existiert. Beispiel: ERC20.
order_refstringoptionalIhre Bestellkennung, maximal 128 Zeichen. Wird in API-Antworten und Events zurückgegeben.
customer_emailstringoptionalGültige E-Mail-Adresse, maximal 190 Zeichen. Wird im Zahlungsdatensatz des Händlers gespeichert.
redirect_urlstringoptionalHTTPS-URL, maximal 255 Zeichen, wird nach erfolgreichem Checkout angeboten.

Antwortfelder

FeldTypBeschreibung
idstringStabile Zahlungskennung, beginnend mit P-.
statusstringAktueller Lifecycle-Status.
amount / amount_decimal / amount_minornumber / string / integerAngeforderter Anzeigewert in praktischer, exakter Dezimal- und ISO-Untereinheiten-Form.
currency / currency_minor_unitsstring / integerGesperrte Anzeigewährung und ihre Genauigkeit.
amount_usd / amount_usd_centsnumber / integerUnveränderlicher interner USD-Buchungswert.
fx_rate_usd / fx_source / fx_observed_atdecimal string / string / ISO 8601Gesperrter USD-Kurs pro Einheit der Anzeigewährung samt Audit-Metadaten.
asset / networkstringAufgelöstes On-Chain-Asset.
crypto_amountdecimal stringExakter Betrag, den der Kunde senden muss. Krypto-Dezimalwerte niemals als binäre Fließkommazahlen parsen.
crypto_receiveddecimal stringAktuell an der Einzahlungsadresse beobachtete Gesamtsumme.
deposit_addressstringFür diese Zahlung zugewiesene eigene Adresse.
exchange_ratedecimal stringGesperrter 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_atstring / ISO 8601Unveränderlicher Audit-Snapshot des Krypto-Kurses.
confirmationsintegerAktuelle Netzwerkbestätigungen.
confirmations_requiredintegerSchwellenwert für diese Zahlung. Höhere USD-Stufen können zusätzliche Bestätigungen erfordern.
checkout_urlURLHosted-Rechnung zur Anzeige für den Kunden.
expires_atISO 8601Frist für eine unbezahlte Rechnung.
completed_atISO 8601 / nullEndgü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.

API-Referenz

Zahlungen auflisten

GET/v1/payments240 Anfragen / Minute / Schlüssel

Gibt 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

ParameterStandardBeschreibung
limit20Seitengröße von 1 bis 100.
starting_afterZahlungs-ID aus dem next_cursor der vorherigen Seite.
statusExakter Lifecycle-Status wie pending, completed oder expired.
order_refExakte 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"
}
i

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.

API-Referenz

Zahlung abrufen

GET/v1/payments/{id}240 Anfragen / Minute / Schlüssel

Gibt 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"
i

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.

Zustandsmodell

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.

created->pending->underpaidoderconfirming->completed/overpaid
StatusBedeutungAktion des Händlers
createdRechnung und Adresse zugewiesen; noch keine Zahlungseingänge erkannt.Hosted Checkout anzeigen.
pendingWartet auf eine verwertbare On-Chain-Zahlung.Bestellung offen halten.
underpaidEingegangene Mittel liegen unter der Toleranz des Händlers.Zahler bitten, den angezeigten Restbetrag zu senden.
confirmingAusreichender Wert erkannt; wartet auf Bestätigungen.Noch nicht ausliefern.
completedErforderlicher Wert und Bestätigungen erreicht.Genau einmal ausliefern.
overpaidMehr als erwartet wurde bestätigt.Ausliefern und den Überschuss prüfen.
expiredVor Ablauf wurde keine ausreichende Zahlung erkannt.Neue Zahlung erstellen.
failedAdresszuweisung 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.

Kundenerlebnis

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.

Kurs gesperrt

Der Kunde sieht für das Rechnungsfenster denselben crypto_amount, den die API zurückgegeben hat.

Kein Kundenkonto

Der Zahler erstellt kein CryptoPayIn-Konto und gibt keine Zugangsdaten preis.

Live-Status

Die Seite fragt die Zahlung sicher ab und wechselt von wartend über bestätigend zu bezahlt.

Weiterleitung zum Händler

Nach erfolgreichem Abschluss wird eine HTTPS-redirect_url angeboten; sie ist kein Zahlungsnachweis.

i

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.

Zugangsdaten

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.

ScopeGewährtEndpunkte
payments:readZahlungen auflisten und abrufenGET /v1/payments, GET /v1/payments/{id}
payments:writeHosted-Zahlungen erstellenPOST /v1/payments
links:readZahlungslinks auflisten und abrufenGET /v1/links, GET /v1/links/{id}
links:writeZahlungslinks erstellen, bearbeiten, pausieren und löschenPOST/PATCH/DELETE /v1/links
shops:readShops und deren Produkte auflisten und abrufenGET /v1/shops, GET .../products
shops:writeShops, Produkte und Varianten erstellen und bearbeitenPOST/PATCH/DELETE /v1/shops und Produkte
balance:readKrypto-Guthaben und USD-Schätzungen lesenGET /v1/balance
payouts:readAuszahlungen auflisten und abrufenGET /v1/payouts, GET /v1/payouts/{id}
payouts:writeOn-Chain-Auszahlungen anfordernPOST /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.

Maschinelle Käufer

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.

GEThttps://cryptopaylink.co/pay/{link}.jsonöffentlich · Discovery

Liefert Status, Preise, akzeptierte Assets und den exakten Eingabevertrag für den Rechnungsaufruf (Pflichtfelder, Versandschema, Varianten).

POSThttps://cryptopaylink.co/pay/{link}/invoiceöffentlich · unterstützt Idempotency-Key

Erstellt 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.

GEThttps://cryptopaylink.co/pay/{link}/receipt?p={payment}öffentlich · Abfrage alle 5–10 s

Live-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.

GEThttps://shopycrypto.com/s/{shop}.jsonöffentlich · Katalog
POSThttps://shopycrypto.com/s/{shop}/orderöffentlich · Warenkorb → Rechnung, unterstützt Idempotency-Key
GEThttps://shopycrypto.com/s/{shop}/o/{order}/receipt?p={payment}öffentlich · Abfrage alle 5–10 s

Verkä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.

Händler-Ressourcen

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.

GET/v1/shopsshops:read
POST/v1/shopsshops:write
GET/v1/shops/{id}shops:read
PATCH/v1/shops/{id}shops:write
DELETE/v1/shops/{id}shops:write

Request-Body

FeldTypAnforderungBeschreibung
namestringerforderlich2–80 Zeichen.
taglinestringoptionalBis zu 160 Zeichen.
themestringoptionallight (Standard) oder dark.
accentstringoptionalHex-Akzentfarbe aus der Shop-Palette, zurückgegeben als accent_palette bei GET /v1/shops.
accepted_assetsarray of stringsoptionalStandard-Assets für die Produkte des Shops, z. B. ["BTC","LTC","XMR"]. Wird bei Änderung auf alle Produkte angewendet.
statusstringoptionalNur PATCH: active oder paused.
i

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.

Händler-Ressourcen

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.

GET/v1/shops/{shop}/productsshops:read
POST/v1/shops/{shop}/productsshops:write
GET/v1/shops/{shop}/products/{id}shops:read
PATCH/v1/shops/{shop}/products/{id}shops:write
DELETE/v1/shops/{shop}/products/{id}shops:write

Request-Body

FeldTypAnforderungBeschreibung
titlestringerforderlich3–120 Zeichen.
description / blurbstringoptionalVollständige Beschreibung sowie eine ≤200-Zeichen-Zeile für die Shop-Karte.
emojistringoptionalEinzelnes Emoji, das auf der Produktkarte angezeigt wird.
featuredbooleanoptionalHöchstens ein hervorgehobenes Produkt pro Shop.
product_typestringoptionaldigital (Standard) oder physical.
shipping_countriesarray of stringsbedingtNur physisch: ISO-Codes wie ["FR","BE"], oder ["*"] für weltweit.
amount_type / currency / amount / min / maxmixedbedingtBasispreisgestaltung, identische Regeln wie bei Zahlungslinks. Physische Produkte müssen fixed sein.
max_usesintegeroptionalGesamt-Verkaufsobergrenze (0 = unbegrenzt).
delivery_type + delivery_text/url/keysmixedoptionalDigitale Auslieferung für das Basisprodukt, gleiche Struktur wie bei Zahlungslinks.
variant_optionsarrayoptional1–3 Gruppen {name, values[]}, jeweils 2–10 Werte. Die Kombinationen dürfen 30 nicht überschreiten.
variantsarraybedingtEin Objekt pro Kombination (siehe unten). Erforderlich und vollständig, wenn variant_options vorhanden ist.
statusstringoptionalNur PATCH: active oder paused.

Varianten-Objekt

FeldTypBeschreibung
optionsarray of stringsEin Wert pro Optionsgruppe, in Gruppenreihenfolge, z. B. ["Pro","Lifetime"].
pricenumber or stringVariantenpreis in der Produktwährung.
stockinteger or nullVerbleibende Einheiten, oder null für unbegrenzt.
delivery_type + delivery_text/url/keysmixedOptionale, 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"]}
    ]
  }'
i

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.

Händler-Ressourcen

Guthaben

GET/v1/balancebalance:read

Liefert 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"
  }]
}
i

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.

Händler-Ressourcen

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.

GET/v1/payoutspayouts:read
POST/v1/payoutspayouts:write · 30 / Min. / Schlüssel
GET/v1/payouts/{id}payouts:read

Request-Body

FeldTypAnforderungBeschreibung
assetstringerforderlichSymbol oder Kurzform, z. B. LTC oder USDT.TRC20.
networkstringbedingtErforderlich, wenn das Symbol in mehreren Netzwerken existiert.
amountnumber or stringerforderlichZu sendender Betrag, ohne Netzwerkgebühr, mit der Genauigkeit des Assets. Sein USD-Wert muss den Kontomindestbetrag erreichen.
addressstringerforderlichZieladresse, validiert für die Chain des Assets.
notestringoptionalIhre eigene Referenz, bis zu 255 Zeichen.
totp_codestringbedingtAktueller 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

StatusBedeutung
requestedAus Ihrem Guthaben reserviert; wartet auf Prüfung durch den Betreiber oder automatische Freigabe.
approved / processingFreigegeben und zur Übertragung durch den Executor eingereiht.
sentOn-Chain übertragen; txid ist befüllt.
confirmedHat die erforderlichen Bestätigungen erreicht. Endgültig.
failedKonnte nicht gesendet werden; failure_message erläutert den Grund, und das Guthaben wird zurückerstattet.
cancelledVor 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.

Händler-Ressourcen

Konto

GET/v1/accountjeder gültige Schlüssel

Liefert 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
}
Server-zu-Server-Events

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");

Zustell-Header

HeaderBeispielZweck
Content-Typeapplication/jsonUTF-8-JSON-Body.
X-CPI-Timestamp1784293200Unix-Sekunden, enthalten in der signierten Nachricht.
X-CPI-Signaturesha256=...Hex-HMAC-SHA256.
X-CPI-Signature-Versionv1Version des Signaturschemas.
X-CPI-Event-Idevt_a12b...Stabile logische Event-ID; bei Wiederholungen identisch.
X-CPI-Delivery-Id1842Stabile 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

Beliebigen 2xx zurückgeben

Eine Zustellung gilt bei HTTP 200-299 als erfolgreich. Führen Sie aufwendige Arbeit asynchron aus und antworten Sie zügig.

Insgesamt sechs Versuche

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.

Keine Weiterleitungen

3xx-Antworten werden nicht verfolgt. Registrieren Sie direkt die endgültige HTTPS-URL.

Nur öffentliche Ziele

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.

Webhooks

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"
}
Zuverlässigkeit

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"
  }
}
HTTPTypische TypenBedeutung
400invalid_request, unknown_parameterFehlerhaftes JSON, fehlerhafte Query oder fehlerhafter Idempotency-Header.
401unauthorizedFehlende, ungültige oder inaktive Anmeldedaten/Konto.
403insufficient_scope, admin_disabledGültiger Schlüssel ohne die erforderliche Berechtigung (siehe X-Required-Scope), oder eine von einem Administrator gesperrte Ressource.
404not_foundUnbekannter Endpunkt oder eine Ressource außerhalb dieses Händlerkontos.
405method_not_allowedVerwenden Sie die im Allow-Header angegebene Methode.
409idempotency_conflictSchlüssel mit abweichendem JSON wiederverwendet.
413request_too_largeJSON-Body überschreitet 64 KiB.
415unsupported_media_typePOST-Body ist nicht als application/json deklariert.
422invalid, limit, invalid_amount, below_minimum, bad_address, 2fa_required, unsupported_assetWohlgeformte Anfrage hat die deterministische Validierung nicht bestanden oder eine Ressourcenobergrenze erreicht.
429rate_limitedWarten Sie auf Retry-After.
500server_errorUnerwarteter Fehler; sicher mit demselben Idempotency-Key wiederholen.
503maintenance, temporarily_unavailable, asset_unavailable, no_rate, price_stale, fiat_rate_unavailable, fiat_rate_stale, derive_failedVorübergehender Ausfall der Plattform, eines Nodes, des Preises oder der Adresszuweisung. Es wird keine veraltete Umrechnung ersatzweise verwendet.

Aktuelle Limits

ScopeLimitZeitfenster
Nginx-Sicherheitsobergrenze pro IP10 Anfragen/Sekunde, Burst 30Fortlaufend
Obergrenze für nicht authentifizierte IPs300 Anfragen60 Sekunden
POST /v1/payments, links, shops, products120 Anfragen pro API-Schlüssel60 Sekunden
POST /v1/payouts30 Anfragen pro API-Schlüssel60 Sekunden
GET-Endpunkte240 Anfragen pro API-Schlüssel60 Sekunden

Kontolimits

RessourceObergrenze
Shops pro Konto10
Zahlungslinks pro Konto50
Produkte pro Shop50
Variantenkombinationen pro Produkt30
Lizenzschlüssel pro Produkt / Link10,000
Checkout-Fragen pro Link5
Aktive API-Schlüssel pro Konto50

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.

Sicherheit im Produktivbetrieb

Integrationssicherheit

API-Secrets in einem Secret Manager aufbewahren

Laden Sie sie zur Laufzeit; protokollieren Sie niemals den vollständigen Wert und committen Sie ihn nicht in die Versionsverwaltung.

Die API von Ihrem Backend aus aufrufen

Ein Browser- oder Mobile-Client kann ein Händler-Secret nicht sicher aufbewahren.

Den rohen Webhook-Body verifizieren

Prüfen Sie die Aktualität des Zeitstempels und verwenden Sie einen zeitkonstanten Signaturvergleich, bevor Sie das JSON parsen.

Die Auslieferung idempotent gestalten

Erfassen Sie verarbeitete Events/Bestellungen transaktional, damit Wiederholungen niemals doppelt ausliefern.

Dem finalen API-Status vertrauen, nicht Weiterleitungen

Rufen Sie die Zahlung ab, wenn ein Event unerwartet ist oder Ihr lokaler Status abweicht.

Rotation mit Überlappung

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.

Start

Go-Live-Checkliste

1
Einen eigenen Produktions-API-Schlüssel erstellen

Verwenden Sie nicht die persönliche Kopie eines Entwicklers über mehrere Dienste hinweg.

2
Beide Live-Kataloge abfragen

Verwenden Sie GET /v1/assets und GET /v1/currencies; stellen Sie nur Einträge dar, die vorhanden und available: true sind.

3
Ihren Webhook-Endpunkt hinzufügen und testen

Speichern Sie das Signatur-Secret einmalig; verifizieren Sie Zeitstempel und Signatur, und deduplizieren Sie anschließend anhand der stabilen Event-ID.

4
Für jede Bestellung einen Idempotency-Key verwenden

Testen Sie eine doppelte Wiederholung und bestätigen Sie, dass nur eine Zahlungs-ID existiert.

5
Kursausfälle, Unterzahlung und Ablauf testen

Ihr Bestellstatus sollte bei veralteten Fiat-Kursen, nicht verfügbaren Assets, verzögerten Bestätigungen und jedem Nicht-Happy-Path stabil bleiben.

6
Täglich abgleichen

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.

Konto erstellen