Betalinger med Wealth Reader

Arkitektur i to trin

Betalingsintegrationen adskiller ansvarsområderne strengt i to trin:

sequenceDiagram
autonumber
actor Usuario as Bruger
participant Front as Frontend (Forhandler)
participant Back as Backend (Forhandler)
participant API as Wealth Reader API
participant Widget as Widget Payments
participant Banco as Bankinstitut (SCA)
Note over Back,API: Forberedende trin (kun administrerede profiler)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Profilkatalog (institution_code)
Note over Back,API: Trin 1: Opret uforanderlig betalingsintention (Server-to-Server)
Back->>API: POST /payments/?action=create (med X-API-Key og Idempotency-Key)
API-->>Back: 201 med payment.id + kortlivet payment.widget.token
Note over Front,Widget: Trin 2: Indlæs widget og godkend (Browser)
Back->>Front: Sender payment.id og payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) eller load-payments.js
Widget->>Usuario: Viser uforanderligt institut, beløb og betalingstekst
Usuario->>Widget: Godkender betalingen
Widget->>Banco: Omdirigering / App to App (SCA)
Banco->>API: SCA-retur til Wealth Readers callback
API-->>Widget: Teknisk bekræftelse af godkendelsen
Note over Back,API: Afstemning og finansiel bekræftelse
loop Indtil en endelig status
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Trin 1 (Sikker backend): Din server opretter en betalingsintention (POST /payments/?action=create) med din X-API-Key, en Idempotency-Key og Content-Type: application/json. Dette kald fastlåser beløbet (amount_minor, i cent), valutaen (currency, i øjeblikket kun EUR), modtageren (beneficiary.name og beneficiary.iban), teksten på kontoudtoget (reference), din interne reference (customer_reference) og den tilladte weboprindelse (allowed_origin). Disse seks felter er obligatoriske, og anmodningens indhold følger en streng positivliste: Ethvert ukendt felt medfører 422 invalid_request.
2. Svar: 201 med {"success": true, "payment": {…}} — eller 200, hvis det er en idempotent gentagelse. Betalingsintentionens identifikator findes i payment.id, og widgettens kortlivede token findes i payment.widget.token.
3. Trin 2 (Forhandlerens frontend): Browseren indlæser widgetten med det officielle script load-payments.js eller funktionen WealthReaderPayments.mount() og sender udelukkende payment.id og payment.widget.token. Brugeren vælger sin bank (hvis den ikke allerede er valgt i betalingsintentionen) og gennemfører stærk kundeautentifikation (SCA) i bankens grænseflade.
4. Finansiel bekræftelse: Din backend henter status med POST /payments/?action=status, hvor anmodningens indhold er præcis {"payment_intent_id": "<id>"}. Der er ingen webhook: Status forespørges løbende, indtil en endelig status nås.

To betalingsmodeller

Wealth Reader understøtter to modeller afhængigt af virksomhedens behov:

1. Standardintegration for forhandlere (Egen modtager):
   • Forhandleren vælger frit modtagerens navn og IBAN, beløb, valuta (EUR), betalingstekst og ordrereference.
   • Med allowed_institution_codes kan forhandleren begrænse de banker, brugeren kan vælge, eller tillade hele kataloget.
2. Administrerede profiler (som cruz_roja_demo):
   • Udviklet til donationer og offentlige demonstrationer.
   • Serveren fastlægger de officielle modtagerkonti, så pengene kun kan sendes til velgørenhedsorganisationen (for eksempel Spansk Røde Kors med beløb mellem 0,01 EUR og 1,00 EUR).

Fælles katalog over bankinstitutter

Wealth Reader tilbyder et fælles katalog over europæiske institutter, der understøtter betalingsinitiering via PSD2, gennem:

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

Det giver en bankliste med standardiserede navne, logoer, understøttede overførselsmetoder og tekniske krav (såsom behovet for at bede betaleren om debitors IBAN). Filtrene country, search (alias q), code, payment_method, limit og offset understøttes.

Dette endpoint er offentligt: Det kræver ikke X-API-Key. Det giver ingen fordel at sende nøglen, og det bruger et kald fra adgangsnøglens kvote.

Brug altid koderne præcis som returneret i code. Ved oprettelse af betalingsintentionen valideres formatet af allowed_institution_codes, men ikke om koderne findes i kataloget: En forkert stavet kode giver ikke fejl ved oprettelsen, men resulterer senere i en tom bankvælger.

Adskillelse af ansvarsområder

• Betalingsadgangsnøglen (X-API-Key) bruges udelukkende fra server til server. Den må aldrig indgå i frontend eller offentlige kodearkiver.
• Browseren modtager kun betalingsintentionens identifikator og et kortlivet token, der er bundet til HTTPS-oprindelsen.
• Widgetten kan ikke ændre beløb, valuta, modtager, betalingstekst eller tilladte institutter.
• Lukning af modalen eller widgetten erstatter ikke forespørgslen om finansiel status i backend.
• Betalinger deler hverken adgangsnøgler, tokens eller callbacks med Wealth Readers bankaggregeringsprodukt.

Adgangsnøgler og kvote

Produktet PAYMENTS skal være aktiveret for din betalingsadgangsnøgle; ellers svarer API’et med 403 payments_not_allowed. En manglende eller forkert formateret adgangsnøgle giver 401 invalid_api_key.

Næste trin

Fortsæt med Integration og widget.