Wealth Reader (8.1.12)

Download OpenAPI specification:

As APIs regulatórias baseadas em PSD2 fornecem acesso a certas informações financeiras, como saldos de contas bancárias e transações. No entanto, existem outras fontes de informações patrimoniais que não são acessíveis através dessas APIs. A API Wealth Reader estende as informações oferecidas pelas APIs regulatórias, fornecendo acesso em tempo real a fontes patrimoniais adicionais em qualquer entidade mundial. Existem dois outros documentos relacionados que irão ajudá-lo a integrar a API Wealth Reader. Um é o guia de integração do widget Javascript: https://docs-en.wealthreader.com/ e o outro é uma coleção Postman baseada nesta documentação. Muito importante: Esta definição de API é adaptada para clientes que integram via Widget, portanto alguns parâmetros que não são necessários para este tipo de integração foram omitidos, como os parâmetros de autenticação bancária, pois um token será usado.

Core

API principal necessária para integrações padrão

Obtém ativos financeiros e detalhes de sua composição

Obtém ativos financeiros e detalhes de sua composição incluindo carteiras de investimento compostas por ações ou fundos, cartões de crédito, seguros e empréstimos. Inclui informações de propriedade para cada ativo bem como identificadores únicos que facilitam o processamento de dados. É possível obter dados Mock. Verifique com a equipe técnica como fazer isso.

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

Identifica o cliente no serviço

code
string

Nome da entidade. A lista completa está disponível com GET

Exemplo: caixabank

token
string

Identifica a credencial custodiada. O fluxo pelo qual o token foi obtido está descrito no documento 'Guia de integração do Widget'. Os seguintes usuários Mock estão disponíveis: MOCKDATA, resposta OK; MOCKOTP, resposta com desafio OTP; MOCKLOGINKO, resposta com erro de login

Exemplo: MOCKDATA

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

Lista de tipos de produto dos quais as informações devem ser recuperadas. Aceita múltiplos valores separados por vírgulas.

Exemplo: accounts,portfolios

only_balances
boolean
Default: false

Indica se deseja obter apenas os saldos dos produtos em vez de todas as informações disponíveis. Valor padrão: false.

Exemplo: false

fetch_transaction_details
boolean
Default: false

Indica se devem ser obtidos detalhes ampliados das transações quando o conector da entidade o suportar. IMPORTANTE: Ativá-lo implica realizar uma ou mais navegações adicionais por cada transação para enriquecer as informações retornadas. Isto aumentará inevitavelmente e de forma significativa o tempo de execução. O número de navegações adicionais cresce com o volume de transações. Recomenda-se ativá-lo apenas quando houver certeza de que é necessário um nível de detalhe adicional ao retornado por padrão. Os detalhes obtidos são inseridos na chave additional_info ao nível de cada transação. O uso deste parâmetro requer um ambiente dedicado.

Exemplo: false

date_from
string <date>

Data a partir da qual as transações são solicitadas, no formato AAAA-MM-DD. Deve ser uma data anterior a hoje.

Exemplo: 2024-01-01

date_to
string <date>

Isso só se aplica para restringir por datas futuras para produtos loan e confirming, no formato AAAA-MM-DD. A data deve ser posterior a hoje

Exemplo: 2025-12-31

required_products_schema
string

Esquema de produtos necessários. Indica as contas ou cartões dos quais os dados são desejados, com configurações adicionais.

Exemplo:

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

Aceita uuids de transações separados por vírgulas. Parâmetro considerado apenas se product_types for ALL ou incluir accounts. Adiciona o documento PDF associado a cada uma das transações bancárias solicitadas.

Exemplo:

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Seleciona o canal de entrega do segundo fator quando a API retornou o código 2017 ou 20171 (vários métodos OTP). Chame novamente com o mesmo identificador de sessão dessa resposta e defina otp_method com a string exata do campo otp_method de um objeto em statistics.otpMethods — não o índice do array. Omita na primeira requisição com credenciais; envie após a escolha do utilizador. O exemplo abaixo é ilustrativo; copie sempre a string em statistics.otpMethods para a sua entidade.

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

Lista de tipos de transação

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Consultar tokens associados a uma api_key

Use este método para consultar os tokens vinculados a uma api_key específica. Os resultados são paginados: limit define o número de tokens por página (máximo 500) e page indica a página a devolver. api_key, method e limit são obrigatórios; se algum deles faltar ou for inválido, a API responde com HTTP 400 e o código de erro 2.

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

api_key para identificar o cliente no serviço

method
required
string
Value: "get"

Operação a realizar. O único valor suportado é get.

Exemplo: get

limit
required
integer [ 1 .. 500 ]

Número de tokens por página. Mínimo 1, máximo 500.

Exemplo: 100

page
integer >= 1
Default: 1

Especifique o número da página que deseja recuperar. Cada página contém até limit tokens. Se não fornecido, o valor padrão é 1.

Exemplo: 1

code
string

Código da entidade usado para filtrar os tokens. Se omitido, são devolvidos os tokens de todas as entidades.

Exemplo: bbva

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

Campo usado para ordenar os resultados: created_at (data de criação) ou accesed_at (data do último acesso). Padrão created_at.

Exemplo: created_at

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

Direção da ordenação: ASC (ascendente) ou DESC (descendente). Padrão DESC.

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

Revogar um token

Este método permite revogar um token existente para desautorizar futuras solicitações de acesso à API.

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

Identifica o cliente no serviço

token
string

Token a ser revogado.

Responses

Response samples

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

Reatribuir um token a uma api_key diferente

Este método permite reatribuir um token de uma api_key para outra. Ambas as api_keys devem estar ativas e pertencer à mesma empresa, e o token deve pertencer à api_key_source.

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

api_key a partir da qual reatribuir o token.

api_key_target
string

api_key para a qual reatribuir o token.

token
string

Token a ser reatribuído.

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

Adicionar um novo domínio

Adiciona a associação entre o domínio que hospedará o widget e o webhook de destino. Para editar ou testar os seus domínios, use https://www.wealthreader.com/clients/

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

Method to execute.

Exemplo: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Exemplo: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Controla se o widget inicia um fluxo de tokenização:

  • 1 - O utilizador autentica-se na instituição financeira (login, consentimento, 2FA se necessário) e é devolvido um token reutilizável para futuras consultas
  • 0 - Não é realizada tokenização. O valor do token obtido anteriormente deve ser incluído no pedido

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

Lista de códigos de erro

Lista de códigos de erro. Preste atenção especial ao fato de que nem todos os códigos de erro devem receber o mesmo tratamento da sua aplicação. Para um erro de senha incorreta, você não deve tentar novamente a chamada com os mesmos parâmetros, mas para um erro indicando que a entidade está em manutenção, você pode tentar novamente. Solicite uma sessão técnica com nossa equipe para resolver quaisquer questões sobre gerenciamento de erros.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Lista de códigos de aviso

Lista de códigos de aviso.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Endpoints opcionais não necessários para integrações padrão. Use apenas se explicitamente instruído pela Wealth Reader.

Obtém a lista de entidades suportadas

Obtém a lista de entidades suportadas e as informações necessárias para desenhar o formulário de login da entidade.

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

Registrar um novo usuário

Este endpoint é opcional e não é necessário para integrações padrão. Use apenas se explicitamente instruído pela Wealth Reader. Este endpoint permite registrar um usuário na plataforma de transferência de portfólio Easytransfer ou na ferramenta de relatórios Acumulas, com base em um identificador único.

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.

Exemplo: 12345678A

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

Service associated with the user. Determines the data flow.

Exemplo: easy-transfer

email
required
string <email>

User email, used according to service type.

Exemplo: sai_banker@singularbank.com

Responses

Response samples

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

Verificar status de registro do usuário

Este endpoint é opcional e não é necessário para integrações padrão. Use apenas se explicitamente instruído pela Wealth Reader. Verifica se um usuário está registrado no sistema Easytransfer ou Acumulas e retorna o link de acesso único para o usuário.

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

Authentication key

user_id
required
string

User identification document.

Exemplo: 12345678A

Responses

Response samples

Content type
application/json
{}

Revogar um usuário previamente registrado

Este endpoint é opcional e não é necessário para integrações padrão. Use apenas se explicitamente instruído pela Wealth Reader. Este endpoint permite cancelar o registro de um usuário do serviço da plataforma 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.

Exemplo: 12345678A

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

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

Exemplo: easy-transfer

Responses

Response samples

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

Carregamento de conexões em lote

Este endpoint é opcional e não é necessário para integrações padrão. Use apenas se explicitamente instruído pela Wealth Reader. Importante: Para utilizar a gestão de processos batch do lado do Wealthreader, é necessário contar com um ambiente dedicado. Este endpoint não está disponível em api.wealthreader.com. Os endpoints agrupados sob a tag "batch" permitem processar múltiplas conexões bancárias de forma assíncrona, ao contrário do método /entities/ que é síncrono. Ideal para processar grandes volumes de conexões e evitar 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.

Exemplo: 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",
  • "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"
}

Obter estatísticas gerais sobre conexões batch

Este endpoint é opcional. Recupera estatísticas gerais sobre o resultado do processamento de todas as conexões em um lote.

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

Obter resultado individual de uma conexão específica dentro de um batch

Este endpoint é opcional. Recupera o resultado de uma conexão específica do lote.

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

Verificação de titularidade: verifique se um IBAN pertence a um titular através da Verificação do Beneficiário (VoP) SEPA do banco associado à sua licença. Guia passo a passo: MyBankMatch.

Verifica se um IBAN pertence a um titular (MyBankMatch)

Verifica se um IBAN pertence ao titular indicado através da Verificação do Beneficiário (VoP) SEPA do seu próprio banco, associado à sua licença da WealthReader. Devolve o veredicto do banco: não o substitui por um cálculo local de semelhança de nomes nem cria, autoriza ou executa qualquer ordem de pagamento.

Antes da primeira chamada

  1. Disponha de uma licença ativa com o produto MY_BANK_MATCH e quota disponível.
  2. Abra Clientes · MyBankMatch, clique em Ligar banco e conclua a autenticação na janela alojada da WealthReader. A ligação tokenizada fica associada à sua api_key; o token bancário não é entregue ao navegador nem é um parâmetro da consulta.

Pedido: corpo codificado como formulário (application/x-www-form-urlencoded) com api_key, iban e name, tal como em /entities/. Não se envia JSON nem se utiliza o cabeçalho X-API-Key. Mantenha a api_key no seu backend.

Resposta: HTTP 200 indica que foi obtido um resultado do produto, não que o nome coincida. Verifique success e depois payload.result:

payload.result Significado Campos adicionais Faturável
MATCH O banco considera que o nome coincide com o titular. Nenhum. Sim, 0,10 EUR.
PARTIAL_MATCH O banco devolve uma coincidência parcial (CLOSE_MATCH). suggested_name. Sim, 0,10 EUR.
NO_MATCH O banco indica que o nome não coincide. Nenhum. Sim, 0,10 EUR.
NOT_CONFIGURED A licença ainda não tem um banco associado. setup_url. Não.
REAUTH_REQUIRED A ligação ao banco necessita de uma nova autenticação. setup_url, reason_code. Não.
NOT_POSSIBLE Não foi possível obter um veredicto utilizável. Não equivale a NO_MATCH. reason. Não.

Apenas MATCH, PARTIAL_MATCH e NO_MATCH consomem quota. Os erros de entrada e os resultados não conclusivos não são faturados.

Não existe chave de idempotência nem nova tentativa gratuita. Se perder a resposta (timeout, rede ou um corpo não interpretável), o resultado e o respetivo consumo de quota podem ser desconhecidos para a sua aplicação. Não volte a enviar automaticamente a mesma consulta: reveja o histórico em Clientes e contacte o suporte indicando statistics.SESSION.

Guia completo: MyBankMatch.

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

Chave de 8 caracteres hexadecimais de uma licença ativa com o produto MY_BANK_MATCH e quota disponível. Mantenha-a no seu backend.

iban
required
string

IBAN de um país SEPA. São removidos os espaços, é convertido para maiúsculas e são validados o comprimento do respetivo país e os dígitos de controlo mod-97.

Exemplo: ES9321005707250200257112

name
required
string <= 140 characters

Nome do titular. Não vazio, UTF-8 válido, sem caracteres de controlo e até 140 caracteres. É aparado e os espaços internos são colapsados.

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

Pagamentos SEPA de conta para conta iniciados a partir do banco do pagador. Existem duas formas de os integrar:

  • Fast Track: um único POST /payments/?action=fast-track devolve o URL de pagamento e a Wealth Reader notifica o seu notification_url com OK ou KO. Consulte Pagamentos Fast Track.
  • Widget: o seu backend cria uma intenção de pagamento imutável com POST /payments/?action=create, abre o widget com o token devolvido e confirma o resultado com POST /payments/?action=status. Consulte Introdução aos pagamentos e Estados, sondagem e reconciliação.

Regras comuns a todas as chamadas /payments/?action=...

  • Método POST com o cabeçalho Content-Type: application/json e um objeto JSON como corpo (máximo de 32768 bytes).
  • Autenticação apenas com o cabeçalho X-API-Key (wr_live_ seguido de 72 letras ou dígitos) de uma licença ativa com o produto PAYMENTS. Nunca é enviada no corpo. Cada chamada autenticada conta para o limite de chamadas da licença.
  • O corpo é uma lista branca: a falta de um campo obrigatório ou a presença de um campo não previsto devolve 422 invalid_request.
  • A única confirmação financeira positiva é payment_status: settled. Um evento do widget, um retorno SCA ou interaction_status: completed nunca significam que o pagamento esteja liquidado.

Formato de erro: application/json (não problem+json) com um error.code estável; error.message é informativo e pode mudar.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motivo
400 invalid_json Corpo vazio, inválido ou que não é um objeto JSON.
401 invalid_api_key X-API-Key ausente, mal formada, desconhecida ou inativa.
403 payments_not_allowed A licença não tem o produto PAYMENTS.
404 action_not_found action desconhecida.
405 method_not_allowed Método diferente de POST.
413 request_too_large Corpo com mais de 32768 bytes.
415 json_required Content-Type diferente de application/json.
422 invalid_request Campos em falta ou não previstos.
429 api_limit_reached Foi atingido o limite de chamadas da licença.
500 internal_error Erro inesperado.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Serviço temporariamente indisponível ou novos pagamentos em pausa.

Notificação de OK ou KO de um pagamento Fast Track Webhook

A Wealth Reader envia este POST para o notification_url de um pagamento Fast Track quando verifica o estado do pagamento e o encontra num estado final. reconciliation_required não é final e não é notificado: confirme-o com status.

  • outcome é ok apenas se o banco tiver liquidado o pagamento (settled); rejected, cancelled, expired e failed notificam ko.
  • O estado é verificado enquanto o pagador permanece na página de pagamento (que o consulta até ao resultado final ou até a sessão de pagamento expirar) e sempre que chama status. Não existe um envio agendado à parte: se o pagador sair antes de o banco concluir, ou se o seu servidor não responder 2xx, a notificação é enviada na verificação seguinte. Se não tiver chegado alguns minutos depois de redirecionar o pagador, chame status com o payment_intent_id; essa chamada também desencadeia a notificação pendente.
  • Responda com qualquer 2xx para a dar como entregue. A Wealth Reader não segue redirecionamentos e espera no máximo 3 segundos.
  • A mesma notificação pode chegar mais do que uma vez: trate customer_reference mais outcome como idempotentes.
  • O pedido não é assinado. Antes de entregar um bem valioso, confirme o resultado com status utilizando a sua X-API-Key e o payment_intent_id da notificação.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok apenas para settled.

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

Resultado financeiro final.

customer_reference
required
string

A Idempotency-Key que enviou ao criar o pagamento.

payment_intent_id
required
string <uuid>

Identificador devolvido por fast-track. Utilize-o para confirmar o resultado com 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"
}

Cria um pagamento e obtém o respetivo URL (Fast Track)

Uma única chamada que devolve o URL de pagamento. O pagador abre-o e autoriza no seu banco; quando o pagamento atinge um estado final, a Wealth Reader notifica o seu notification_url com OK ou KO (consulte o webhook notification_url). Internamente, é criada a mesma intenção imutável que com create: o montante, o beneficiário e o descritivo ficam fixados antes de chegarem ao navegador.

O cabeçalho Idempotency-Key é também a sua referência de comerciante (customer_reference na notificação): não é enviado no corpo. Se repetir a mesma chave com o mesmo corpo, recebe o mesmo URL; se a reutilizar com outros dados (incluindo outro logo), a resposta é 409 idempotency_conflict.

Uma transferência imediata não tem um limite próprio nesta API: o banco rejeita a que não puder aceitar, incluindo por montante, e essa rejeição chega como KO.

header Parameters
X-API-Key
required
string

Chave de API de uma licença com o produto PAYMENTS. Mantenha-a no seu backend.

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

De 16 a 128 caracteres; deve começar por uma letra ou um dígito e conter apenas letras, dígitos e . _ : -. Um UUID v4 é válido. É também a referência de comerciante devolvida na notificação.

Request Body schema: application/json
required
amount
required
string

Montante em unidades principais, como cadeia JSON. "15.50" correspondem a 15,50 EUR; também é aceite um inteiro sem decimais ("15"). No máximo duas casas decimais, pelo que "15.5" e "15.50" são o mesmo montante. Mínimo 0.01. O máximo está limitado ao limite que cada cliente tiver configurado no seu banco.

Exemplo: 15.50

currency
required
string
Value: "EUR"

Moeda ISO 4217. Nesta versão, apenas EUR.

Exemplo: EUR

required
object (payments-beneficiary)

Destinatário da transferência. Não pode ser alterado depois de o pagamento ser criado.

reference
required
string [ 1 .. 140 ] characters

Descritivo do extrato, até 140 caracteres.

Exemplo: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (transferência SEPA) ou instant (transferência SEPA imediata).

Exemplo: normal

notification_url
required
string <= 2000 characters

URL https público que recebe a notificação de OK ou KO. Sem credenciais, porta 443 se for indicada e sem endereços privados, locais nem de metadados.

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

logo
string <= 2048 characters

Opcional. URL https público do logótipo do seu comerciante em SVG (o caminho deve terminar em .svg; admite parâmetros de consulta), sem credenciais, fragmento nem endereços privados, até 2048 caracteres ASCII. A página de pagamento apresenta-o acima do resumo; a Wealth Reader não o descarrega, é o navegador do pagador que o carrega. Qualquer outro valor devolve 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Cria uma intenção de pagamento (widget)

Cria uma intenção de pagamento imutável e devolve um token de curta duração para abrir o widget no navegador do pagador. O montante, o beneficiário e o descritivo ficam fixados no backend e não podem ser alterados a partir do navegador. Depois de o widget ser fechado, confirme o resultado a partir do seu backend com status.

Existem duas variantes de corpo:

  • Padrão: o utilizador fixa amount_minor, currency, beneficiary, reference, customer_reference e allowed_origin.
  • Perfil gerido (por exemplo cruz_roja_demo): a Wealth Reader fixa o beneficiário, o descritivo e os limites; o utilizador envia profile, institution_code, amount_minor, customer_reference e allowed_origin. Obtenha os bancos com profile-institutions.

Se repetir a mesma Idempotency-Key com o mesmo corpo, recebe a mesma intenção (200, idempotent_replay: true); se a reutilizar com outros dados, a resposta é 409 idempotency_conflict. A chave é própria da sua empresa.

Guia: Intenções e idempotência e Integração com o widget.

header Parameters
X-API-Key
required
string

Chave de API de uma licença com o produto PAYMENTS. Mantenha-a no seu backend.

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

De 16 a 128 caracteres ASCII visíveis. Gere uma por pagamento (um UUID v4 é válido) e reutilize-a se repetir a chamada.

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

Montante em unidades secundárias (cêntimos) como inteiro JSON. 1500 correspondem a 15,00 EUR. O máximo está limitado ao limite que cada cliente tiver configurado no seu banco.

Exemplo: 1500

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

Destinatário da transferência. Não pode ser alterado depois de o pagamento ser criado.

reference
required
string [ 1 .. 140 ] characters

Descritivo do extrato, até 140 caracteres.

Exemplo: Pedido 78901

customer_reference
required
string <= 128 characters

A sua referência interna do pagamento. De 1 a 128 caracteres; começa por uma letra ou um dígito e contém apenas letras, dígitos e . _ : -.

Exemplo: order-78901

allowed_origin
required
string

Origem (https://host[:puerto], sem caminho, consulta nem fragmento) da página que abre o widget. O widget só funciona a partir dessa origem.

Exemplo: https://tienda.example.com

locale
string
Value: "es"

Opcional. Idioma do widget; nesta versão, apenas es.

expected_mode
string
Enum: "mock" "live"

Opcional. Se não coincidir com o ambiente, a chamada devolve 409 payment_mode_mismatch em vez de criar o pagamento.

allowed_institution_codes
Array of strings <= 2500 items

Opcional. Lista não vazia de códigos de banco únicos (consulte /payments/entities/) entre os quais o pagador pode escolher.

Exemplo:

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

Opcional. URL https público do seu logótipo em SVG (caminho terminado em .svg), sem credenciais, fragmento nem endereços privados, até 2048 caracteres.

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

Consulta o estado de um pagamento

Consulta servidor a servidor do estado de um pagamento, até obter uma conclusão bancária. Um callback, um retorno SCA ou o fecho do widget não são uma confirmação financeira: apenas payment_status: settled o é.

A Wealth Reader limita as consultas externas por intenção; aplique também backoff no seu backend e não crie outra intenção enquanto o resultado for ambíguo.

Resultado ambíguo: uma falha de rede, timeout ou resposta não reconhecida após a emissão do início altera a intenção para reconciliation_required com payment_status: unknown, e a resposta inclui reconciliation. A iniciação nunca é repetida automaticamente. Conserve o identificador e a chave de idempotência, não crie outra intenção nem volte a autorizar e, quando automatic_recovery for false, deixe de sondar e escale para o suporte com reconciliation.reference.

Nos pagamentos Fast Track, esta consulta também envia para notification_url a notificação de OK/KO pendente quando o pagamento atingiu um estado final.

Guia: Estados, sondagem e reconciliação.

header Parameters
X-API-Key
required
string

Chave de API da licença que criou o pagamento.

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

payment.id devolvido por create (em Fast Track, o payment_intent_id devolvido por fast-track).

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

refresh
boolean
Default: true

Opcional. true consulta o banco sobre o estado mais recente quando aplicável; false devolve o estado armazenado.

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

Lista os bancos e as condições de um perfil gerido

Devolve as condições de um perfil gerido ativado para a sua empresa (beneficiário, descritivo, limites de montante) e os bancos que o pagador pode escolher. Utilize o code escolhido como institution_code em create.

header Parameters
X-API-Key
required
string

Chave de API de uma licença com o produto PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Código do perfil gerido.

Exemplo: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Lista os bancos disponíveis para pagamentos

Catálogo de bancos que podem iniciar pagamentos, com o respetivo logótipo e os métodos de pagamento que suportam. X-API-Key é opcional; se for enviada, é validada e conta como chamada. Também admite POST com os mesmos filtros num corpo JSON, e POST /payments/?action=entities com X-API-Key obrigatória.

Os filtros desconhecidos são ignorados e nunca produzem um erro de validação.

query Parameters
country
string
Example: country=ES

Código de país ISO 3166-1 alfa-2. ALL ou vazio significa sem filtro.

Exemplo: ES

search
string

Texto contido no nome ou no código, sem distinguir maiúsculas de minúsculas (alias q).

code
string
Example: code=santander-es

Código exato do banco, sem distinguir maiúsculas de minúsculas.

Exemplo: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Apenas os bancos que suportam este método de pagamento.

limit
integer [ 1 .. 2000 ]

Tamanho da página (de 1 a 2000).

offset
integer >= 0

Número de resultados a ignorar.

header Parameters
X-API-Key
string

Opcional. Se for enviada, é validada e conta como chamada.

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.

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

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

Exemplo: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Exemplo: a1b2c3d4

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

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

Exemplo: 2026-07-01

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

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

Exemplo: 2026-07-11

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

Filters by the email of the employee.

Exemplo: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Exemplo: 216

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

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

Exemplo: 500

Responses

Response samples

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