Construir a Verification of Payee de raiz significa integrar-se com cada PSP respondente e normalizar cada resposta. Uma API VoP elimina esse trabalho: liga-se uma vez e o prestador trata da conectividade ao esquema em toda a SEPA. A sua tarefa torna-se uma integração limpa de pedido/resposta.
1. Autentique-se
As chamadas são feitas por HTTPS e autenticadas com um bearer token. Guarde a credencial como segredo, nunca no cliente. Para verificações manuais ou de baixo volume existe um painel disponível, para que quem não programa possa verificar sem escrever código.
2. Envie o pedido
Envie por POST o nome e o IBAN do beneficiário para o endpoint de verificação. Inclua o seu próprio id de referência para reconciliar o resultado com o pagamento ou o registo de onboarding a que pertence.
Mantenha-a idempotente
Passe um id externo estável em cada pedido para que as repetições não criem verificações duplicadas e possa ligar uma entrada de log assíncrona à ação de origem.
3. Trate os quatro resultados
Cada resposta corresponde a um código do esquema SEPA, por isso a sua ramificação mantém-se simples:
- MATCH (MTCH) — o nome corresponde ao titular da conta; prossiga com confiança.
- CLOSE_MATCH (CMTC) — quase certo; mostre o nome verificado sugerido e peça ao utilizador para confirmar.
- NO_MATCH (NMTC) — mostre um aviso claro antes de o pagamento ser confirmado.
- NOT_APPLICABLE (NOAP) — verificação indisponível neste momento; deixe o utilizador decidir.
A resposta traz também o BIC do banco respondente e o tempo de processamento, úteis para monitorização e logs de auditoria.
4. Reutilize-a em todo o lado
Como o contrato é o mesmo, o único endpoint serve vários fins: uma verificação em linha enquanto um pagador revê um novo beneficiário, a verificação por lotes de um ficheiro de fornecedores e uma pré-verificação dentro de um fluxo de mandato SEPA Direct Debit. A RoxPay usa a VoP exatamente assim — incluindo como pré-verificação obrigatória antes de emitir o link de assinatura de um mandato SDD.