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

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.

Die Antwort ist 202 Accepted. Speichern Sie ihre id und fragen Sie den Issuance-Endpunkt ab, bis address verfügbar ist. Geben Sie dem Zahlenden dann die zurückgegebene payment_url.

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

Eine Rechnung bleibt standardmäßig 30 Tage offen. 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 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.

Einzahlungen laufen nicht ab. Das Senden von expires_in beim Erstellen einer Einzahlung gibt 400 invalid_expires_in zurück.

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. Warten Sie auf die Adresse wie bei einer Rechnung. 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.

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": "registering",
  "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": null,
      "status": "registering"
    }
  ],
  "expires_at": "2026-10-19T09:00:00Z"
}

Speichern Sie die Gruppen-id. GET /api/v1/shops/{shop_id}/issuances/{id} gibt die Gruppe mit jeder Option zurück; fragen Sie sie ab, bis die Optionen Adressen haben, und geben Sie dem Zahlenden dann die payment_url der Gruppe, wo er eine Option auswählt.

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.

Limits

Eine Rechnung kann höchstens 1.000.000 Token betragen. Ein Händler kann bis zu 2.000 aktive Rechnungen und eine begrenzte Anzahl aktiver Einzahlungsadressen pro Netzwerkfamilie haben. Stornieren Sie nicht mehr benötigte Rechnungen oder deaktivieren Sie Einzahlungen, um Platz zu schaffen. Siehe Limits für die genauen Werte und Fehlercodes.

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.

Senden Sie für beide Vorgänge eine Authentifizierung und 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.