Maksut Wealth Reader

Arkkitehtuuri kahdessa vaiheessa

Maksujen integrointi noudattaa tiukkaa vastuunjakoa kahteen vaiheeseen:

sequenceDiagram
autonumber
actor Usuario as Käyttäjä
participant Front as Frontend (kaupankäynti)
participant Back as Backend (kaupankäynti)
participant API as API Wealth Reader
participant Widget as Widget-maksut
participant Banco as Pankki (SCA)
Note over Back,API: Edellinen vaihe (vain hallinnoidut profiilit)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Profiililuettelo (institution_code)
Note over Back,API: Vaihe 1: Muuttumattoman intention luominen (palvelimelta palvelimelle)
Back->>API: POST /payments/?action=create (yhdessä X-API-Key ja Idempotency-Keykanssa)
API-->>Back: 201 payment.id + payment.widget.token ohimenevä
Note over Front,Widget: Vaihe 2: Lataa ja valtuuta widgetissä (selain)
Back->>Front: Toimitus payment.id ja payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) vai load-payments.js
Widget->>Usuario: Näyttää muuttumattoman pankin, summan ja maksun viestin
Usuario->>Widget: Valtuuta maksu
Widget->>Banco: Uudelleenohjaus / Sovellus toiseen (SCA)
Banco->>API: Paluu SCA callback Wealth Reader
API-->>Widget: Tekninen vahvistus valtuutuksesta
Note over Back,API: Taloudellinen sovitus ja vahvistus
loop Päätetilaan
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Vaihe 1 (Turvallinen taustajärjestelmä): Palvelimesi luo maksuaikomuksen (POST /payments/?action=create) X-API-Key, Idempotency-Key ja Content-Type: application/jsonavulla. Tässä puhelussa summa (amount_minor, sentteinä), valuutta (currency, tänään vain EUR), edunsaaja (beneficiary.name ja beneficiary.iban), tiliotteella näkyvä maksun viesti (reference), sen sisäinen viite (customer_reference) ja sallittu verkkoalkuperä (allowed_origin) ovat muuttumattomasti kiinteitä. Nämä kuusi kenttää ovat pakollisia, ja runko on tiukka valkoinen lista: kaikki tunnistamattomat kentät palauttavat 422 invalid_request.
2. Vastaus: 201 {"success": true, "payment": {…}} — tai 200, jos kyseessä on idempotentti toisto. Intent ID tulee payment.id ja widgetin katoava token payment.widget.token.
3. Vaihe 2 (Kaupan käyttöliittymä): Selain liittää widgetin virallisella load-payments.js -skriptillä tai WealthReaderPayments.mount()-toiminnolla, toimittaen vain payment.id ja payment.widget.token. Käyttäjä valitsee pankkinsa (jos sitä ei ole ennakkovalittu tarkoituksessa) ja suorittaa vahvan tunnistautumisen (SCA) pankkikäyttöliittymässä.
4. Taloudellinen vahvistus: Taustajärjestelmäsi kysyy maksun tilaa POST /payments/?action=status:n avulla, jonka runko on täsmälleen {"payment_intent_id": "<id>"}. Ei webhookia: Se kysyy, kunnes saavuttaa lopputilan.

Kaksi maksumallia

Wealth Reader tukee kahta mallia yrityksen tarpeiden mukaan:

1. Vakiointegraatio kauppiaille (oma edunsaaja):
   • Kauppias määrittelee vapaasti edunsaajan nimen ja IBAN , summan, valuutan (EUR), käsitteen ja sen tilausviitteen.
   • Voit suodattaa, mitkä pankit saat käyttäjälle allowed_institution_codes avulla tai sallia koko katalogin.
2. Hallinnoidut profiilit (kuten cruz_roja_demo):
   • Suunniteltu lahjoituksia ja julkisia esittelyjä varten.
   • Palvelin asettaa viralliset kohdetilit varmistaakseen, että varat voidaan ohjata vain hyväntekeväisyysjärjestölle (esimerkiksi Espanjan Punaiselle Ristille, jonka summat ovat välillä 0,01 EUR – 1,00 EUR).

Yhtenäinen pankkiyksiköiden hakemisto

Wealth Reader tarjoaa yhtenäisen luettelon eurooppalaisista toimijoista, jotka on valmisteltu maksujen aloittamista varten PSD2 kautta:

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

Sen avulla voit saada pankkien listan niiden standardoiduilla nimillä, logoilla, tuetuilla siirtomenetelmillä ja teknisillä vaatimuksilla (kuten tarve pyytää velallisen IBAN maksajalta). Se tukee suodattimia country, search (alias q), code, payment_method, limit ja offset.

Tämä päätepiste on julkinen: se ei vaadi X-API-Key. Sen lähettäminen ei tuota mitään ja kuluttaa yhden kutsun API-avaimesi kiintiöstä.

Käytä näitä koodeja aina sellaisina kuin ne tulevat code. Intentin luominen vahvistaa allowed_institution_codesmuotoilun, mutta ei tarkista, että ne ovat luettelossa: väärin kirjoitettu koodi ei epäonnistu luomisessa ja näkyy myöhemmin tyhjänä pankkipoimijana.

Vastuunjako

• Maksun käyttöavainta (X-API-Key) käytetään vain palvelimelta toiselle. Sitä ei tulisi koskaan sisällyttää frontend- tai julkisiin tietovarastoihin.
• Selain vastaanottaa vain tarkoituksen tunnisteen ja lyhytikäisen ohimenevän token , joka liittyy alkuperään HTTPS.
• Widget ei voi muuttaa summaa, valuuttaa, edunsaajaa, konseptia tai valtuutettuja laitoksia.
• Modaalin tai widgetin sulkeminen ei korvaa maksun tilan kyselyä taustalla.
• Maksut eivät jaa pääsyavaimia, tokeneita tai takaisinsoittoja Wealth Reader:n pankkien aggregointituotteen kanssa.

Pääsyavaimet ja kutsukiintiö

Maksuavaimessasi täytyy olla tuotteen PAYMENTS päällä; jos ei, API vastaa 403 payments_not_allowed. Puuttuva tai väärin muotoiltu API-avain palauttaa 401 invalid_api_key.

Seuraava askel

Jatka Integraatio ja widget.