Idempotente de raiz
A mesma chave com o mesmo corpo devolve o mesmo link: uma chamada repetida nunca cria um segundo pagamento.
Programadores
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.
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"
}'
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"
}
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"
}
Cabeçalhos, campos, estados e erros de POST /payments/?action=fast-track. O detalhe completo está no guia.
| Cabeçalho | Validação |
|---|---|
X-API-Key | A sua chave de API da Wealthreader, com os pagamentos ativos. |
Idempotency-Key | De 16 a 128 caracteres: letras, números e . _ : -. É a sua referência do pagamento e regressa na notificação como customer_reference. |
| Campo | Validação | Obrigatório |
|---|---|---|
amount | Montante em euros como cadeia de caracteres, com até duas casas decimais: "2450.00". Mínimo 0.01. | Sim |
currency | EUR. | Sim |
beneficiary.name | Nome do beneficiário, de 1 a 140 caracteres. | Sim |
beneficiary.iban | IBAN do beneficiário, sem espaços e com dígitos de controlo válidos. Não é necessário registá-lo previamente. | Sim |
reference | Descritivo que o seu cliente verá e que chega ao extrato, até 140 caracteres. | Sim |
priority | instant para transferência imediata ou normal para transferência padrão. | Sim |
notification_url | URL https público para o qual enviamos a notificação ok ou ko. | Sim |
logo | URL https público do logótipo da sua empresa em SVG, que a página de pagamento mostra junto ao beneficiário. | Não |
payment_status | Significado | outcome |
|---|---|---|
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 |
| HTTP | Código | Significado |
|---|---|---|
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.
A mesma chave com o mesmo corpo devolve o mesmo link: uma chamada repetida nunca cria um segundo pagamento.
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.
Envie o URL do seu logótipo em SVG e a página de pagamento mostra-o junto ao nome do beneficiário.
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.
Abrir o guia Pagamentos Fast Track (abre num novo separador) Abrir a referência da API (abre num novo separador) Pedir acesso
Mostramos-lhe a FastTrackPay com as cobranças do seu negócio.