Überblick über Zahlungs-Sandboxes
Eine Zahlungs-Sandbox ist deine eigene Kopie der API eines Zahlungsanbieters. Solche Anbieter heißen üblicherweise PSP, kurz für Payment Service Provider, und die App nutzt dieses Wort ebenfalls.
Die Sandbox nimmt die Aufrufe entgegen, die deine Integration ohnehin macht, unter denselben Pfaden, und antwortet in den Strukturen und Statuscodes des PSP.
Nützlich ist sie, weil sie Zustand hält. Autorisiere eine Zahlung, ziehe sie in einem späteren Aufruf ein und erstatte danach einen Teil: Es bleibt durchgehend eine Zahlung und sind nicht drei unabhängige Antworten.
Dieser Zustand ist bewusst kurzlebig. Eine Zahlung und ihre Historie bleiben etwa einen Tag, eine gehostete Checkout-Sitzung 15 Minuten und eine 3D-Secure-Abfrage 5 Minuten. Das reicht für einen Testlauf oder einen Nachmittag Fehlersuche, und es ist kein Ort, um Aufzeichnungen aufzubewahren.
Der Zahlungslebenszyklus
Eine Zahlung durchläuft die Zustände, die auch der Anbieter nutzt:
- Autorisieren reserviert das Geld. Eine Zahlung, die keinen getrennten Einzug braucht, ist sofort abgeschlossen, so wie manche Anbieter arbeiten.
- Einziehen holt es. Ziehe den ganzen Betrag ein, einen Teil davon, oder mehrfach bis zur autorisierten Höhe.
- Erstatten gibt es zurück, ganz oder in Teilen.
- Stornieren gibt eine Autorisierung frei, die nie eingezogen wurde.
- Anpassen erhöht oder senkt eine Autorisierung vor dem Einzug.
Zwei Randfälle sind nachgebildet, weil echte Integrationen darauf stoßen: eine nie eingezogene Zahlung zu erstatten, was sie stattdessen storniert, und eine bereits eingezogene zu stornieren, was sie stattdessen erstattet. Eine Autorisierung über null zur Kartenprüfung funktioniert ebenfalls.
Nicht jeder PSP kann das alles, und die Sandbox tut nicht so. Jede Marke gibt Version für Version an, was sie unterstützt, und die App zeigt es im Tab Überblick der Marke als Funktionen wie capture, partialCapture, partialRefund, threeDS und idempotency.
3D Secure ohne Handarbeit
Kartenzahlungen, die eine Authentifizierung brauchen, durchlaufen den vollständigen 3DS2-Ablauf. Je nachdem, was du anforderst, kann eine Zahlung:
- reibungslos durchlaufen, ganz ohne Abfrage,
- zuerst einen Device-Fingerprint erheben und davon abhängen lassen, ob der Zahler überhaupt gefragt wird,
- oder bei einer Abfrage stehen bleiben, als Einmalcode, als Weiterleitung oder als Freigabe in einer Banking-App.
Die Sandbox liefert die Abfrageseite selbst aus, ein Test kommt also bis zum Ende durch. Genau das lässt sich gegen die Sandbox eines Anbieters sonst nicht automatisieren, weil dort ein Mensch klicken muss.
Zahlarten, die deine Seite verlassen
Wallets, Banküberweisungen und lokale Zahlarten schicken den Zahler woandershin und warten, bis er zurückkommt. Die Sandbox liefert auch diese Seite aus, und die Zahlung bleibt so lange in einem wartenden Zustand, bis sie freigegeben oder abgebrochen wird, genau wie in der Produktion. Anbieter mit einer gehosteten Checkout-Seite funktionieren genauso: Du legst die Sitzung an, bekommst eine URL, und mit dem Abschluss ist die Zahlung erledigt.
Idempotenz-Schlüssel
Sende denselben Idempotenz-Schlüssel zweimal, und du bekommst das erste Ergebnis zurück statt einer zweiten Belastung, bei den Anbietern, die das unterstützen. Dieses Verhalten ist anderswo schwer zu testen, denn dafür muss sich ein Anbieter deinen Schlüssel wirklich merken.
Was zurückkommt
Antwortkörper, Feldnamen und HTTP-Statuscodes sind die des PSP. Eine Client-Bibliothek, die für den Anbieter geschrieben wurde, läuft unverändert. Das ist der ganze Punkt: Du änderst eine Basis-URL und sonst nichts.
Jede Zahlung trägt ihre eigene Historie, ihre Einzüge und Erstattungen gehören also dazu und sind keine getrennten Einträge, die du zusammensuchen musst. In der App kannst du sie nach Referenz, Betrag, Status, Zahlart oder Zahler durchsehen.
Siehe Aktivität einer Sandbox.
Das Ergebnis bestimmen
Du wartest nicht ab, was die Sandbox gerade tun möchte. Benenne den Karteninhaber, die E-Mail des Zahlers oder den Betrag nach dem Ergebnis, das du willst, und genau das kommt zurück, im Ablehnungscode des Anbieters.
Siehe Zahlungsszenarien.
Wo sie antwortet
Jeder Anbieter ist unter einem eigenen Präfix eingehängt, das Marke, API und Version trägt:
https://<domain>/pay/<deine-org>/<name>/adyen/checkout/v71/paymentsAlles nach dem Präfix ist der Pfad des Anbieters. Eine Sandbox kann mehrere Anbieter gleichzeitig bedienen, jeden unter seinem eigenen Präfix.
Siehe Sandbox anlegen.