Pagamentos

Pagamentos Fast Track

Se você escolher esta via, não precisa montar o widget nem seguir as demais seções de pagamentos. Um único POST devolve a URL de pagamento, e a Wealthreader avisa o seu servidor quando o resultado é OK ou KO. Como garantia, guarde o payment_intent_id da resposta: com ele você pode consultar o estado se o aviso não chegar.

O pagador abre essa URL e autoriza o pagamento no próprio banco. Por baixo, é criada a mesma intenção imutável que no restante da API: o valor, o destinatário e a descrição ficam fixados antes de chegar ao navegador, e o cabeçalho Idempotency-Key evita uma segunda cobrança se a chamada for interrompida.

Criar o pagamento

POST /payments/?action=fast-track

Cabeçalhos obrigatórios: Content-Type: application/json, X-API-Key e Idempotency-Key. A chave tem de 16 a 128 caracteres, começa por letra ou número e só admite letras, números e . _ : -; um UUID v4 serve. Se faltar ou se o comprimento não for válido, a resposta é 400 idempotency_key_required; se usar outros caracteres, 422 invalid_customer_reference. Essa chave também é a referência do comerciante: não é preciso enviá-la no corpo. Se você repetir a mesma chave com o mesmo corpo, recebe novamente a mesma URL. Se reutilizá-la com outros dados, a resposta é 409 idempotency_conflict.

Campo	Tipo	Descrição
`amount`	String	Valor em unidades principais, como string JSON. `"15.50"` equivale a 15,50. Também se admite um inteiro sem decimais (`"15"`). No máximo duas casas decimais: `"15.5"` e `"15.50"` são o mesmo valor. Mínimo `0.01`. O máximo está limitado ao limite que cada cliente tiver configurado no seu banco. Fora dessas regras de formato, `422 invalid_amount`.
`currency`	String	Moeda ISO 4217. Nesta versão, `EUR`.
`beneficiary`	Objeto	Destinatário: `name` (de 1 a 140 caracteres) e `iban` (sem espaços, com dígito de controle).
`reference`	String	Descrição que aparece no extrato, com até 140 caracteres.
`priority`	String	`normal` ou `instant`.
`notification_url`	String	URL `https` pública que recebe o aviso de OK ou KO.
`logo`	String	Opcional. URL `https` pública do logotipo do seu comércio em SVG: o caminho deve terminar em `.svg` (admite parâmetros de consulta), sem credenciais nem endereços privados, com até 2048 caracteres ASCII. A página de pagamento o exibe acima do resumo, junto ao nome do beneficiário; sem `logo`, não há cabeçalho do comércio. A Wealthreader não baixa a URL: quem a carrega é o navegador do pagador. Qualquer outro valor responde `422 invalid_logo`.

Todos os campos são obrigatórios, exceto logo. O corpo é uma lista de permissões. Um campo a mais, ou um obrigatório que falte, responde 422 invalid_request. logo faz parte do pagamento: repetir a mesma Idempotency-Key com outro logo também resulta em 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, inclusive pelo valor, e essa rejeição chega como KO ao notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

A resposta, com 201 na primeira vez e 200 se a chave já existia, contém a URL e o identificador do pagamento:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Redirecione o pagador para a URL. O token fica no fragmento, expira com o widget (normalmente 15 minutos) e não deve ser registrado nos seus logs. Guarde o payment_intent_id junto ao seu pedido.

Aviso de OK ou KO

Quando a Wealthreader verifica o estado do pagamento e o encontra em um estado final, faz um POST para notification_url com Content-Type: application/json e User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome é ok somente se o banco tiver liquidado o pagamento (settled). rejected, cancelled, expired e failed geram o aviso ko. Um resultado ambíguo (reconciliation_required) não é final e não é avisado.
customer_reference é a sua Idempotency-Key, e payment_intent_id é o identificador devolvido ao criar o pagamento.
Responda 2xx para dar o aviso por entregue. A Wealthreader espera no máximo 3 segundos e não segue redirecionamentos.
O mesmo aviso pode chegar mais de uma vez: trate customer_reference mais outcome como idempotentes.
Uma URL que não seja https pública é rejeitada ao criar o pagamento e é verificada novamente antes de cada envio.

Quando chega. O estado é verificado enquanto o pagador continua na página de pagamento, que o consulta até o resultado final ou até a sessão de pagamento expirar, e sempre que você consulta POST /payments/?action=status. Não há um envio programado à parte: se o pagador fechar a página antes de o banco concluir, ou se o seu servidor não responder 2xx, o aviso é enviado na verificação seguinte. Por isso, se você não tiver recebido o aviso alguns minutos depois de redirecionar o pagador, consulte o estado com o payment_intent_id; essa consulta também dispara o aviso pendente. Veja Estados, sondagem e reconciliação.

O aviso não é assinado. Antes de entregar um bem ou serviço de valor, confirme o resultado com POST /payments/?action=status usando a sua X-API-Key e o payment_intent_id: somente payment_status: settled nessa resposta é uma confirmação financeira.

Última atualização 2026-11-08