Referência API

Documentação API Verification of Payee

Autenticação, o endpoint de verificação, payloads de pedido e resposta, códigos de correspondência do esquema SEPA e tratamento de erros — tudo o que um programador precisa para integrar a verificação IBAN/nome, com exemplos JSON e cURL prontos a copiar.

POST {BASE_URL}/vop/v1/verify
Autenticação
Bearer token (OAuth 2.0)
Formato
application/json

O URL base e as credenciais API são fornecidos no onboarding — contacte-nos para as obter.

A API Verification of Payee é um único endpoint REST autenticado: envia em POST um nome de beneficiário e um IBAN e recebe um resultado de correspondência padronizado em tempo real. Os exemplos abaixo são ilustrativos; o seu URL base e credenciais exatas são emitidos durante o onboarding.

Autenticação

Cada pedido é autenticado com um bearer token sobre HTTPS. Envie o token no cabeçalho Authorization; os tokens são emitidos por ambiente (sandbox e produção).

As mesmas credenciais também desbloqueiam o painel RoxBusiness, onde pode executar verificações pontuais sem escrever código.

Cabeçalhos HTTP 
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Pedido

Envie em POST um corpo JSON com o nome do beneficiário e o IBAN. Para pessoas coletivas pode também enviar um identificador de organização (p. ex. uma Partita IVA / Codice Fiscale italianos) e um external_id opcional para a reconciliação.

Corpo do pedido

Campo Tipo Obrigatório Descrição
name string Obrigatório Nome do beneficiário a verificar, tal como o pagador o inseriu.
iban string Obrigatório IBAN de destino (validado quanto a formato e checksum antes da chamada ao esquema).
account_type enum Opcional NATURAL_PERSON ou LEGAL_PERSON. Ajuda o banco respondente a comparar corretamente.
organisation_id string Opcional Número de IVA / código fiscal para pessoas coletivas (p. ex. Partita IVA). Verificado face ao titular registado.
external_id string Opcional O seu próprio id de referência, devolvido na resposta para a reconciliação.
Corpo do pedido 
{
  "name": "ACME Trading S.r.l.",
  "iban": "IT60X0542811101000000123456",
  "account_type": "LEGAL_PERSON",
  "organisation_id": "IT01524770524",
  "external_id": "invoice-2025-00842"
}
cURL 
curl -X POST "$BASE_URL/vop/v1/verify" \
  -H "Authorization: Bearer $ROXPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Trading S.r.l.",
    "iban": "IT60X0542811101000000123456",
    "account_type": "LEGAL_PERSON",
    "organisation_id": "IT01524770524",
    "external_id": "invoice-2025-00842"
  }'

Resposta

Uma resposta 200 devolve o resultado normalizado, o código de correspondência do esquema SEPA, o BIC do banco respondente e o tempo de processamento. Numa correspondência parcial, o nome verificado é devolvido em suggested_name.

Corpo da resposta

Campo Tipo Descrição
verification_id string Id único desta verificação, para a sua trilha de auditoria.
result enum MATCH, CLOSE_MATCH, NO_MATCH ou NOT_APPLICABLE.
scheme_code string O código do esquema SEPA VoP: MTCH, CMTC, NMTC ou NOAP.
suggested_name string Em CLOSE_MATCH, o nome verificado do titular a sugerir ao pagador.
responding_bic string BIC da instituição que respondeu à verificação.
processing_time_ms integer Tempo que o PSP respondente demorou, em milissegundos.
external_id string O seu id de referência, devolvido sem alterações.
200 OK 
{
  "verification_id": "vop_3f9a1c2e7b",
  "result": "CLOSE_MATCH",
  "scheme_code": "CMTC",
  "suggested_name": "ACME Trading SRL",
  "responding_bic": "BCITITMMXXX",
  "processing_time_ms": 412,
  "external_id": "invoice-2025-00842"
}

Códigos de resultado de correspondência

Cada resposta corresponde a um dos quatro códigos do esquema SEPA VoP. Ramifique em scheme_code para que a sua lógica se mantenha estável.

Código Resultado Significado Ação recomendada
MTCH MATCH O nome corresponde ao titular da conta. Prossiga com confiança.
CMTC CLOSE_MATCH Quase certo (p. ex. nome comercial vs firma). Mostre suggested_name; peça ao pagador para confirmar.
NMTC NO_MATCH O nome não pertence ao IBAN. Paragem firme — avise e bloqueie a aprovação automática.
NOAP NOT_APPLICABLE A verificação não pôde ser concluída. Informe o pagador; deixe-o decidir.

Tratamento de erros

NO_MATCH é um resultado 200 válido, não um erro — nunca o trate como uma falha de transporte. Os erros reais usam códigos de estado 4xx/5xx com um código de erro legível por máquina e um request_id para o suporte.

HTTP Código de erro Quando acontece
400 invalid_iban O IBAN falhou a validação de formato ou checksum.
400 missing_field Falta um campo obrigatório (name ou iban).
401 unauthorized Bearer token em falta ou inválido.
429 rate_limited Pedidos em excesso — aplique backoff e tente novamente.
503 scheme_unavailable O esquema VoP / o PSP respondente está temporariamente inacessível.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integre em quatro passos

Uma integração REST padrão que se encaixa no seu fluxo de pagamento existente.

  1. 1

    Obtenha credenciais

    Faça o onboarding e receba o seu bearer token e URL base para sandbox e produção.

  2. 2

    Chame /verify

    Envie em POST o nome do beneficiário e o IBAN, com external_id e organisation_id opcionais.

  3. 3

    Leia scheme_code

    Ramifique em MTCH / CMTC / NMTC / NOAP e guarde o verification_id.

  4. 4

    Aja na sua UI

    Mostre um sinal claro ao pagador, ou condicione uma remessa ou mandato ao resultado.

Referência API

FAQ para programadores

As primeiras perguntas das equipas de integração.

Um corpo JSON com name e iban (obrigatórios), mais account_type, organisation_id (IVA/código fiscal para pessoas coletivas) e o seu external_id opcionais. Veja o exemplo de pedido acima.

NO_MATCH (código de esquema NMTC) é uma resposta 200 válida, não um erro. Trate-a como uma paragem firme: avise o pagador, bloqueie a aprovação automática e exija uma nova verificação antes do envio.

Sim. Os tokens são emitidos por ambiente, por isso pode integrar e testar em sandbox antes de mudar o URL base para produção.

Sim — envie organisation_id com account_type LEGAL_PERSON. Ajuda quando o nome comercial difere do nome registado.

Envie o seu próprio external_id no pedido; é devolvido sem alterações, e cada resposta inclui também um verification_id único.

Continue a ler

A API Verification of Payee Visão geral, públicos e casos de uso. RoxPay Verification of Payee Como o serviço é entregue na RoxPay. Glossário Termos VoP, SEPA e códigos de esquema.

Obtenha as suas credenciais API

Faça o onboarding no esquema SEPA VoP com uma integração REST e entre em produção antes do seu prazo.

Falar com um especialista Sobre a API VoP