Betalinger med Wealth Reader

Arkitektur i to trinn

Betalingsintegrasjon følger en streng ansvarsfordeling i to trinn:

sequenceDiagram
autonumber
actor Usuario as Bruker
participant Front as Frontend (handel)
participant Back as Backend (handel)
participant API as API Wealth Reader
participant Widget as Widget-betalinger
participant Banco as Bank (SCA)
Note over Back,API: Forrige steg (kun administrerte profiler)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Profilkatalog (institution_code)
Note over Back,API: Trinn 1: Å skape den uforanderlige intensjonen (Server-til-Server)
Back->>API: POST /payments/?action=create (med X-API-Key og Idempotency-Key)
API-->>Back: 201 med payment.id + payment.widget.token flyktig
Note over Front,Widget: Steg 2: Last inn og godkjenn i widgeten (nettleseren)
Back->>Front: Levering payment.id og payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) eller load-payments.js
Widget->>Usuario: Den har en uforanderlig enhet, mengde og konsept
Usuario->>Widget: Autoriser betaling
Widget->>Banco: Omdirigering / App to App (SCA)
Banco->>API: Tilbakevending av SCA til callback av Wealth Reader
API-->>Widget: Teknisk bekreftelse av godkjenning
Note over Back,API: Finansiell avstemming og bekreftelse
loop Til terminaltilstand
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Trinn 1 (Sikker backend): Serveren din oppretter en betalingsintensjon (POST /payments/?action=create) med ditt X-API-Key, en Idempotency-Key og Content-Type: application/json. I denne samtalen er beløpet (amount_minor, i cent), valutaen (currency, i dag bare EUR), mottakeren (beneficiary.name og beneficiary.iban), konseptet med kontoutskriften (reference), dens interne referanse (customer_reference) og tillatt webopprinnelse (allowed_origin) uforanderlig fast. Disse seks feltene er obligatoriske, og kroppen er en streng hviteliste: alle ikke-anerkjente felt returnerer 422 invalid_request.
2. Svar: 201 med {"success": true, "payment": {…}} — eller 200 hvis det er en idempotent repetisjon. Intensjons-ID-en kommer i payment.id og widgetens flyktige token i payment.widget.token.
3. Trinn 2 (Frontend for handelen): Nettleseren monterer widgeten ved hjelp av det offisielle load-payments.js -skriptet eller WealthReaderPayments.mount()-funksjonen, og leverer kun payment.id og payment.widget.token. Brukeren velger sin bank (hvis den ikke var forhåndsvalgt i hensikten) og fullfører den sterke autentiseringen (SCA) i bankgrensesnittet.
4. Finansiell bekreftelse: Din backend spør etter betalingsstatus ved hjelp av POST /payments/?action=status, hvis kropp er nøyaktig {"payment_intent_id": "<id>"}. Ingen webhook: Den sjekker til den når en terminal tilstand.

To betalingsmodeller

Wealth Reader støtter to modeller avhengig av virksomhetens behov:

1. Standardintegrasjon for handelsmenn (egen begunstiget):
   • Handelsmannen definerer fritt navn og IBAN til mottakeren, beløpet, valutaen (EUR), konseptet og dets ordrereferanse.
   • Du kan filtrere hvilke banker som skal gjøres tilgjengelige for brukeren ved å bruke allowed_institution_codes eller tillate hele katalogen.
2. Administrerte profiler (som cruz_roja_demo):
   • Designet for donasjoner og offentlige demonstrasjoner.
   • Serveren setter de offisielle destinasjonskontoene for å sikre at midlene kun kan dirigeres til veldedigheten (for eksempel Spanske Røde Kors med beløp mellom 0,01 EUR og 1,00 EUR).

Enhetlig katalog over bankenheter

Wealth Reader gir en samlet katalog over europeiske enheter forberedt for betalingsinitiering via PSD2 gjennom:

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

Den lar deg få tak i en liste over banker med deres standardiserte navn, logoer, støttede overføringsmetoder og tekniske krav (som behovet for å be om skyldnerens IBAN fra betaleren). Den støtter filtrene country, search (alias q), code, payment_method, limit og offset.

Dette endepunktet er offentlig: det krever ikke X-API-Key. Å sende det bidrar ikke med noe og bruker et kall fra passordkvoten din.

Bruk alltid disse kodene slik de kommer inn i code. Å lage intensjonen validerer allowed_institution_codesformateringen, men sjekker ikke at de finnes i katalogen: feilstavet kode feiler ikke ved opprettelse og vises senere som en tom bankplukker.

Ansvarsfordeling

• Betalingstilgangsnøkkelen (X-API-Key) brukes kun fra server til server. Den bør aldri inkluderes i frontend eller offentlige repositorier.
• Nettleseren mottar kun identifikatoren til intensjonen og en kortvarig efemær token knyttet til opprinnelsen HTTPS.
• Widgeten kan ikke endre beløp, valuta, mottaker, konsept eller autoriserte institusjoner.
• Å lukke modalen eller widgeten er ikke en erstatning for å kontrollere betalingens finansielle status fra backend.
• Betalinger deler ikke tilgangsnøkler, tokens eller tilbakeringinger med Wealth Readersitt bankaggregationsprodukt.

Tilgangsnøkler og kvote

Betalingspassnøkkelen din må ha produktet PAYMENTS aktivert; hvis ikke, svarer API 403 payments_not_allowed. En manglende eller feilformatert passnøkkel returnerer 401 invalid_api_key.

Neste steg

Fortsett med Integrasjon og widget.