Einzahlungen und Rechnungen
Verwenden Sie eine Rechnung für eine Bestellung mit festem Preis. Verwenden Sie eine Einzahlung für ein Kundenguthaben, das wiederholt aufgeladen werden kann.
Eine Rechnung erstellen
Abschnitt betitelt „Eine Rechnung erstellen“curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\",\"external_id\":\"order-123\"}"Ersetzen Sie {shop_id} durch Ihre Shop-ID. Setzen Sie CHAIN_ID und TOKEN_ADDRESS aus der API-Antwort und AMOUNT in den kleinsten Einheiten des ausgewählten Tokens. external_id verknüpft die Rechnung mit einer Bestellung in Ihrem System; es ersetzt nicht den Idempotenzschlüssel.
Optionale Felder: description (bis zu 500 Zeichen), external_id (bis zu 200) und return_url, die eine https://-URL sein muss. Eine längere description oder external_id gibt 400 invalid_description zurück, eine andere return_url 400 invalid_return_url. Einzahlungen nehmen dieselben Felder an.
Die Antwort ist 202 Accepted und enthält bereits die Zahlungs-address und die payment_url; die Rechnung ist sofort open. Speichern Sie ihre id und geben Sie dem Zahlenden die zurückgegebene payment_url. Bei 503 address_unavailable wiederholen Sie dieselbe Anfrage mit demselben Idempotency-Key.
Teilzahlungen summieren sich. Sobald genügend bestätigtes Geld eingegangen ist, plant Invoise die Auszahlung und schließt die Rechnung. Der Empfänger erhält den Rechnungsbetrag abzüglich der Servicegebühr. Jede Überzahlung geht an Invoise, nicht an den Empfänger.
Rechnungen sind einmalige Zahlungen; sie erneuern sich nicht automatisch.
Rechnungslaufzeit
Abschnitt betitelt „Rechnungslaufzeit“Eine Rechnung bleibt standardmäßig 30 Tage offen. Invoise kann diesen Standard ändern; senden Sie daher expires_in, wenn Ihre Integration von der Laufzeit abhängt. Um eine andere Laufzeit zu wählen, fügen Sie expires_in zum Anfragekörper hinzu, zum Beispiel "expires_in":"7d". Zulässige Werte sind 1h, 2h, 1d, 7d, 30d, 180d und 365d.
Rechnungsantworten, einschließlich der öffentlichen Zahlungsseite, enthalten expires_at. Wenn diese Zeit verstreicht, schließt sich eine unbezahlte Rechnung: cancelled_at wird gesetzt und der Webhook invoice.cancelled wird mit data.reason auf expired gesendet. Eine später eingehende Zahlung wird weiterhin erfasst und kann weiterhin abgerechnet werden, wie bei einer stornierten Rechnung. Abonnieren Sie bei kurzen Laufzeiten wie 1h, 2h oder 1d invoice.cancelled, damit Sie sofort vom Ablauf erfahren.
Einzahlungen laufen nicht ab. Das Senden von expires_in beim Erstellen einer Einzahlung gibt 400 invalid_expires_in zurück.
Eine Einzahlungsadresse erstellen
Abschnitt betitelt „Eine Einzahlungsadresse erstellen“Verwenden Sie dieselben Anfrage-Header mit diesem Endpunkt und Body:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/deposits' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"external_id\":\"customer-123\"}"Legen Sie keinen festen amount fest. Die Adresse kommt wie bei einer Rechnung in der Erstellungsantwort. Die Adresse kann wiederholte Aufladungen im gewählten Token und Netzwerk empfangen.
Kleine Einzahlungen sammeln sich an, bis sie die Auszahlungsschwelle des Shops erreichen. Lesen Sie diese über GET /api/v1/shops/{shop_id}/terms. Invoise nimmt die Gebühr von jeder Auszahlung, nicht von jedem eingehenden Transfer: Gemeinsam ausgezahlte Einzahlungen zahlen eine Gebühr, und die Mindestgebühr des Netzwerks gilt einmal pro Auszahlung. Eine Rechnung zahlt ihre Gebühr einmal, vom Rechnungsbetrag.
Mehrere Token oder Netzwerke anbieten
Abschnitt betitelt „Mehrere Token oder Netzwerke anbieten“Senden Sie assets anstelle von chain_id und token, damit der Zahlende wählen kann, wie er bezahlt. Dies funktioniert für Rechnungen und Einzahlungen:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d '{"assets":[{"chain_id":<chain-id>,"token":"<token-address>"},{"chain_id":<other-chain-id>,"token":"<other-token-address>"}],"amount":"10.5","external_id":"order-124"}'Bei assets ist der Rechnungsbetrag amount ein dezimaler Token-Betrag, wie "10.5", keine Basiseinheiten: die Token können unterschiedliche Dezimalstellen haben. Jede Option muss den minimum_payment-Wert ihres Netzwerks erreichen.
Die Antwort ist eine Gruppe. Jede Option ist eine separate Rechnung oder Einzahlungsadresse mit eigener address, eigenem Betrag in Basiseinheiten und eigenem Status:
{ "id": "<group-id>", "group": true, "shop_id": "<shop-id>", "public_id": "<public-id>", "status": "open", "payment_url": "https://pay.invoise.me/<public-id>", "options": [ { "id": "<option-id>", "public_id": "<option-public-id>", "chain_id": 12345, "token": "<token-address>", "token_decimals": 6, "family": "evm", "amount": "10500000", "address": "<option-address>", "status": "open" } ], "expires_at": "2026-10-19T09:00:00Z"}Speichern Sie die Gruppen-id. Jede Option hat ihre address bereits in der Erstellungsantwort; geben Sie dem Zahlenden also sofort die payment_url der Gruppe, wo er eine Option auswählt. GET /api/v1/shops/{shop_id}/issuances/{id} gibt die Gruppe mit jeder Option zurück.
Eine Rechnungsgruppe wird einmal bezahlt. Ihr status folgt der bezahlten Option, und paid_issuance_id benennt sie. Webhook-Ereignisse werden pro Option gesendet und enthalten group_id und group_public_id. duplicate: true bedeutet, dass die Gruppe bereits über eine andere Option bezahlt wurde: Schreiben Sie die Bestellung nicht doppelt gut. Eine Einzahlungsgruppe behält eine wiederverwendbare Adresse pro Option.
Stornieren Sie eine Rechnungsgruppe oder pausieren Sie eine Einzahlungsgruppe über die Gruppen-id; jede Option ändert sich gemeinsam. Die eigene id einer Option gibt 400 issuance_in_group zurück.
Wenn eine Option nicht erstellt werden kann, wird nichts erstellt, und error.details benennt die Option als {chain_id, token}. Ein leeres oder wiederholtes Paar, oder assets zusammen mit chain_id oder token gesendet, gibt 400 invalid_assets zurück.
Standardmäßig kann eine Rechnung höchstens 1.000.000 Token betragen. Ein Händler kann bis zu 2.000 aktive Rechnungen und bis zu 100.000 aktive Einzahlungsadressen in EVM-Netzwerken, 100.000 auf Tron und 100 auf Solana haben und pro Stunde höchstens so viele neue Zahlungsadressen erstellen, wie sein Limit aktiver Rechnungen beträgt. Stornieren Sie nicht mehr benötigte Rechnungen oder deaktivieren Sie Einzahlungen, um Platz zu schaffen. Das sind Standardwerte: Das Invoise-Team kann für einen Händler andere Limits festlegen. Um mehr Zahler zu bedienen, deaktivieren Sie ungenutzte Einzahlungen und aktivieren Sie sie wieder, wenn sie gebraucht werden: Eine deaktivierte Einzahlung zählt nicht zum Limit, und das erneute Aktivieren braucht einen freien Platz. Eine deaktivierte Adresse wird weiter überwacht, später eingehendes Geld wird also trotzdem gutgeschrieben und ausgezahlt. Eine deaktivierte Solana-Adresse, auf der eine Stunde lang nichts einging, wird stündlich geprüft, solches Geld erscheint also bis zu eine Stunde später; deaktivieren Sie keine Adresse, auf die Sie noch eine Zahlung erwarten. Welche Adressen Sie umschalten, entscheiden Sie; umschalten kann auch ein Shop-API-Schlüssel mit write. Siehe Limits für die genauen Werte und Fehlercodes.
Eine Einzahlung pausieren oder eine Rechnung stornieren
Abschnitt betitelt „Eine Einzahlung pausieren oder eine Rechnung stornieren“| Aktion | Anfrage |
|---|---|
| Die Zahlungsseite einer Einzahlung pausieren | PATCH /api/v1/shops/{shop_id}/deposits/{id} mit {"enabled":false}. Verwenden Sie true, um sie wieder zu aktivieren. |
| Die Zahlungsseite einer Rechnung stornieren | POST /api/v1/shops/{shop_id}/invoices/{id}/cancel. |
Beides geht mit einem Shop-API-Schlüssel mit write oder einer Inhaber-Sitzung; senden Sie einen gespeicherten Idempotency-Key.
Diese Aktionen schließen die Zahlungsseite. Sie erstatten kein Geld und stoppen nicht die Überwachung der Adresse. An eine stornierte Rechnung gesendete Mittel können weiterhin abgerechnet werden; ihre Ereignisse enthalten invoice_cancelled: true.
Mittel, die nach der bereits erfolgten Abrechnung einer Rechnung gesendet werden, werden als verspätete Transfers erfasst. Sie werden nicht automatisch ausgezahlt. Die Wiederherstellung, einschließlich der Wiederherstellung des falschen Tokens, erfordert einen separaten manuellen Vorgang.
Siehe die API-Referenz für vollständige Anfrage- und Antwortfelder.