Plăți cu Wealth Reader

Arhitectura în doi pași

Integrarea plăților urmează o separare strictă a responsabilităților în doi pași:

sequenceDiagram
autonumber
actor Usuario as Utilizator
participant Front as Frontend (Comerț)
participant Back as Backend (Comerț)
participant API as API Wealth Reader
participant Widget as Plăți prin widget-uri
participant Banco as Bancă (SCA)
Note over Back,API: Pasul anterior (doar profiluri gestionate)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Catalog de profil (institution_code)
Note over Back,API: Pasul 1: Crearea intenției imuabile (Server-la-server)
Back->>API: POST /payments/?action=create (cu X-API-Key și Idempotency-Key)
API-->>Back: 201 cu payment.id + payment.widget.token efemer
Note over Front,Widget: Pasul 2: Încarcă și autorizează în widget (browser)
Back->>Front: Livrarea payment.id și payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) sau load-payments.js
Widget->>Usuario: Are o entitate, o cantitate și un concept imutable
Usuario->>Widget: Autorizarea plății
Widget->>Banco: Redirecționează / Aplicație către aplicație (SCA)
Banco->>API: Întoarcerea SCA la callback Wealth Reader
API-->>Widget: Confirmare tehnică a autorizării
Note over Back,API: Reconciliere și confirmare financiară
loop Până la starea terminală
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Pasul 1 (Backend securizat): Serverul tău creează o intenție de plată (POST /payments/?action=create) cu X-API-Key, un Idempotency-Key și Content-Type: application/json. În acest apel, suma (amount_minor, în cenți), moneda (currency, astăzi doar EUR), beneficiarul (beneficiary.name și beneficiary.iban), conceptul extrasului (reference), referința sa internă (customer_reference) și originea web permisă (allowed_origin) sunt fixate imuabil. Aceste șase câmpuri sunt obligatorii, iar corpul este o listă albă strictă: orice câmp nerecunoscut returnează 422 invalid_request.
2. Răspuns: 201 cu {"success": true, "payment": {…}} — sau 200 dacă este o repetiție idempotentă. ID-ul intenției apare înpayment.id, iar token efemer al widget-ului în payment.widget.token.
3. Pasul 2 (Frontend al tranzacției): Browserul montează widget-ul folosind scriptul oficial load-payments.js sau funcția WealthReaderPayments.mount(), livrând doar payment.id și payment.widget.token. Utilizatorul își selectează banca (dacă nu a fost preselectată în intenție) și completează autentificarea puternică (SCA) în interfața bancară.
4. Confirmare financiară: Backend-ul tău interoghează starea plății folosind POST /payments/?action=status, al cărui corp este exact {"payment_intent_id": "<id>"}. Fără webhook: Interogează până ajunge la o stare terminală.

Două modele de plată

Wealth Reader susține două modele, în funcție de nevoile afacerii:

1. Integrare standard pentru comercianți (beneficiar propriu):
   • Negustorul definește liber numele și IBAN beneficiarului, suma, moneda (EUR), conceptul și referința ordinului său.
   • Poți filtra ce bănci să pui la dispoziția utilizatorului folosind allowed_institution_codes sau poți permite întregul catalog.
2. Profiluri gestionate (cum ar fi cruz_roja_demo):
   • Concepută pentru donații și demonstrații publice.
   • Serverul setează conturile oficiale de destinație pentru a se asigura că fondurile pot fi direcționate doar către organizația caritabilă (de exemplu, Crucea Roșie Spaniolă cu sume între 0,01 EUR și 1,00 EUR).

Directorul unificat al entităților bancare

Wealth Reader oferă un catalog unificat al entităților europene pregătite pentru inițierea plății prin PSD2 prin:

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

Îți permite să obții lista băncilor cu denumirile lor standardizate, logo-urile, metodele de transfer suportate și cerințele tehnice (cum ar fi necesitatea de a solicita IBAN debitorului de la plătitor). Suportă filtrele country, search (alias q), code, payment_method, limit și offset.

Acest endpoint este public: nu necesită X-API-Key. Trimiterea nu contribuie cu nimic și consumă un apel din cota ta de parolă.

Folosește întotdeauna aceste coduri pe măsură ce vin în code. Crearea intenției validează formatarea allowed_institution_codes, dar nu verifică dacă acestea există în catalog: codul greșit nu dă greșit la creare și apare ulterior ca un colector bancar gol.

Separarea responsabilităților

• Cheia de acces la plată (X-API-Key) este folosită doar de la un server la altul. Nu ar trebui niciodată inclusă în frontend-ul sau în depozitele publice.
• Browserul primește doar identificatorul intenției și un token efemer de scurtă durată legat de originea HTTPS.
• Widgetul nu poate modifica suma, moneda, beneficiarul, conceptul sau instituțiile autorizate.
• Închiderea ferestrei modale sau a widget-ului nu înlocuiește interogarea situației financiare în backend.
• Plățile nu partajează cheile de acces, token-urile sau callback-urile cu produsul de agregare bancară al Wealth Reader.

Date de autentificare și cotă de apeluri

Cheia ta de acces pentru plăți trebuie să aibă produsul PAYMENTS activat; dacă nu, API răspunde 403 payments_not_allowed. O cheie de acces lipsă sau formatată incorect returnează 401 invalid_api_key.

Pasul următor

Continuă cu Integrare și widget.