Betalingen met Wealth Reader

Architectuur in twee stappen

Betalingsintegratie volgt een strikte scheiding van verantwoordelijkheden in twee stappen:

sequenceDiagram
autonumber
actor Usuario as Gebruiker
participant Front as Frontend (Commerce)
participant Back as Backend (Commerce)
participant API as API Wealth Reader
participant Widget as Widgetbetalingen
participant Banco as Bank (SCA)
Note over Back,API: Vorige stap (alleen beheerde profielen)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Profielcatalogus (institution_code)
Note over Back,API: Stap 1: Het creëren van de onveranderlijke intentie (Server-to-Server)
Back->>API: POST /payments/?action=create (met X-API-Key en Idempotency-Key)
API-->>Back: 201 met payment.id + payment.widget.token vluchtig
Note over Front,Widget: Stap 2: Laden en autoriseer in de widget (browser)
Back->>Front: Bezorging payment.id en payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) of load-payments.js
Widget->>Usuario: Toont de onveranderlijke bank, het bedrag en de betalingsomschrijving
Usuario->>Widget: Betaling autoriseren
Widget->>Banco: Doorverwijzing / App naar App (SCA)
Banco->>API: Terugkeer van de SCA naar de callback van Wealth Reader
API-->>Widget: Technische bevestiging van de autorisatie
Note over Back,API: Financiële verzoening en bevestiging
loop Naar terminale toestand
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Stap 1 (Secure Backend): Je server creëert een betalingsintentie (POST /payments/?action=create) met je X-API-Key, een Idempotency-Key en Content-Type: application/json. In dit gesprek zijn het bedrag (amount_minor, in centen), de munteenheid (currency, tegenwoordig slechts EUR), de begunstigde (beneficiary.name en beneficiary.iban), de betalingsomschrijving op het afschrift (reference), de interne referentie (customer_reference) en de toegestane weboorsprong (allowed_origin) onveranderlijk vastgelegd. Die zes velden zijn verplicht, en het lichaam is een strikte whitelist: elk niet-erkend veld keert terug 422 invalid_request.
2. Antwoord: 201 met {"success": true, "payment": {…}} — of 200 als het een idempotente herhaling is. De intentie-ID komt in payment.id en de vluchtige token van de widget in payment.widget.token.
3. Stap 2 (Frontend van de transactie): De browser mountt de widget met het officiële load-payments.js -script of de WealthReaderPayments.mount()functie, waarbij alleen de payment.id en payment.widget.tokenworden geleverd. De gebruiker selecteert zijn bank (als deze niet vooraf was geselecteerd in de bedoeling) en voltooit de sterke authenticatie (SCA) in de bankinterface.
4. Financiële bevestiging: Je backend vraagt de staat met POST /payments/?action=status, waarvan het lichaam precies {"payment_intent_id": "<id>"}is. Geen webhook: Het pollt totdat het een terminale toestand bereikt.

Twee betalingsmodellen

Wealth Reader ondersteunt twee modellen, afhankelijk van de behoeften van het bedrijf:

1. Standaardintegratie voor handelaren (Eigen begunstigde):
   • De handelaar bepaalt vrij de naam en IBAN van de begunstigde, het bedrag, de munteenheid (EUR), het concept en de orderreferentie.
   • Je kunt filteren welke banken beschikbaar worden gesteld aan de gebruiker met allowed_institution_codes of de hele catalogus toestaan.
2. Beheerde profielen (zoals cruz_roja_demo):
   • Ontworpen voor donaties en openbare demonstraties.
   • De server stelt de officiële bestemmingsrekeningen in om ervoor te zorgen dat de fondsen alleen naar het goede doel kunnen worden gestuurd (bijvoorbeeld het Spaanse Rode Kruis met bedragen tussen 0,01 EUR en 1,00 EUR).

Geïntegreerde directory van bankentiteiten

Wealth Reader biedt een uniforme catalogus van Europese entiteiten die zijn voorbereid voor betalingsinitiatie via PSD2 door:

• GET https://api.wealthreader.com/payments/entities/?country=ES

Het stelt u in staat om de lijst van banken te verkrijgen met hun gestandaardiseerde namen, logo's, ondersteunde overboekingsmethoden en technische vereisten (zoals de noodzaak om de IBAN van de schuldenaar aan de betaler op te vragen). Het ondersteunt de filters country, search (alias q), code, payment_method, limit en offset.

Dit eindpunt is openbaar: het vereist geen X-API-Key. Het verzenden ervan draagt niets bij en verbruikt een aanroep van je toegangscodequotum.

Gebruik deze codes altijd zoals ze in codekomen. Het creëren van de intentie valideert de allowed_institution_codesopmaak, maar controleert niet of ze in de catalogus bestaan: verkeerd gespelde code faalt niet bij het aanmaken en verschijnt later als een lege bankplocker.

Scheiding van verantwoordelijkheden

• De betalingstoegangssleutel (X-API-Key) wordt alleen van server naar server gebruikt. Deze mag nooit worden opgenomen in frontend- of openbare repositories.
• De browser ontvangt alleen de identificatie van de intentie en een kortstondige vluchtige token gekoppeld aan de oorsprong HTTPS.
• De widget kan het bedrag, de geldeenheid, de begunstigde, het concept of de geautoriseerde instellingen niet wijzigen.
• Het sluiten van de modal of widget is geen vervanging voor het opvragen van de betalingsstatus in de backend.
• Betalingen delen geen toegangssleutels, tokens of callbacks met het bankaggregatieproduct van Wealth Reader.

Toegangssleutels en oproepquotum

Je betalingstoegangssleutel moet het product PAYMENTS ingeschakeld hebben; zo niet, dan reageert de API 403 payments_not_allowed. Een ontbrekende of verkeerd geformatteerde toegangssleutel keert 401 invalid_api_keyterug.

Volgende stap

Ga verder met Integratie en widget.