Pagamentos com Wealth Reader

Arquitetura em dois passos

A integração de pagamentos segue uma separação rigorosa de responsabilidades em duas etapas:

sequenceDiagram
autonumber
actor Usuario as Usuário
participant Front as Frontend (Comércio)
participant Back as Backend (Comércio)
participant API as API Wealth Reader
participant Widget as Pagamentos por Widgets
participant Banco as Banco (SCA)
Note over Back,API: Etapa anterior (apenas perfis gerenciados)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Catálogo de Perfis (institution_code)
Note over Back,API: Passo 1: Criando a Intenção Imutável (Servidor para Servidor)
Back->>API: POST /payments/?action=create (com X-API-Key e Idempotency-Key)
API-->>Back: 201 com payment.id + payment.widget.token efêmero
Note over Front,Widget: Passo 2: Carregue e autorize no widget (navegador)
Back->>Front: Entrega payment.id e payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) ou load-payments.js
Widget->>Usuario: Exibe instituição, valor e descrição do pagamento imutáveis
Usuario->>Widget: Autorizar pagamento
Widget->>Banco: Redirecionar / Aplicativo para Aplicativo (SCA)
Banco->>API: Retorno da SCA ao callback de Wealth Reader
API-->>Widget: Confirmação técnica da autorização
Note over Back,API: Reconciliação Financeira e Confirmação
loop Para o estado terminal
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Passo 1 (Backend Seguro): Seu servidor cria uma intenção de pagamento (POST /payments/?action=create) com seu X-API-Key, um Idempotency-Key e Content-Type: application/json. Nessa chamada, o valor (amount_minor, em centavos), a moeda (currency, hoje apenas EUR), o beneficiário (beneficiary.name e beneficiary.iban), a descrição exibida no extrato (reference), sua referência interna (customer_reference) e a origem web permitida (allowed_origin) são fixos de forma imutável. Esses seis campos são obrigatórios, e o corpo é uma lista branca rígida: qualquer campo não reconhecido retorna 422 invalid_request.
2. Resposta: 201 com {"success": true, "payment": {…}} — ou 200 se for uma repetição idempotente. A ID de intenção vem em payment.id e a token efêmera do widget em payment.widget.token.
3. Passo 2 (Frontend da operação): O navegador monta o widget usando o script oficial de load-payments.js ou a função WealthReaderPayments.mount(), entregando apenas o payment.id e o payment.widget.token. O usuário seleciona seu banco (se não foi pré-selecionado na intenção) e completa a autenticação forte (SCA) na interface bancária.
4. Confirmação financeira: Seu backend consulta o estado usando POST /payments/?action=status, cujo corpo é exatamente {"payment_intent_id": "<id>"}. Sem webhook: ele consulta até atingir um estado terminal.

Dois modelos de pagamento

Wealth Reader suporta dois modelos dependendo das necessidades do negócio:

1. Integração padrão para comerciantes (Beneficiário próprio):
   • O comerciante define livremente o nome e a IBAN do beneficiário, o montante, a moeda (EUR), o conceito e sua referência à ordem.
   • Você pode filtrar quais bancos disponibilizar ao usuário usando allowed_institution_codes ou permitir o catálogo completo.
2. Perfis gerenciados (como cruz_roja_demo):
   • Projetado para doações e demonstrações públicas.
   • O servidor define as contas oficiais de destino para garantir que os fundos só possam ser direcionados à instituição de caridade (por exemplo, a Cruz Vermelha Espanhola com valores entre 0,01 EUR e 1,00 EUR).

Diretório unificado de entidades bancárias

Wealth Reader fornece um catálogo unificado de entidades europeias preparadas para a iniciação de pagamentos via PSD2 por meio de:

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

Ele permite obter a lista de bancos com seus nomes padronizados, logotipos, métodos de transferência suportados e requisitos técnicos (como a necessidade de solicitar a IBAN do devedor ao pagador). Ele suporta os filtros country, search (alias q), code, payment_method, limit e offset.

Esse endpoint é público: não requer X-API-Key. Enviar não contribui com nada e consome uma chamada da sua cota de chamadas da credencial.

Sempre use esses códigos conforme vêm code. Criar a intenção valida a formatação allowed_institution_codes, mas não verifica se eles existem no catálogo: código com erros de ortografia não falha na criação e aparece depois como um coletor de banco vazio.

Separação de responsabilidades

• A chave de acesso ao pagamento (X-API-Key) é usada apenas de servidor para servidor. Ela nunca deve ser incluída em repositórios frontend ou públicos.
• O navegador recebe apenas o identificador da intenção e uma token efêmera de curta duração vinculada à origem HTTPS.
• O widget não pode alterar o valor, moeda, beneficiário, conceito ou instituições autorizadas.
• Fechar o modal ou widget não substitui consultar o estado financeiro do pagamento no backend.
• Pagamentos não compartilham chaves de acesso, tokens ou callbacks com o produto de agregação bancária da Wealth Reader.

Credenciais e cota de chamadas

Sua chave de pagamento deve ter o produto PAYMENTS ativado; caso contrário, a API responde 403 payments_not_allowed. Uma chave de acesso faltando ou formatada incorretamente retorna 401 invalid_api_key.

Próximo passo

Continue com Integração e widget.