API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Les API réglementaires basées sur PSD2 donnent accès à certaines informations financières telles que les soldes des comptes bancaires et les transactions. Cependant, il existe d'autres sources d'informations sur la richesse qui ne sont pas accessibles via ces API. L'API Wealth Reader étend les informations offertes par les API réglementaires en fournissant un accès en temps réel à des sources de richesse supplémentaires dans toute entité mondiale. Il existe deux autres documents connexes qui vous aideront à intégrer l'API Wealth Reader. L'un est le guide d'intégration du widget Javascript : https://docs-en.wealthreader.com/ et l'autre est une collection Postman basée sur cette documentation. Très important : Cette définition d'API est adaptée pour les clients intégrant via Widget, donc certains paramètres qui ne sont pas nécessaires pour ce type d'intégration ont été omis, tels que les paramètres d'authentification bancaire, car un token sera utilisé.

Core

API principale requise pour les intégrations standard

Récupère les actifs financiers et les détails de leur composition

Récupère les actifs financiers et les détails de leur composition incluant les portefeuilles d'investissement composés d'actions ou de fonds, cartes de crédit, assurances et prêts. Inclut les informations de propriété pour chaque actif ainsi que des identifiants uniques qui facilitent le traitement des données. Il est possible d'obtenir des données Mock. Vérifiez auprès de l'équipe technique comment procéder.

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

Identifie le client dans le service

code
string

Nom de l'entité. La liste complète est disponible avec GET

Exemple: caixabank

token
string

Identifie les identifiants gardés. Le flux par lequel le token a été obtenu est décrit dans le document 'Guide d'intégration du Widget'. Les utilisateurs Mock suivants sont disponibles: MOCKDATA, réponse OK; MOCKOTP, réponse avec défi OTP; MOCKLOGINKO, réponse avec erreur de login

Exemple: MOCKDATA

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

Liste des types de produits dont les informations doivent être récupérées. Accepte plusieurs valeurs séparées par des virgules.

Exemple: accounts,portfolios

only_balances
boolean
Default: false

Indique s'il faut obtenir uniquement les soldes des produits au lieu de toutes les informations disponibles. Valeur par défaut: false.

Exemple: false

fetch_transaction_details
boolean
Default: false

Indique si des détails étendus des transactions doivent être obtenus lorsque le connecteur de l'entité le prend en charge. IMPORTANT : L'activer implique d'effectuer une ou plusieurs navigations supplémentaires par transaction pour enrichir les informations renvoyées. Cela augmentera inévitablement et de manière significative le temps d'exécution. Le nombre de navigations supplémentaires augmente avec le volume de transactions. Il est recommandé de l'activer uniquement lorsque vous êtes certain qu'un niveau de détail supérieur à celui renvoyé par défaut est requis. Les détails obtenus sont insérés dans la clé additional_info au niveau de chaque transaction. L'utilisation de ce paramètre nécessite un environnement dédié.

Exemple: false

date_from
string <date>

Date à partir de laquelle les transactions sont demandées, au format AAAA-MM-JJ. Doit être une date antérieure à aujourd'hui.

Exemple: 2024-01-01

date_to
string <date>

Ceci s'applique uniquement pour restreindre par dates futures pour les produits loan et confirming, au format AAAA-MM-JJ. La date doit être postérieure à aujourd'hui

Exemple: 2025-12-31

required_products_schema
string

Schéma des produits requis. Indique les comptes ou cartes dont les données sont souhaitées, avec des configurations supplémentaires.

Exemple: 

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

Accepte les uuids de transactions séparés par des virgules. Paramètre pris en compte uniquement si product_types est ALL ou inclut accounts. Ajoute le document PDF associé à chacune des transactions bancaires demandées.

Exemple: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Sélectionne le canal d'envoi du second facteur lorsque l'API a renvoyé le code 2017 ou 20171 (plusieurs méthodes OTP). Rappelez avec le même identifiant de session que cette réponse et définissez otp_method sur la chaîne exacte du champ otp_method d'un objet dans statistics.otpMethods — pas l'index du tableau. À omettre lors de la première requête par identifiants; à envoyer après le choix de l'utilisateur. L'exemple ci-dessous est indicatif; copiez toujours la chaîne renvoyée dans statistics.otpMethods pour votre entité.

Exemple: 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
[
  • {
    }
]

Liste des types de transaction

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Interroger les tokens associés à une api_key

Utilisez cette méthode pour interroger les tokens liés à une api_key spécifique. Les résultats sont paginés : limit fixe le nombre de tokens par page (500 au maximum) et page indique la page à retourner. api_key, method et limit sont obligatoires ; si l'un d'eux est absent ou invalide, l'API répond avec HTTP 400 et le code d'erreur 2.

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

api_key pour identifier le client dans le service

method
required
string
Value: "get"

Opération à effectuer. La seule valeur prise en charge est get.

Exemple: get

limit
required
integer [ 1 .. 500 ]

Nombre de tokens par page. Minimum 1, maximum 500.

Exemple: 100

page
integer >= 1
Default: 1

Spécifiez le numéro de page que vous souhaitez récupérer. Chaque page contient jusqu'à limit tokens. Si non fourni, la valeur par défaut est 1.

Exemple: 1

code
string

Code d'entité utilisé pour filtrer les tokens. S'il est omis, les tokens de toutes les entités sont retournés.

Exemple: bbva

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

Champ utilisé pour trier les résultats : created_at (date de création) ou accesed_at (date du dernier accès). Par défaut created_at.

Exemple: created_at

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

Sens du tri : ASC (croissant) ou DESC (décroissant). Par défaut DESC.

Exemple: 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": {
    }
}

Révoquer un token

Cette méthode permet de révoquer un token existant pour désautoriser les futures demandes d'accès à l'API.

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

Identifie le client dans le service

token
string

Jeton à révoquer.

Responses

Response samples

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

Réattribuer un token à une api_key différente

Cette méthode permet de réattribuer un token d'une api_key à une autre. Les deux api_keys doivent être actives et appartenir à la même entreprise, et le token doit appartenir à api_key_source.

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

api_key à partir de laquelle réattribuer le jeton.

api_key_target
string

api_key vers lequel réattribuer le jeton.

token
string

Jeton à réattribuer.

Exemple: 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."
}

Ajouter un nouveau domaine

Ajoute l'association entre le domaine qui hébergera le widget et le webhook de destination. Pour modifier ou tester vos domaines, utilisez https://www.wealthreader.com/clients/

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

Method to execute.

Exemple: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Exemple: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Contrôle si le widget lance un flux de tokenisation :

  • 1 - L'utilisateur s'authentifie auprès de l'institution financière (login, consentement, 2FA si nécessaire) et un token réutilisable est renvoyé pour les requêtes futures
  • 0 - Aucune tokenisation n'est effectuée. La valeur du token précédemment obtenu doit être incluse dans la requête

Exemple: 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"
}

Liste des codes d'erreur

Liste des codes d'erreur. Faites particulièrement attention au fait que tous les codes d'erreur ne doivent pas recevoir le même traitement de votre application. Pour une erreur de mot de passe incorrect, vous ne devez pas réessayer l'appel avec les mêmes paramètres, mais pour une erreur indiquant que l'entité est en maintenance, vous pouvez réessayer. Demandez une session technique avec notre équipe pour résoudre toute question sur la gestion des erreurs.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Liste des codes d'avertissement

Liste des codes d'avertissement.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Points de terminaison optionnels non requis pour les intégrations standard. Utiliser uniquement si Wealth Reader l'indique explicitement.

Récupère la liste des entités prises en charge

Récupère la liste des entités prises en charge et les informations nécessaires pour dessiner le formulaire de connexion de l'entité.

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
[
  • {
    }
]

Enregistrer un nouvel utilisateur

Ce endpoint est optionnel et non requis pour les intégrations standard. À utiliser uniquement sur instruction explicite de Wealth Reader. Ce endpoint permet d'enregistrer un utilisateur soit sur la plateforme de transfert de portefeuille, Easytransfer, soit sur l'outil de reporting, Acumulas, basé sur un identifiant unique.

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.

Exemple: 12345678A

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

Service associated with the user. Determines the data flow.

Exemple: easy-transfer

email
required
string <email>

User email, used according to service type.

Exemple: sai_banker@singularbank.com

Responses

Response samples

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

Vérifier le statut d'inscription de l'utilisateur

Ce endpoint est optionnel et non requis pour les intégrations standard. À utiliser uniquement sur instruction explicite de Wealth Reader. Vérifie si un utilisateur est enregistré dans le système Easytransfer ou Acumulas et renvoie le lien d'accès unique pour l'utilisateur.

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

Authentication key

user_id
required
string

User identification document.

Exemple: 12345678A

Responses

Response samples

Content type
application/json
{}

Révoquer un utilisateur précédemment enregistré

Ce endpoint est optionnel et non requis pour les intégrations standard. À utiliser uniquement sur instruction explicite de Wealth Reader. Ce endpoint permet de désinscrire un utilisateur du service de la plateforme Easytransfer ou Acumulas.

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.

Exemple: 12345678A

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

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

Exemple: easy-transfer

Responses

Response samples

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

Chargement de connexions par lot

Ce endpoint est optionnel et non requis pour les intégrations standard. À utiliser uniquement sur instruction explicite de Wealth Reader. Important : Pour utiliser la gestion des processus batch du côté de Wealthreader, un environnement dédié est nécessaire. Ce endpoint n'est pas disponible sur api.wealthreader.com. Les endpoints regroupés sous le tag "batch" permettent de traiter plusieurs connexions bancaires de manière asynchrone, contrairement à la méthode /entities/ qui est synchrone. Idéal pour traiter de grands volumes de connexions et éviter les timeouts.

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.

Exemple: 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"
}

Obtenir les statistiques générales des connexions batch

Ce endpoint est optionnel. Récupère les statistiques générales sur le résultat du traitement de toutes les connexions d'un batch.

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": {
    }
}

Obtenir le résultat individuel d'une connexion spécifique dans un batch

Ce endpoint est optionnel. Récupère le résultat d'une connexion spécifique du batch.

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

Vérification du titulaire : vérifiez si un IBAN appartient à un titulaire grâce à la Vérification du bénéficiaire (VoP) SEPA de la banque associée à votre licence. Guide pas à pas : MyBankMatch.

Vérifie qu'un IBAN appartient à un titulaire (MyBankMatch)

Vérifie si un IBAN appartient au titulaire indiqué grâce à la Vérification du bénéficiaire (VoP) SEPA de votre propre banque, associée à votre licence WealthReader. Renvoie le verdict de la banque : il n'est pas remplacé par un calcul local de similarité des noms, et aucun ordre de paiement n'est créé, autorisé ni exécuté.

Avant le premier appel

  1. Disposez d'une licence active avec le produit MY_BANK_MATCH et un quota disponible.
  2. Ouvrez Clients · MyBankMatch, cliquez sur Connecter la banque et terminez l'authentification dans la fenêtre hébergée par WealthReader. La connexion tokenisée est associée à votre api_key ; le jeton bancaire n'est pas transmis au navigateur et n'est pas un paramètre de la requête.

Requête : corps encodé comme un formulaire (application/x-www-form-urlencoded) avec api_key, iban et name, comme pour /entities/. Aucun JSON n'est envoyé et l'en-tête X-API-Key n'est pas utilisé. Conservez la api_key dans votre backend.

Réponse : HTTP 200 indique qu'un résultat du produit a été obtenu, et non que le nom correspond. Vérifiez success, puis payload.result :

payload.result Signification Champs supplémentaires Facturable
MATCH La banque considère que le nom correspond au titulaire. Aucun. Oui, 0,10 EUR.
PARTIAL_MATCH La banque renvoie une correspondance partielle (CLOSE_MATCH). suggested_name. Oui, 0,10 EUR.
NO_MATCH La banque indique que le nom ne correspond pas. Aucun. Oui, 0,10 EUR.
NOT_CONFIGURED La licence n'a pas encore de banque associée. setup_url. Non.
REAUTH_REQUIRED La connexion avec la banque nécessite une nouvelle authentification. setup_url, reason_code. Non.
NOT_POSSIBLE Il n'a pas été possible d'obtenir un verdict exploitable. Cela n'équivaut pas à NO_MATCH. reason. Non.

Seuls MATCH, PARTIAL_MATCH et NO_MATCH consomment du quota. Les erreurs de saisie et les résultats non concluants ne sont pas facturés.

Il n'existe ni clé d'idempotence ni nouvelle tentative gratuite. Si vous perdez la réponse (timeout, réseau ou corps non interprétable), le résultat et la consommation de quota correspondante peuvent être inconnus de votre application. Ne renvoyez pas automatiquement la même requête : consultez l'historique dans Clients et contactez le support en indiquant statistics.SESSION.

Guide complet : MyBankMatch.

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

Clé de 8 caractères hexadécimaux d'une licence active disposant du produit MY_BANK_MATCH et d'un quota disponible. Conservez-la dans votre backend.

iban
required
string

IBAN d'un pays SEPA. Les espaces sont supprimés, la valeur est mise en majuscules, puis la longueur propre à son pays et les chiffres de contrôle mod-97 sont validés.

Exemple: ES9321005707250200257112

name
required
string <= 140 characters

Nom du titulaire. Non vide, UTF-8 valide, sans caractères de contrôle et jusqu'à 140 caractères. Il est rogné et les espaces internes sont fusionnés.

Exemple: 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

Paiements SEPA de compte à compte initiés depuis la banque du payeur. Il existe deux façons de les intégrer :

  • Fast Track : un seul POST /payments/?action=fast-track renvoie l'URL de paiement et Wealth Reader notifie votre notification_url avec OK ou KO. Consultez Paiements Fast Track.
  • Widget : votre backend crée une intention de paiement immuable avec POST /payments/?action=create, ouvre le widget avec le jeton renvoyé et confirme le résultat avec POST /payments/?action=status. Consultez Introduction aux paiements et États, interrogation et rapprochement.

Règles communes à tous les appels /payments/?action=...

  • Méthode POST avec l'en-tête Content-Type: application/json et un objet JSON comme corps (32768 octets maximum).
  • Authentification uniquement par l'en-tête X-API-Key (wr_live_ suivi de 72 lettres ou chiffres) d'une licence active disposant du produit PAYMENTS. Elle n'est jamais envoyée dans le corps. Chaque appel authentifié est décompté de la limite d'appels de la licence.
  • Le corps est une liste blanche : un champ obligatoire manquant ou un champ non prévu renvoie 422 invalid_request.
  • La seule confirmation financière positive est payment_status: settled. Un événement du widget, un retour SCA ou interaction_status: completed ne signifient jamais que le paiement est réglé.

Format d'erreur : application/json (pas problem+json) avec un error.code stable ; error.message est informatif et peut changer.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motif
400 invalid_json Corps vide, non valide ou qui n'est pas un objet JSON.
401 invalid_api_key X-API-Key absente, mal formée, inconnue ou inactive.
403 payments_not_allowed La licence ne dispose pas du produit PAYMENTS.
404 action_not_found action inconnue.
405 method_not_allowed Méthode autre que POST.
413 request_too_large Corps de plus de 32768 octets.
415 json_required Content-Type autre que application/json.
422 invalid_request Champs manquants ou non prévus.
429 api_limit_reached La limite d'appels de la licence a été atteinte.
500 internal_error Erreur inattendue.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Service temporairement indisponible ou nouveaux paiements suspendus.

Notification OK ou KO d'un paiement Fast Track Webhook

Wealth Reader envoie ce POST à la notification_url d'un paiement Fast Track lorsqu'il vérifie l'état du paiement et le trouve dans un état final. reconciliation_required n'est pas final et n'est pas notifié : confirmez-le avec status.

  • outcome vaut ok uniquement si la banque a réglé le paiement (settled) ; rejected, cancelled, expired et failed sont notifiés comme ko.
  • L'état est vérifié tant que le payeur reste sur la page de paiement (qui l'interroge jusqu'au résultat final ou jusqu'à l'expiration de la session de paiement) et chaque fois que vous appelez status. Il n'existe pas d'envoi programmé distinct : si le payeur quitte la page avant que la banque ne conclue, ou si votre serveur ne répond pas 2xx, la notification est envoyée lors de la vérification suivante. Si elle n'est pas arrivée quelques minutes après la redirection du payeur, appelez status avec le payment_intent_id ; cet appel déclenche également la notification en attente.
  • Répondez avec n'importe quel 2xx pour la considérer comme livrée. Wealth Reader ne suit pas les redirections et attend 3 secondes au maximum.
  • La même notification peut arriver plusieurs fois : traitez customer_reference plus outcome comme idempotents.
  • La requête n'est pas signée. Avant de livrer un bien de valeur, confirmez le résultat avec status en utilisant votre X-API-Key et le payment_intent_id de la notification.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok uniquement pour settled.

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

Résultat financier final.

customer_reference
required
string

La Idempotency-Key que vous avez envoyée lors de la création du paiement.

payment_intent_id
required
string <uuid>

Identifiant renvoyé par fast-track. Utilisez-le pour confirmer le résultat avec status.

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"
}

Crée un paiement et obtient son URL (Fast Track)

Un seul appel qui renvoie l'URL de paiement. Le payeur l'ouvre et autorise le paiement auprès de sa banque ; lorsque le paiement atteint un état final, Wealth Reader notifie votre notification_url avec OK ou KO (voir le webhook notification_url). En arrière-plan, la même intention immuable qu'avec create est créée : le montant, le bénéficiaire et le libellé sont fixés avant d'atteindre le navigateur.

L'en-tête Idempotency-Key est également votre référence commerçant (customer_reference dans la notification) : il n'est pas envoyé dans le corps. Si vous répétez la même clé avec le même corps, vous recevez la même URL ; si vous la réutilisez avec d'autres données (y compris un autre logo), la réponse est 409 idempotency_conflict.

Un virement instantané n'a pas de plafond propre dans cette API : la banque refuse celui qu'elle ne peut pas accepter, y compris en raison du montant, et ce refus est notifié comme KO.

header Parameters
X-API-Key
required
string

Clé d'API d'une licence disposant du produit PAYMENTS. Conservez-la dans votre backend.

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

De 16 à 128 caractères ; elle doit commencer par une lettre ou un chiffre et contenir uniquement des lettres, des chiffres et . _ : -. Un UUID v4 est valide. C'est également la référence commerçant renvoyée dans la notification.

Request Body schema: application/json
required
amount
required
string

Montant en unités principales, sous forme de chaîne JSON. "15.50" correspond à 15,50 EUR ; un entier sans décimales ("15") est également accepté. Deux décimales au maximum, donc "15.5" et "15.50" représentent le même montant. Minimum 0.01. Le maximum est limité par le plafond que chaque client a configuré auprès de sa banque.

Exemple: 15.50

currency
required
string
Value: "EUR"

Devise ISO 4217. Dans cette version, uniquement EUR.

Exemple: EUR

required
object (payments-beneficiary)

Destinataire du virement. Il ne peut pas être modifié une fois le paiement créé.

reference
required
string [ 1 .. 140 ] characters

Libellé du relevé, jusqu'à 140 caractères.

Exemple: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (virement SEPA) ou instant (virement SEPA instantané).

Exemple: normal

notification_url
required
string <= 2000 characters

URL https publique qui reçoit la notification OK ou KO. Sans identifiants, port 443 s'il est indiqué, et sans adresses privées, locales ou de métadonnées.

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

logo
string <= 2048 characters

Facultatif. URL https publique du logo de votre commerce au format SVG (le chemin doit se terminer par .svg ; les paramètres de requête sont acceptés), sans identifiants, fragment ni adresses privées, jusqu'à 2048 caractères ASCII. La page de paiement l'affiche au-dessus du récapitulatif ; Wealth Reader ne le télécharge pas, c'est le navigateur du payeur qui le charge. Toute autre valeur renvoie 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Crée une intention de paiement (widget)

Crée une intention de paiement immuable et renvoie un jeton de courte durée pour ouvrir le widget dans le navigateur du payeur. Le montant, le bénéficiaire et le libellé sont fixés dans le backend et ne peuvent pas être modifiés depuis le navigateur. Après la fermeture du widget, confirmez le résultat depuis votre backend avec status.

Il existe deux variantes de corps :

  • Standard : vous fixez amount_minor, currency, beneficiary, reference, customer_reference et allowed_origin.
  • Profil géré (par exemple cruz_roja_demo) : Wealth Reader fixe le bénéficiaire, le libellé et les limites ; vous envoyez profile, institution_code, amount_minor, customer_reference et allowed_origin. Obtenez les banques avec profile-institutions.

Si vous répétez la même Idempotency-Key avec le même corps, vous recevez la même intention (200, idempotent_replay: true) ; si vous la réutilisez avec d'autres données, la réponse est 409 idempotency_conflict. La clé est propre à votre entreprise.

Guide : Intentions et idempotence et Intégration avec le widget.

header Parameters
X-API-Key
required
string

Clé d'API d'une licence disposant du produit PAYMENTS. Conservez-la dans votre backend.

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

De 16 à 128 caractères ASCII visibles. Générez-en une par paiement (un UUID v4 est valide) et réutilisez-la si vous relancez l'appel.

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

Montant en unités secondaires (centimes) sous forme d'entier JSON. 1500 correspond à 15,00 EUR. Le maximum est limité par le plafond que chaque client a configuré auprès de sa banque.

Exemple: 1500

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

Destinataire du virement. Il ne peut pas être modifié une fois le paiement créé.

reference
required
string [ 1 .. 140 ] characters

Libellé du relevé, jusqu'à 140 caractères.

Exemple: Pedido 78901

customer_reference
required
string <= 128 characters

Votre référence interne du paiement. De 1 à 128 caractères ; commence par une lettre ou un chiffre et contient uniquement des lettres, des chiffres et . _ : -.

Exemple: order-78901

allowed_origin
required
string

Origine (https://host[:puerto], sans chemin, requête ni fragment) de la page qui ouvre le widget. Le widget ne fonctionne que depuis cette origine.

Exemple: https://tienda.example.com

locale
string
Value: "es"

Facultatif. Langue du widget ; dans cette version, uniquement es.

expected_mode
string
Enum: "mock" "live"

Facultatif. S'il ne correspond pas à l'environnement, l'appel renvoie 409 payment_mode_mismatch au lieu de créer le paiement.

allowed_institution_codes
Array of strings <= 2500 items

Facultatif. Liste non vide de codes de banque uniques (voir /payments/entities/) parmi lesquels le payeur peut choisir.

Exemple: 

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

Facultatif. URL https publique de votre logo au format SVG (chemin se terminant par .svg), sans identifiants, fragment ni adresses privées, jusqu'à 2048 caractères.

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": {
    }
}

Consulte l'état d'un paiement

Consultation de serveur à serveur de l'état d'un paiement, jusqu'à l'obtention d'une conclusion bancaire. Un callback, un retour SCA ou la fermeture du widget ne constituent pas une confirmation financière : seul payment_status: settled en est une.

Wealth Reader limite les consultations externes par intention ; appliquez également un backoff dans votre backend et ne créez pas d'autre intention tant que le résultat est ambigu.

Résultat ambigu : une panne réseau, un timeout ou une réponse non reconnue après l'émission de l'initiation fait passer l'intention à reconciliation_required avec payment_status: unknown, et la réponse inclut reconciliation. L'initiation n'est jamais répétée automatiquement. Conservez l'identifiant et la clé d'idempotence, ne créez pas d'autre intention et n'autorisez pas à nouveau ; lorsque automatic_recovery vaut false, cessez d'interroger et escaladez au support avec reconciliation.reference.

Pour les paiements Fast Track, cette consultation envoie également à notification_url la notification OK/KO en attente lorsque le paiement a atteint un état final.

Guide : États, interrogation et rapprochement.

header Parameters
X-API-Key
required
string

Clé d'API de la licence qui a créé le paiement.

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

payment.id renvoyé par create (pour Fast Track, le payment_intent_id renvoyé par fast-track).

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

refresh
boolean
Default: true

Facultatif. true interroge la banque sur le dernier état lorsque cela est pertinent ; false renvoie l'état enregistré.

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": {
    }
}

Liste les banques et les conditions d'un profil géré

Renvoie les conditions d'un profil géré activé pour votre entreprise (bénéficiaire, libellé, limites de montant) et les banques que le payeur peut choisir. Utilisez le code choisi comme institution_code dans create.

header Parameters
X-API-Key
required
string

Clé d'API d'une licence disposant du produit PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Code du profil géré.

Exemple: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Liste les banques disponibles pour les paiements

Catalogue des banques pouvant initier des paiements, avec leur logo et les méthodes de paiement qu'elles prennent en charge. X-API-Key est facultative ; si vous l'envoyez, elle est validée et décomptée comme un appel. POST est également accepté avec les mêmes filtres dans un corps JSON, ainsi que POST /payments/?action=entities avec X-API-Key obligatoire.

Les filtres inconnus sont ignorés et ne produisent jamais d'erreur de validation.

query Parameters
country
string
Example: country=ES

Code pays ISO 3166-1 alpha-2. ALL ou une valeur vide signifie aucun filtre.

Exemple: ES

search
string

Texte contenu dans le nom ou le code, sans distinction de casse (alias q).

code
string
Example: code=santander-es

Code exact de la banque, sans distinction de casse.

Exemple: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Uniquement les banques qui prennent en charge cette méthode de paiement.

limit
integer [ 1 .. 2000 ]

Taille de page (de 1 à 2000).

offset
integer >= 0

Nombre de résultats ignorés.

header Parameters
X-API-Key
string

Facultatif. Si elle est envoyée, elle est validée et décomptée comme un appel.

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.

Exemple: 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.

Exemple: 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.

Exemple: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

Exemple: 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.

Exemple: a1b2c3d4

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

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

Exemple: 2026-07-01

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

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

Exemple: 2026-07-11

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

Filters by the email of the employee.

Exemple: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Exemple: 216

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

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

Exemple: 500

Responses

Response samples

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