Zum Inhalt springen

Deine erste Einlösung

  1. Schlüssel holen

    Erstelle im Händlerportal einen Testschlüssel. Den vollständigen Schlüssel siehst du nur einmal; sein letzter Teil ist zugleich das Secret, mit dem du Anfragen signierst.

  2. Gutschein reservieren

    Sende den Code, die Währung und deine Kundenreferenz. Der Gutschein wird an diesen Kunden gebunden und kann nirgendwo sonst verwendet werden.

  3. Gutschreiben, dann erfassen

    Schreib das Guthaben auf deiner Seite gut, dann erfasse die Einlösung. Schlägt die Aufladung fehl, stornierst du stattdessen, und der Gutschein wird freigegeben.

  4. Webhooks empfangen

    Registriere einen Endpunkt, um signierte Events zu Erfassungen, Stornierungen, Abläufen und Checkouts zu erhalten.

Einlösungen · Beispiel
POST /v1/redemptions
Authorization: Bearer vch_test_…
Idempotency-Key: topup-88213
Vouchereto-Signature: t=1790500000,v1=9c1e5f07…
Content-Type: application/json

{ "code": "7K2M-9QXR-4HTB-2WNZ", "customer_ref": "acct_48213", "currency": "USD" }

# 201 Created
{ "id": "5f0c2a7e-…", "object": "redemption", "status": "reserved",
  "amount_minor": 5000, "currency": "USD", "voucher_last4": "2WNZ",
  "customer_ref": "acct_48213", "livemode": false,
  "expires_at": "2026-09-27T14:12:00Z", "captured_at": null }

Der Lebenszyklus einer Einlösung

aktiver Gutscheinreserviert
  • erfasstDer Gutschein ist verbraucht. Unwiderruflich.
  • storniertDu hast storniert. Der Gutschein ist wieder aktiv.
  • Reservierung abgelaufenNicht rechtzeitig erfasst (standardmäßig 15 Minuten). Der Gutschein ist wieder aktiv.

Worauf du aufbaust

Anfragen signieren

Jede Anfrage enthält einen Vouchereto-Signature-Header: einen Zeitstempel und einen HMAC-SHA256 aus Zeitstempel, Methode, Pfad und Body, signiert mit dem Secret deines API-Schlüssels. Wir akzeptieren eine Zeitabweichung von bis zu 300 Sekunden.

sign.js
// Sign every request with the secret part of your API key (the text after the last "_")
const t = Math.floor(Date.now() / 1000);
const payload = `${t}.${method} ${pathWithQuery}\n${body}`;
const v1 = crypto.createHmac("sha256", keySecret).update(payload).digest("hex");
headers["Vouchereto-Signature"] = `t=${t},v1=${v1}`;

Idempotenz

Jeder POST braucht einen Idempotency-Key-Header. Wiederholst du eine Anfrage mit demselben Schlüssel, erhältst du die ursprüngliche Antwort zurück, markiert mit Idempotent-Replayed: true. Schlüssel werden mindestens 30 Tage aufbewahrt.

Sandbox-Gutscheine

Mit einem Testschlüssel erstellt POST /v1/sandbox/vouchers einen Testgutschein im gewünschten Status (active, reserved, redeemed, expired, risk_hold oder void) und gibt seinen Code zurück. Testschlüssel sehen immer nur Testdaten.

Webhook-Events

Events, die wir an deinen Endpunkt senden
EventWann es gesendet wird
redemption.capturedEin reservierter Gutschein wurde erfasst. Das gutgeschriebene Guthaben kann bleiben.
redemption.cancelledEine Reservierung wurde storniert. Der Gutschein ist wieder aktiv.
redemption.expiredEine Reservierung ist ohne Erfassung abgelaufen.
checkout.completedEin gehosteter Checkout wurde bezahlt und der Gutschein eingelöst.
checkout.expiredEine gehostete Checkout-Sitzung ist ohne Zahlung abgelaufen.
checkout.failedEin bezahlter Checkout wurde rückgängig gemacht, zum Beispiel nach einer Erstattung.

Fehler

Fehlercodes und was du dem Kunden sagst
StatusCodeWas du dem Kunden sagst
404VOUCHER_INVALIDWir konnten diesen Code nicht finden. Prüfe ihn und versuche es erneut.
409VOUCHER_ALREADY_REDEEMEDDieser Gutschein wurde bereits eingelöst.
409VOUCHER_RESERVEDDieser Gutschein wird gerade in einer anderen Zahlung verwendet.
422VOUCHER_EXPIREDDieser Gutschein ist abgelaufen.
422UNIVERSAL_NOT_ACCEPTEDWir akzeptieren keine Universal-Gutscheine. Verwende einen Gutschein für diese Website.
422CURRENCY_MISMATCHDieser Gutschein lautet auf eine andere Währung.
429TOO_MANY_INVALID_ATTEMPTSZu viele Versuche. Warte ein paar Minuten und versuche es erneut.

Fehler folgen RFC 7807 (application/problem+json) mit einem stabilen Code und einer request_id.

Diese Seite fasst die API zusammen. Die vollständige Referenz mit allen Feldern findest du unter www.vouchereto.com/docs/reference.

Irgendwo hängen geblieben?

Schreib an [DEVELOPER SUPPORT EMAIL]. Jede Nachricht liest ein Entwickler.