Programadores

Uma chamada. Um link de pagamento.

A FastTrackPay é um ponto de acesso da API de pagamentos da Wealthreader: HTTPS e JSON. Envie o pagamento, redirecione o seu cliente e receba a notificação com a sua referência.

Para começar, ativamos os pagamentos e o seu perfil de pagamento na sua chave de API da Wealthreader. Se já utiliza a API, é a mesma chave.

  1. Crie o pagamento

    Um POST com a sua chave de API, uma chave de idempotência que é também a sua referência e o corpo do pagamento: montante, moeda, beneficiário, descritivo, prioridade e URL de notificação.

    # Criar o pagamento
    curl 'https://api.wealthreader.com/payments/?action=fast-track' \
      -H "X-API-Key: $API_KEY" \
      -H "Idempotency-Key: invoice-F-2026-104" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "2450.00",
        "currency": "EUR",
        "beneficiary": {
          "name": "Empresa Exemplo, Lda.",
          "iban": "ES9121000418450200051332"
        },
        "reference": "Fatura F-2026-104",
        "priority": "instant",
        "notification_url": "https://example.com/payments/notice"
      }'
  2. Leve o seu cliente ao link

    A resposta traz o URL do pagamento e o respetivo identificador. Redirecione o seu cliente para o URL: expira ao fim de poucos minutos (15 por predefinição), por isso crie-o quando ele for pagar.

    {
      "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
      "payment_intent_id": "22222222-2222-4222-8222-222222222222"
    }
  3. Receba a notificação

    Quando o pagamento chega a um estado final, enviamos um POST para o seu notification_url com outcome ok ou ko e a sua referência em customer_reference. Responda com um código 2xx.

    A notificação pode chegar mais do que uma vez e não é assinada: antes de entregar algo valioso, confirme o estado com POST /payments/?action=status.

    {
      "outcome": "ok",
      "payment_status": "settled",
      "customer_reference": "invoice-F-2026-104",
      "payment_intent_id": "22222222-2222-4222-8222-222222222222"
    }

Referência rápida

Cabeçalhos, campos, estados e erros de POST /payments/?action=fast-track. O detalhe completo está no guia.

Cabeçalhos do pedido
CabeçalhoValidação
X-API-KeyA sua chave de API da Wealthreader, com os pagamentos ativos.
Idempotency-KeyDe 16 a 128 caracteres: letras, números e . _ : -. É a sua referência do pagamento e regressa na notificação como customer_reference.
Campos do corpo
CampoValidaçãoObrigatório
amountMontante em euros como cadeia de caracteres, com até duas casas decimais: "2450.00". Mínimo 0.01.Sim
currencyEUR.Sim
beneficiary.nameNome do beneficiário, de 1 a 140 caracteres.Sim
beneficiary.ibanIBAN do beneficiário, sem espaços e com dígitos de controlo válidos. Não é necessário registá-lo previamente.Sim
referenceDescritivo que o seu cliente verá e que chega ao extrato, até 140 caracteres.Sim
priorityinstant para transferência imediata ou normal para transferência padrão.Sim
notification_urlURL https público para o qual enviamos a notificação ok ou ko.Sim
logoURL https público do logótipo da sua empresa em SVG, que a página de pagamento mostra junto ao beneficiário.Não
Estados do pagamento e notificação
payment_statusSignificadooutcome
settled O banco liquidou o pagamento. ok
rejected O banco rejeitou o pagamento, incluindo por causa do montante ou por não aceitar a transferência imediata. ko
cancelled Foi cancelado antes de ser concluído. ko
expired A sessão de pagamento expirou sem ser concluída. ko
failed Não foi possível concluir o pagamento. ko
pending Em curso: ainda não é um estado final. Ainda sem notificação
Códigos de erro
HTTPCódigoSignificado
400 idempotency_key_required Falta o cabeçalho Idempotency-Key ou o seu comprimento não é válido.
401 invalid_api_key Chave de API inválida.
403 payments_not_allowed, payment_profile_required A sua chave não tem os pagamentos ativos ou falta-lhe o perfil de pagamento.
409 idempotency_conflict Reutilizou uma Idempotency-Key com outros dados.
422 invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url Corpo inválido: um campo a mais ou em falta, ou um montante, beneficiário ou URL de notificação incorretos.
429 api_limit_reached Atingiu o limite de chamadas.
503 payments_disabled Os pagamentos não estão disponíveis neste momento.

Os erros devolvem um JSON com success a false e o código da tabela em error.code.

Detalhes de integração

Idempotente de raiz

A mesma chave com o mesmo corpo devolve o mesmo link: uma chamada repetida nunca cria um segundo pagamento.

Imediata ou padrão

Escolha em cada pagamento a transferência imediata ou a padrão. Se o banco não aceitar a imediata, a notificação chega como ko.

A sua marca no pagamento

Envie o URL do seu logótipo em SVG e a página de pagamento mostra-o junto ao nome do beneficiário.

A página de pagamento

O seu cliente revê o montante, o beneficiário e o descritivo, escolhe o banco e autoriza. Por agora, a página é apresentada em espanhol.

Não peça ao seu cliente uma transferência: envie-lhe o pagamento preparado

Mostramos-lhe a FastTrackPay com as cobranças do seu negócio.

Pedir uma demonstração