API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

PSD2-pohjaiset sääntely-API:t tarjoavat pääsyn tiettyihin taloudellisiin tietoihin, kuten pankkitilisaldoihin ja tapahtumiin. On kuitenkin olemassa muita varallisuustietojen lähteitä, jotka eivät ole saatavilla näiden API:iden kautta. Wealth Reader API laajentaa sääntely-API:iden tarjoamia tietoja tarjoamalla reaaliaikaisen pääsyn lisävarallisuuslähteisiin missä tahansa maailmanlaajuisessa yksikössä. On olemassa kaksi muuta liittyvää asiakirjaa, jotka auttavat sinua integroimaan Wealth Reader API:n. Toinen on Javascript-widgetin integraatio-opas: https://docs-en.wealthreader.com/ ja toinen on Postman-kokoelma, joka perustuu tähän dokumentaatioon. Erittäin tärkeää: Tämä API-määrittely on mukautettu asiakkaille, jotka integroivat Widgetin kautta, joten jotkin parametrit, joita ei tarvita tällaisessa integraatiossa, on jätetty pois, kuten pankkitunnistautumisen parametrit, koska tokenia käytetään.

Core

Ydin-API vaaditaan vakiointegraatioihin

Hakee taloudelliset varat ja niiden koostumustiedot

Hakee taloudelliset varat ja niiden koostumustiedot mukaan lukien sijoitussalkut koostuen osakkeista tai rahastoista, luottokortit, vakuutukset ja lainat. Sisältää omistustiedot jokaiselle varalle sekä yksilölliset tunnisteet, jotka helpottavat tietojen käsittelyä. On mahdollista saada Mock-tietoja. Tarkista tekniseltä tiimiltä miten tämä tehdään.

Request Body schema: application/x-www-form-urlencoded
api_key
string

Tunnistaa asiakkaan palvelussa

code
string

Yksikön nimi. Täydellinen luettelo on saatavilla GET-pyynnöllä

Esimerkki: caixabank

token
string

Tunnistaa säilytetyt tunnistetiedot. Kulku, jolla token on saatu, on kuvattu dokumentissa 'Widgetin integraatio-opas'. Seuraavat Mock-käyttäjät ovat saatavilla: MOCKDATA, OK-vastaus; MOCKOTP, vastaus OTP-haasteella; MOCKLOGINKO, vastaus kirjautumisvirheellä

Esimerkki: MOCKDATA

product_types
string
Enum: "accounts" "portfolios" "cards" "receipts" "loans" "factoring" "confirming" "properties" "invoices" "files" "deposits" "leases" "insurances"

Luettelo tuotetyypeistä, joista tiedot haetaan. Hyväksyy useita pilkuilla erotettuja arvoja.

Esimerkki: accounts,portfolios

only_balances
boolean
Default: false

Ilmoittaa, haetaanko vain tuotteiden saldot kaiken saatavilla olevan tiedon sijaan. Oletusarvo: false.

Esimerkki: false

fetch_transaction_details
boolean
Default: false

Ilmoittaa, haetaanko laajennetut tapahtumatiedot, kun entiteetin liitin tukee sitä. TÄRKEÄÄ: Sen käyttöönotto tarkoittaa yhden tai useamman lisänavigoinnin suorittamista tapahtumaa kohden palautettujen tietojen rikastamiseksi. Tämä lisää väistämättä ja merkittävästi suoritusaikaa. Lisänavigointien määrä kasvaa tapahtumien määrän mukana. On suositeltavaa ottaa se käyttöön vain, kun on varmaa, että tarvitaan oletuksena palautettua suurempaa yksityiskohtaisuutta. Haetut tiedot lisätään additional_info-avaimeen kunkin tapahtuman tasolla. Tämän parametrin käyttö edellyttää erillistä ympäristöä.

Esimerkki: false

date_from
string <date>

Päivämäärä, josta lähtien tapahtumia pyydetään, muodossa VVVV-KK-PP. Täytyy olla päivämäärä ennen tätä päivää.

Esimerkki: 2024-01-01

date_to
string <date>

Tämä koskee vain tulevien päivämäärien rajoittamista tuotteille loan ja confirming, muodossa VVVV-KK-PP. Päivämäärän on oltava tämän päivän jälkeen

Esimerkki: 2025-12-31

required_products_schema
string

Vaadittu tuoteskeema. Ilmoittaa tilit tai kortit, joista tietoja halutaan, lisäkonfiguraatioiden kanssa.

Esimerkki: 

{
  "ACCOUNTS": {
    "0ae4d722b1c82feeafb4b36b2893230444071335": {
      "only_balances": false,
      "add_pdf_from_uuids": [
        "90763109952d4f2ebece8dceca8254078c5384a0"
      ],
      "date_from": "2024-04-03"
    }
  },
  "CARDS": {
    "957e6f63546f3fecacce80192b6f7436496dc057": {}
  }
}
add_pdf_from_uuids
string

Hyväksyy tapahtuma-uuid:t pilkuilla erotettuna. Parametri, joka otetaan huomioon vain jos product_types on ALL tai sisältää accounts. Lisää kunkin pyydetyn pankkitapahtuman liittyvän PDF-dokumentin.

Esimerkki: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Valitsee kaksivaiheisen toimituskanavan, kun API palautti virhekoodin 2017 tai 20171 (useita OTP-tapoja). Kutsu uudelleen samalla istuntotunnisteella kuin tuossa vastauksessa ja aseta otp_method tarkaksi otp_method-kentän merkkijonoksi yhdestä statistics.otpMethods-objektista — ei taulukon indeksiä. Jätä pois ensimmäisestä tunnistepyynnöstä; lähetä käyttäjän valinnan jälkeen. Alla oleva esimerkki on ohjeellinen; kopioi aina merkkijono statistics.otpMethods-kentästä.

Esimerkki: OTP_SMS ****1234

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4e5f6g7h8i9j0&code=caixabank&token=1234Asdf&product_types=accounts%2Cportfolios&only_balances=false&date_from=2024-01-01&date_to=2025-12-31&required_products_schema=%7B%22ACCOUNTS%22%3A%7B%220ae4d722b1c82feeafb4b36b2893230444071335%22%3A%7B%22only_balances%22%3Afalse%2C%22add_pdf_from_uuids%22%3A%5B%2290763109952d4f2ebece8dceca8254078c5384a0%22%5D%2C%22date_from%22%3A%222024-04-03%22%7D%7D%2C%22CARDS%22%3A%7B%22957e6f63546f3fecacce80192b6f7436496dc057%22%3A%7B%7D%7D%7D&add_pdf_from_uuids=20966426721d0885ef9d4b95535e1d3198936f16%2C8772d6c978d37d7af83094abf380b8b703e94105

Response samples

Content type
application/json
[
  • {
    }
]

Tapahtumatyyppien luettelo

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Kysy api_key-tunnisteeseen liittyviä tokeneita

Käytä tätä menetelmää tiettyyn api_key-tunnisteeseen liittyvien tokenien kyselyyn. Tulokset sivutetaan: limit määrittää tokenien määrän sivua kohden (enintään 500) ja page valitsee palautettavan sivun. api_key, method ja limit ovat pakollisia; jos jokin niistä puuttuu tai on virheellinen, API vastaa HTTP 400 -tilalla ja virhekoodilla 2.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string^[a-z0-9]{8}$

api_key asiakkaan tunnistamiseksi palvelussa

method
required
string
Value: "get"

Suoritettava toiminto. Ainoa tuettu arvo on get.

Esimerkki: get

limit
required
integer [ 1 .. 500 ]

Tokenien määrä sivua kohden. Vähintään 1, enintään 500.

Esimerkki: 100

page
integer >= 1
Default: 1

Määritä sivunumero, jonka haluat hakea. Jokainen sivu sisältää enintään limit tokenia. Jos ei ole annettu, oletusarvo on 1.

Esimerkki: 1

code
string

Yksikkökoodi, jolla tokenit suodatetaan. Jos se jätetään pois, palautetaan kaikkien yksiköiden tokenit.

Esimerkki: bbva

sort_by
string
Default: "created_at"
Enum: "created_at" "accesed_at"

Kenttä, jonka mukaan tulokset lajitellaan: created_at (luomispäivämäärä) tai accesed_at (viimeinen käyttöpäivämäärä). Oletus created_at.

Esimerkki: created_at

sort_order
string
Default: "DESC"
Enum: "ASC" "DESC"

Lajittelujärjestys: ASC (nouseva) tai DESC (laskeva). Oletus DESC.

Esimerkki: DESC

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&method=get&limit=100&page=1

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "pagination": {
    },
  • "statistics": {
    }
}

Peruuta token

Tämä menetelmä mahdollistaa olemassa olevan tokenin peruuttamisen tulevien API-käyttöpyyntöjen estämiseksi.

Request Body schema: application/x-www-form-urlencoded
required
api_key
string

Tunnistaa asiakkaan palvelussa

token
string

Token, joka peruutetaan.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully revoked."
}

Määritä token uudelleen eri api_key-tunnisteelle

Tämä menetelmä mahdollistaa tokenin uudelleenmäärityksen yhdestä api_key-tunnisteesta toiseen. Molempien api_key-tunnisteiden on oltava aktiivisia ja kuuluttava samalle yritykselle, ja tokenin on kuuluttava api_key_source-tunnisteelle.

Request Body schema: application/x-www-form-urlencoded
required
api_key_source
string

api_key, josta token määritetään uudelleen.

api_key_target
string

api_key, johon token määritetään uudelleen.

token
string

Token, joka määritetään uudelleen.

Esimerkki: FRJ0mHlaqZwLzu

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key_source=a1b2c3d4e5f6g7h8i9j0&api_key_target=b2c3d4e5f6g7h8i9j0k1&token=FRJ0mHlaqZwLzu

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully reassigned."
}

Lisää uusi verkkotunnus

Lisää yhteyden widgetin isännöivän verkkotunnuksen ja kohde-webhookin välille. Verkkotunnusten muokkaamiseen tai testaamiseen käytä https://www.wealthreader.com/clients/

Request Body schema: application/x-www-form-urlencoded
required
method
required
string

Method to execute.

Esimerkki: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Esimerkki: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

Esimerkki: https://desarrollo.cliente.es/hooks/wealthreader

tokenize
required
string
Enum: "1" "0"

Määrittää aloittaako widget tokenisointiprosessin:

  • 1 - Käyttäjä tunnistautuu rahoituslaitokseen (kirjautuminen, suostumus, 2FA tarvittaessa) ja uudelleenkäytettävä token palautetaan
  • 0 - Tokenisointia ei suoriteta. Aiemmin saadun tokenin arvo on sisällytettävä pyyntöön

Esimerkki: 1

Responses

Request samples

Content type
application/x-www-form-urlencoded
method=add&api_key=a1b2c3d4e5f6g7h8i9j0&domain=https%3A%2F%2Fwww.cliente.com&url_callback=https%3A%2F%2Fwww.cliente.com%2Fwebhooks%2Fwealthreader&tokenize=1

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Virhekoodiluettelo

Virhekoodiluettelo. Kiinnitä erityistä huomiota siihen, että kaikkia virhekoodeja ei pitäisi käsitellä samalla tavalla sovelluksessasi. Väärän salasanan virheen kohdalla sinun ei pitäisi yrittää kutsua uudelleen samoilla parametreilla, mutta virheen kohdalla, joka osoittaa että entiteetti on huollossa, voit yrittää uudelleen. Pyydä teknistä istuntoa tiimimme kanssa ratkaistaksesi kaikki kysymykset virheenhallinnasta.

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Varoituskoodiluettelo

Varoituskoodiluettelo.

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Valinnaiset päätepisteet, joita ei vaadita vakiointegraatioihin. Käytä vain, jos Wealth Reader nimenomaisesti ohjeistaa.

Hakee tuettujen yksiköiden luettelon

Hakee tuettujen yksiköiden luettelon ja tiedot, jotka tarvitaan yksikön kirjautumislomakkeen piirtämiseen.

query Parameters
show_only_tested
integer
Default: 0
Enum: 0 1

Indicates whether to show only tested entities. Default value is 0. In production environments, always use 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Rekisteröi uusi käyttäjä

Tämä päätepiste on valinnainen eikä vaadita vakiointegraatioihin. Käytä vain jos Wealth Reader nimenomaisesti ohjeistaa. Tämä päätepiste mahdollistaa käyttäjän rekisteröinnin joko portfolion siirtoalustalle Easytransfer tai raportointityökalulle Acumulas, perustuen yksilölliseen tunnisteeseen.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

Esimerkki: 12345678A

service
required
string
Enum: "integra" "easy-transfer"

Service associated with the user. Determines the data flow.

Esimerkki: easy-transfer

email
required
string <email>

User email, used according to service type.

Esimerkki: sai_banker@singularbank.com

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User registered successfully"
}

Tarkista käyttäjän rekisteröintitila

Tämä päätepiste on valinnainen eikä vaadita vakiointegraatioihin. Käytä vain jos Wealth Reader nimenomaisesti ohjeistaa. Tarkistaa, onko käyttäjä rekisteröity Easytransfer- tai Acumulas-järjestelmään ja palauttaa käyttäjän yksilöllisen pääsylinkin.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key

user_id
required
string

User identification document.

Esimerkki: 12345678A

Responses

Response samples

Content type
application/json
{}

Peruuta aiemmin rekisteröity käyttäjä

Tämä päätepiste on valinnainen eikä vaadita vakiointegraatioihin. Käytä vain jos Wealth Reader nimenomaisesti ohjeistaa. Tämä päätepiste mahdollistaa käyttäjän poistamisen Easytransfer- tai Acumulas-alustapalvelusta.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

Esimerkki: 12345678A

service
required
string
Enum: "integra" "easy-transfer" "all"

Service from which to unregister the user. 'all' for all services.

Esimerkki: easy-transfer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User unregistered successfully"
}

Batch-yhteyksien lataus

Tämä päätepiste on valinnainen eikä vaadita vakiointegraatioihin. Käytä vain jos Wealth Reader nimenomaisesti ohjeistaa. Tärkeää: Wealthreader-puolen eräprosessien hallinnan käyttämiseen vaaditaan omistettu ympäristö. Tämä päätepiste ei ole käytettävissä osoitteessa api.wealthreader.com. "batch"-tagin alla ryhmitellyt päätepisteet mahdollistavat useiden pankkiyhteyksien asynkronisen käsittelyn, toisin kuin synkroninen /entities/-menetelmä. Ihanteellinen suurten yhteysvolyymien käsittelyyn ja aikakatkaisujen välttämiseen.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

notification_url
required
string <uri>

Webhook URL. A notification is sent to this URL for each individual credential as soon as it completes processing, not only once all connections in the batch are done.

Esimerkki: https://example.com/webhook/batch-complete

required
Array of objects (batch-connection) non-empty

List of connections to process

Responses

Callbacks

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4e5f6g7h8i9j0",
  • "notification_url": "https://example.com/webhook/batch-complete",
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "total_connections": 5,
  • "estimated_completion_time": "2025-01-20T10:45:00Z"
}

Callback payload samples

Callback
POST: Webhook fired when a credential finishes processing
Content type
application/json
{
  • "batch_id": 10863151,
  • "credential_id": "cred_demo_002",
  • "status": "completed",
  • "timestamp": "2026-05-13T08:02:47+00:00"
}

Hae yleisiä tilastoja batch-yhteyksistä

Tämä päätepiste on valinnainen. Hakee yleisiä tilastoja kaikkien batch-yhteyksien käsittelytuloksesta.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "status": "completed",
  • "statistics": {
    }
}

Hae tietyn yhteyden yksittäinen tulos batchin sisällä

Tämä päätepiste on valinnainen. Hakee tietyn yhteyden tuloksen batchista.

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

credential_id
required
string

Filter by specific credential_id

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string",
  • "credential_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

MyBankMatch

Tilinomistajuuden varmennus: tarkista, kuuluuko IBAN tietylle tilinomistajalle lisenssiisi liitetyn pankin SEPA-maksunsaajan varmennuksen (VoP) avulla. Vaiheittainen opas: MyBankMatch.

Varmentaa, että IBAN kuuluu tilinomistajalle (MyBankMatch)

Tarkistaa, kuuluuko IBAN ilmoitetulle tilinomistajalle oman pankkisi SEPA-maksunsaajan varmennuksen (VoP) avulla; pankki on liitetty WealthReader-lisenssiisi. Palauttaa pankin ratkaisun: se ei korvaa sitä paikallisella nimien samankaltaisuuslaskelmalla eikä luo, valtuuta tai toteuta mitään maksumääräystä.

Ennen ensimmäistä kutsua

  1. Hanki aktiivinen lisenssi, jossa on tuote MY_BANK_MATCH ja käytettävissä olevaa kiintiötä.
  2. Avaa Asiakkaat · MyBankMatch, valitse Yhdistä pankki ja suorita todennus WealthReader-palvelun isännöimässä ikkunassa. Tokenisoitu yhteys liitetään api_key-avaimeesi; pankkitunnistetta ei luovuteta selaimelle, eikä se ole kyselyn parametri.

Pyyntö: lomakekoodattu runko (application/x-www-form-urlencoded), jossa on api_key, iban ja name, kuten /entities/-kutsussa. JSONia ei lähetetä eikä otsaketta X-API-Key käytetä. Säilytä api_key taustajärjestelmässäsi.

Vastaus: HTTP 200 tarkoittaa, että tuotteesta on saatu tulos, ei sitä, että nimi täsmää. Tarkista success ja sen jälkeen payload.result:

payload.result Merkitys Lisäkentät Laskutettava
MATCH Pankin mukaan nimi vastaa tilinomistajaa. Ei mitään. Kyllä, 0,10 EUR.
PARTIAL_MATCH Pankki palauttaa osittaisen vastaavuuden (CLOSE_MATCH). suggested_name. Kyllä, 0,10 EUR.
NO_MATCH Pankin mukaan nimi ei vastaa. Ei mitään. Kyllä, 0,10 EUR.
NOT_CONFIGURED Lisenssiin ei ole vielä liitetty pankkia. setup_url. Ei.
REAUTH_REQUIRED Pankkiyhteys edellyttää uutta todennusta. setup_url, reason_code. Ei.
NOT_POSSIBLE Käyttökelpoista ratkaisua ei saatu. Ei vastaa tulosta NO_MATCH. reason. Ei.

Vain MATCH, PARTIAL_MATCH ja NO_MATCH kuluttavat kiintiötä. Syötevirheitä ja epäselviä tuloksia ei laskuteta.

Idempotenssiavainta tai maksutonta uudelleenyritystä ei ole. Jos vastaus katoaa (aikakatkaisu, verkko tai tulkitsematon runko), tulos ja sen kiintiönkulutus voivat jäädä sovelluksellesi tuntemattomiksi. Älä lähetä samaa kyselyä automaattisesti uudelleen: tarkista historia Asiakkaat-sivulla ja ota yhteyttä tukeen ilmoittaen statistics.SESSION.

Täydellinen opas: MyBankMatch.

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

8 heksadesimaalimerkin avain aktiivisesta lisenssistä, jossa on tuote MY_BANK_MATCH ja käytettävissä olevaa kiintiötä. Säilytä se taustajärjestelmässäsi.

iban
required
string

SEPA-maan IBAN. Välilyönnit poistetaan, kirjaimet muutetaan isoiksi ja maan mukainen pituus sekä mod-97-tarkistusnumerot validoidaan.

Esimerkki: ES9321005707250200257112

name
required
string <= 140 characters

Tilinomistajan nimi. Ei tyhjä, kelvollista UTF-8:aa, ei ohjausmerkkejä ja enintään 140 merkkiä. Alusta ja lopusta poistetaan välilyönnit, ja sisäiset peräkkäiset välilyönnit yhdistetään.

Esimerkki: Wealthreader S.L.

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&iban=ES9321005707250200257112&name=Wealthreader%20S.L.

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

Payments

Maksajan pankista käynnistettävät tililtä tilille tehtävät SEPA-maksut. Ne voidaan integroida kahdella tavalla:

  • Fast Track: yksi POST /payments/?action=fast-track palauttaa maksun URL-osoitteen, ja Wealth Reader ilmoittaa notification_url-osoitteeseesi tuloksen OK tai KO. Katso Fast Track -maksut.
  • Widget: taustajärjestelmäsi luo muuttumattoman maksuaikomuksen kutsulla POST /payments/?action=create, avaa widgetin palautetulla tunnisteella ja vahvistaa tuloksen kutsulla POST /payments/?action=status. Katso Johdanto maksuihin ja Tilat, kysely ja täsmäytys.

Kaikkia /payments/?action=...-kutsuja koskevat yhteiset säännöt

  • Menetelmä POST, otsake Content-Type: application/json ja rungossa JSON-objekti (enintään 32768 tavua).
  • Todennus vain otsakkeella X-API-Key (wr_live_, jota seuraa 72 kirjainta tai numeroa) aktiivisesta lisenssistä, jossa on tuote PAYMENTS. Sitä ei koskaan lähetetä rungossa. Jokainen todennettu kutsu lasketaan lisenssin kutsurajaan.
  • Runko on sallittujen kenttien luettelo: puuttuva pakollinen kenttä tai odottamaton kenttä palauttaa vastauksen 422 invalid_request.
  • Ainoa myönteinen taloudellinen vahvistus on payment_status: settled. Widgetin tapahtuma, SCA-paluu tai interaction_status: completed eivät koskaan tarkoita, että maksu on selvitetty.

Virhemuoto: application/json (ei problem+json), jossa on pysyvä error.code; error.message on tiedottava ja voi muuttua.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Syy
400 invalid_json Runko on tyhjä, virheellinen tai ei ole JSON-objekti.
401 invalid_api_key X-API-Key puuttuu, on väärin muotoiltu, tuntematon tai ei ole aktiivinen.
403 payments_not_allowed Lisenssissä ei ole tuotetta PAYMENTS.
404 action_not_found Tuntematon action.
405 method_not_allowed Muu menetelmä kuin POST.
413 request_too_large Runko on yli 32768 tavua.
415 json_required Muu Content-Type kuin application/json.
422 invalid_request Puuttuvia tai odottamattomia kenttiä.
429 api_limit_reached Lisenssin kutsuraja on saavutettu.
500 internal_error Odottamaton virhe.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Palvelu ei ole tilapäisesti käytettävissä tai uudet maksut on keskeytetty.

Fast Track -maksun OK- tai KO-ilmoitus Webhook

Wealth Reader lähettää tämän POST-pyynnön Fast Track -maksun notification_url-osoitteeseen, kun se tarkistaa maksun tilan ja toteaa sen olevan lopullinen. reconciliation_required ei ole lopullinen, eikä siitä ilmoiteta: vahvista se status-kutsulla.

  • outcome on ok vain, jos pankki on selvittänyt maksun (settled); tiloista rejected, cancelled, expired ja failed ilmoitetaan ko.
  • Tila tarkistetaan, kun maksaja on yhä maksusivulla (sivu kysyy tilaa lopulliseen tulokseen asti tai kunnes maksuistunto vanhenee), sekä aina, kun teet status-kutsun. Erillistä ajastettua lähetystä ei ole: jos maksaja poistuu ennen kuin pankki on saanut käsittelyn päätökseen tai palvelimesi ei vastaa 2xx, ilmoitus lähetetään seuraavassa tarkistuksessa. Jos ilmoitusta ei ole tullut muutaman minuutin kuluttua maksajan uudelleenohjauksesta, tee status-kutsu arvolla payment_intent_id; tämä kutsu käynnistää myös odottavan ilmoituksen.
  • Vastaa millä tahansa 2xx-koodilla, niin ilmoitus katsotaan toimitetuksi. Wealth Reader ei seuraa uudelleenohjauksia ja odottaa enintään 3 sekuntia.
  • Sama ilmoitus voi saapua useammin kuin kerran: käsittele customer_reference yhdessä outcome-arvon kanssa idempotenttina.
  • Pyyntöä ei ole allekirjoitettu. Ennen arvokkaan hyödykkeen luovuttamista vahvista tulos status-kutsulla käyttäen X-API-Key-avaintasi ja ilmoituksen payment_intent_id-arvoa.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok vain tilalle settled.

payment_status
required
string
Enum: "settled" "rejected" "cancelled" "expired" "failed"

Lopullinen taloudellinen tulos.

customer_reference
required
string

Idempotency-Key, jonka lähetit maksua luodessasi.

payment_intent_id
required
string <uuid>

fast-track-kutsun palauttama tunniste. Käytä sitä tuloksen vahvistamiseen status-kutsulla.

Responses

Request samples

Content type
application/json
Example
{
  • "outcome": "ok",
  • "payment_status": "settled",
  • "customer_reference": "11111111-1111-4111-8111-111111111111",
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f"
}

Luo maksun ja hakee sen URL-osoitteen (Fast Track)

Yksi kutsu, joka palauttaa maksun URL-osoitteen. Maksaja avaa sen ja valtuuttaa maksun pankissaan; kun maksu saavuttaa lopullisen tilan, Wealth Reader ilmoittaa notification_url-osoitteeseesi tuloksen OK tai KO (katso webhook notification_url). Taustalla luodaan sama muuttumaton maksuaikomus kuin create-kutsulla: summa, saaja ja selite lukitaan ennen kuin ne päätyvät selaimeen.

Otsake Idempotency-Key on myös kauppiasviitteesi (customer_reference ilmoituksessa): sitä ei lähetetä rungossa. Jos toistat saman avaimen samalla rungolla, saat saman URL-osoitteen; jos käytät sitä uudelleen eri tiedoilla (myös eri logo-arvolla), vastaus on 409 idempotency_conflict.

Pikasiirrolla ei ole tässä API:ssa omaa ylärajaa: pankki hylkää siirron, jota se ei voi hyväksyä, myös summan perusteella, ja hylkäys välitetään tuloksena KO.

header Parameters
X-API-Key
required
string

API-avain lisenssistä, jossa on tuote PAYMENTS. Säilytä se taustajärjestelmässäsi.

Idempotency-Key
required
string [ 16 .. 128 ] characters

16–128 merkkiä; alkaa kirjaimella tai numerolla ja sisältää vain kirjaimia, numeroita sekä merkkejä . _ : -. UUID v4 kelpaa. Toimii myös kauppiasviitteenä, joka palautetaan ilmoituksessa.

Request Body schema: application/json
required
amount
required
string

Summa päärahayksikköinä JSON-merkkijonona. "15.50" on 15,50 EUR; myös kokonaisluku ilman desimaaleja ("15") hyväksytään. Enintään kaksi desimaalia, joten "15.5" ja "15.50" ovat sama summa. Vähintään 0.01. Enimmäismäärää rajoittaa raja, jonka kukin asiakas on määrittänyt pankissaan.

Esimerkki: 15.50

currency
required
string
Value: "EUR"

ISO 4217 -valuutta. Tässä versiossa vain EUR.

Esimerkki: EUR

required
object (payments-beneficiary)

Tilisiirron vastaanottaja. Ei voi muuttaa maksun luomisen jälkeen.

reference
required
string [ 1 .. 140 ] characters

Tiliotteen selite, enintään 140 merkkiä.

Esimerkki: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (SEPA-tilisiirto) tai instant (SEPA-pikasiirto).

Esimerkki: normal

notification_url
required
string <= 2000 characters

Julkinen https-URL, joka vastaanottaa OK- tai KO-ilmoituksen. Ei tunnistetietoja, portti 443, jos portti ilmoitetaan, eikä yksityisiä, paikallisia tai metatieto-osoitteita.

Esimerkki: https://tienda.example.com/pagos/aviso

logo
string <= 2048 characters

Valinnainen. Julkinen https-URL kauppiaasi SVG-logoon (polun on päätyttävä .svg; kyselyparametrit sallitaan), ilman tunnistetietoja, fragmenttia tai yksityisiä osoitteita, enintään 2048 ASCII-merkkiä. Maksusivu näyttää logon yhteenvedon yläpuolella; Wealth Reader ei lataa sitä, vaan maksajan selain lataa sen. Mikä tahansa muu arvo palauttaa vastauksen 422 invalid_logo.

Esimerkki: https://tienda.example.com/marca/logo.svg

Responses

Request samples

Content type
application/json
{}

Response samples

Luo maksuaikomuksen (widget)

Luo muuttumattoman maksuaikomuksen ja palauttaa lyhytikäisen tunnisteen widgetin avaamiseksi maksajan selaimessa. Summa, saaja ja selite lukitaan taustajärjestelmässä, eikä niitä voi muuttaa selaimesta. Kun widget on suljettu, vahvista tulos taustajärjestelmästäsi status-kutsulla.

Rungosta on kaksi muunnelmaa:

  • Vakio: määrität itse kentät amount_minor, currency, beneficiary, reference, customer_reference ja allowed_origin.
  • Hallinnoitu profiili (esimerkiksi cruz_roja_demo): Wealth Reader määrittää saajan, selitteen ja rajat; lähetät kentät profile, institution_code, amount_minor, customer_reference ja allowed_origin. Hae pankit profile-institutions-kutsulla.

Jos toistat saman Idempotency-Key-avaimen samalla rungolla, saat saman maksuaikomuksen (200, idempotent_replay: true); jos käytät sitä uudelleen eri tiedoilla, vastaus on 409 idempotency_conflict. Avain on yrityskohtainen.

Opas: Maksuaikomukset ja idempotenssi ja Widget-integraatio.

header Parameters
X-API-Key
required
string

API-avain lisenssistä, jossa on tuote PAYMENTS. Säilytä se taustajärjestelmässäsi.

Idempotency-Key
required
string [ 16 .. 128 ] characters

16–128 näkyvää ASCII-merkkiä. Luo yksi avain kutakin maksua kohden (UUID v4 kelpaa) ja käytä sitä uudelleen, jos yrität kutsua uudelleen.

Request Body schema: application/json
required
One of
amount_minor
required
integer >= 1

Summa pienempinä rahayksikköinä (sentteinä) JSON-kokonaislukuna. 1500 on 15,00 EUR. Enimmäismäärää rajoittaa raja, jonka kukin asiakas on määrittänyt pankissaan.

Esimerkki: 1500

currency
required
string
Value: "EUR"
required
object (payments-beneficiary)

Tilisiirron vastaanottaja. Ei voi muuttaa maksun luomisen jälkeen.

reference
required
string [ 1 .. 140 ] characters

Tiliotteen selite, enintään 140 merkkiä.

Esimerkki: Pedido 78901

customer_reference
required
string <= 128 characters

Maksun sisäinen viitteesi. 1–128 merkkiä; alkaa kirjaimella tai numerolla ja sisältää vain kirjaimia, numeroita sekä merkkejä . _ : -.

Esimerkki: order-78901

allowed_origin
required
string

Widgetin avaavan sivun alkuperä (https://host[:puerto], ilman polkua, kyselyä tai fragmenttia). Widget toimii vain tästä alkuperästä.

Esimerkki: https://tienda.example.com

locale
string
Value: "es"

Valinnainen. Widgetin kieli; tässä versiossa vain es.

expected_mode
string
Enum: "mock" "live"

Valinnainen. Jos se ei vastaa ympäristöä, kutsu palauttaa vastauksen 409 payment_mode_mismatch maksun luomisen sijaan.

allowed_institution_codes
Array of strings <= 2500 items

Valinnainen. Ei-tyhjä luettelo yksilöllisiä pankkikoodeja (katso /payments/entities/), joista maksaja voi valita.

Esimerkki: 

[
  "bbva-es",
  "santander-es"
]
logo
string or null

Valinnainen. Julkinen https-URL SVG-logoosi (polku päättyy .svg), ilman tunnistetietoja, fragmenttia tai yksityisiä osoitteita, enintään 2048 merkkiä.

Responses

Request samples

Content type
application/json
Example
{
  • "amount_minor": 1500,
  • "currency": "EUR",
  • "beneficiary": {
    },
  • "reference": "Pedido 78901",
  • "customer_reference": "order-78901",
  • "allowed_origin": "https://tienda.example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payment": {
    }
}

Kysyy maksun tilan

Palvelimelta palvelimelle tehtävä maksun tilan kysely, kunnes pankilta saadaan lopputulos. Takaisinkutsu, SCA-paluu tai widgetin sulkeminen ei ole taloudellinen vahvistus: vain payment_status: settled on.

Wealth Reader rajoittaa ulkoisia kyselyjä maksuaikomusta kohden; käytä backoff-viivettä myös taustajärjestelmässäsi äläkä luo uutta maksuaikomusta, kun tulos on epäselvä.

Epäselvä tulos: verkkokatkos, aikakatkaisu tai tunnistamaton vastaus käynnistyksen lähettämisen jälkeen muuttaa maksuaikomuksen tilaan reconciliation_required arvolla payment_status: unknown, ja vastaus sisältää kentän reconciliation. Käynnistystä ei koskaan toisteta automaattisesti. Säilytä tunniste ja idempotenssiavain, älä luo uutta maksuaikomusta tai valtuuta uudelleen, ja kun automatic_recovery on false, lopeta kysely ja ohjaa asia tukeen viitteellä reconciliation.reference.

Fast Track -maksuissa tämä kysely lähettää myös odottavan OK/KO-ilmoituksen osoitteeseen notification_url, kun maksu on saavuttanut lopullisen tilan.

Opas: Tilat, kysely ja täsmäytys.

header Parameters
X-API-Key
required
string

Maksun luoneen lisenssin API-avain.

Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

create-kutsun palauttama payment.id (Fast Track -maksuissa fast-track-kutsun palauttama payment_intent_id).

Esimerkki: 3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f

refresh
boolean
Default: true

Valinnainen. true kysyy pankilta viimeisimmän tilan, kun se on tarpeen; false palauttaa tallennetun tilan.

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f",
  • "refresh": true
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payment": {
    }
}

Luettelee hallinnoidun profiilin pankit ja ehdot

Palauttaa yrityksellesi käyttöön otetun hallinnoidun profiilin ehdot (saaja, selite, summarajat) sekä pankit, joista maksaja voi valita. Käytä valittua code-arvoa institution_code-kenttänä create-kutsussa.

header Parameters
X-API-Key
required
string

API-avain lisenssistä, jossa on tuote PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Hallinnoidun profiilin koodi.

Esimerkki: cruz_roja_demo

Responses

Request samples

Content type
application/json
{
  • "profile": "cruz_roja_demo"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "profile": {
    }
}

Luettelee maksuihin käytettävissä olevat pankit

Luettelo pankeista, jotka voivat käynnistää maksuja, sekä niiden logot ja tukemat maksutavat. X-API-Key on valinnainen; jos lähetät sen, se validoidaan ja lasketaan kutsuksi. Tukee myös POST-menetelmää samoilla suodattimilla JSON-rungossa sekä kutsua POST /payments/?action=entities, jossa X-API-Key on pakollinen.

Tuntemattomat suodattimet ohitetaan, eivätkä ne koskaan aiheuta validointivirhettä.

query Parameters
country
string
Example: country=ES

ISO 3166-1 alpha-2 -maakoodi. ALL tai tyhjä arvo tarkoittaa, ettei suodatinta käytetä.

Esimerkki: ES

search
string

Nimessä tai koodissa esiintyvä teksti kirjainkoosta riippumatta (alias q).

code
string
Example: code=santander-es

Pankin tarkka koodi kirjainkoosta riippumatta.

Esimerkki: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Vain pankit, jotka tukevat tätä maksutapaa.

limit
integer [ 1 .. 2000 ]

Sivun koko (1–2000).

offset
integer >= 0

Ohitettavien tulosten määrä.

header Parameters
X-API-Key
string

Valinnainen. Jos se lähetetään, se validoidaan ja lasketaan kutsuksi.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "entities": [
    ]
}

Cards (real time)

Real-time card expense synchronization from the Open Sync mobile app: per-customer employee pre-registration, signed webhooks (card_transaction.created / card_enrollment.confirmed), and REST query / backfill.

Register or rotate the real-time cards webhook

Creates or updates the webhook URL of the customer for the card_transaction.created and card_enrollment.confirmed events (see the cards-webhook-delivery schema for the delivery format and signature). On first setup, or when rotate_secret is true, a new webhook_secret (64 hex characters) is generated and returned once; in any other case webhook_secret comes back as null in the response and cannot be retrieved again. webhook_url must always be https:// and must resolve to a publicly routable host: localhost, private, loopback, link-local (including the cloud metadata address), CGNAT, multicast and reserved addresses are rejected, in any notation (hexadecimal, decimal, octal, short dotted or IPv4-mapped IPv6), and so is a hostname that does not resolve at all. The same check runs again right before every delivery, not only at registration: if the host is repointed at an internal address afterwards (DNS rebinding) the delivery is closed as failed with response_excerpt "blocked_host". Sending null in webhook_url disables webhooks for that customer; omitting the field leaves the stored URL untouched, which is how the secret is rotated without changing the URL.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

webhook_url
string or null

https:// URL that will receive the events, on a publicly routable host that resolves in DNS. null disables webhooks; omitting the field leaves the stored URL unchanged.

Esimerkki: https://cliente.example.com/webhooks/wealthreader-cards

rotate_secret
boolean
Default: false

When true, generates and returns a new webhook_secret.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Pre-register the email of an employee

Creates an enrollment request in pending status with a short expiry (ttl_minutes, 20 by default, between 1 and 60) for the employee to confirm by opening the mobile app and entering that email (POST /user-sync-validation/, no contract change for the app). It is idempotent: repeating the call for the same (api_key, email) while it is still pending and not expired returns the same request. If the email is already linked to the calling customer, it returns status "active" directly. If it is already linked to a different customer, it returns 409. Rate limit: at most 60 calls to this endpoint per api_key every 60 seconds, counting every attempt and not only the ones that create a row, checked before anything else so the answers that create nothing (200 already active, 409 linked to another customer, 400) cannot be walked as an enumeration oracle. Exceeding it returns 429 with code rate_limited.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

email
required
string <email>

Email of the employee to pre-register.

Esimerkki: empleado@cliente.com

ttl_minutes
integer [ 1 .. 60 ]
Default: 20

Minutes the request stays valid before expiring.

Responses

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4",
  • "email": "empleado@cliente.com",
  • "ttl_minutes": 20
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Check the status of an enrollment

Read-only status of an enrollment request. It has no side effects on card users, unlike POST /user-sync-validation/, which does confirm. The only write allowed is lazily marking a pending enrollment whose expiry date has already passed as expired.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

Esimerkki: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

Esimerkki: 0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Query / backfill real-time card transactions

Returns the real-time card transactions received for the employees linked to this api_key, ordered by ascending id. Meant both for periodic backfill (poll with date_from/date_to and paginate with since_id) and for one-off queries. This is the same transaction object carried by the card_transaction.created webhook.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

Esimerkki: a1b2c3d4

date_from
string <date>
Example: date_from=2026-07-01

YYYY-MM-DD, on the operation date. Default: today minus 3 days.

Esimerkki: 2026-07-01

date_to
string <date>
Example: date_to=2026-07-11

YYYY-MM-DD, on the operation date. Default: today.

Esimerkki: 2026-07-11

email
string <email>
Example: email=empleado@cliente.com

Filters by the email of the employee.

Esimerkki: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Esimerkki: 216

limit
integer <= 1000
Default: 500
Example: limit=500

Maximum number of transactions to return (500 by default, 1000 max).

Esimerkki: 500

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}