> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de verificação de telefone: OTP, SMS e WhatsApp

> Verifique números com OTP por SMS, WhatsApp, Telegram, RCS e voz na Didit. $0.02/chamada + operadora, deteção de operadora e pontuação de risco.

A Verificação de telefone da Didit oferece um método fiável para verificar os números de telefone dos utilizadores através de códigos de utilização única (OTP). Esta funcionalidade adiciona uma camada essencial de segurança ao seu processo de verificação de identidade, garantindo informações de contacto legítimas dos utilizadores.

Prompt de integração da Verificação de telefone
        Copiar o prompt para a área de transferência



      
      

\<pre>

\````# Goal
Integrate Didit Phone Verification (OTP send + check + carrier/risk lookup) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow — the SDK collects the number and OTP for you.

1\. Add the PHONE feature to the workflow (Business Console or POST /v3/workflows/). Configure risk actions: duplicated_phone_number_action, disposable_number_action, voip_number_action.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `phone_verifications[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server, OTP pair)
Two endpoints, paired by phone_number.

Step 1 — send the code:
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/send/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"options": {
  "code_size": 6,
  "preferred_channel": "whatsapp",
  "locale": "en-US"
},
"vendor_data": "user-1234"
}'
\```
Channels: `whatsapp` (default), `sms`, `telegram`, `voice` — delivery falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.
Branding: SMS codes carry your app's SMS sender name ("123456 is your verification code for Acme Bank") on every send, at no extra cost; set it in the Business Console. Pass `options.sms_sender_name` to sign one code with another name (1 to 30 characters). WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console to send them under your business name.

Step 2 — check the code (user types it into your UI):
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/check/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"code": "123456",
"voip_number_action": "DECLINE"
}'
\```
Each session accepts **up to 3** code-entry attempts. The check response includes the full phone metadata (carrier, line_type, disposable, voip, ported).

\# Status enum (per phone_verifications[].status / phone.status)
"Not Started" | "In Progress" | "Approved" | "Declined" | "Failed" | "Expired or Not Found" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.PHONE)
warnings[] risk codes include:
DUPLICATED_PHONE_NUMBER, DISPOSABLE_NUMBER, VOIP_NUMBER, INVALID_PHONE_NUMBER, OTP_DELIVERY_FAILED, OTP_MAX_ATTEMPTS_REACHED, OTP_EXPIRED, PHONE_NUMBER_BLOCKED.
Full catalogue: /core-technology/phone-verification/warnings-phone-verification.

\# Failure modes to handle
\- HTTP 400 — non-E.164 phone_number on /send/.
\- send response status="Blocked" with reason="spam" — anti-abuse block; no code sent, no charge.
\- check response status="Failed" — wrong code, attempts remaining; re-prompt.
\- check response status="Declined" — third failed attempt; restart with /v3/phone/send/.
\- check response status="Expired or Not Found" — outside the 5-minute window or no pending session for that number; restart.

\# See also
\- Canonical schema: /reference/data-models#phone-verification
\- Per-feature report: /core-technology/phone-verification/report-phone-verification
\- Risk catalogue: /core-technology/phone-verification/warnings-phone-verification
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Colar em

Na lição da Academy sobre como ler um resultado de verificação, o capítulo 8:08 aborda a verificação de telefone e a deteção de duplicados.[Verificação de telefone e duplicados — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![Diagrama do fluxo de verificação de telefone](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=6c12863ce97e5ad6a11757b598918932)## Como funcionaA nossa solução de Verificação de telefone oferece uma validação abrangente de números de telefone através de um processo simples e intuitivo. O sistema combina a verificação por OTP com uma avaliação de risco avançada para fornecer uma verificação de telefone fiável em grande escala.**1. Recolha do número de telefone**O sistema recolhe de forma segura as seguintes informações:| Dados recolhidos | Detalhes |
| - | - |
| **Número de telefone** | Se não for fornecido durante a criação da sessão, o utilizador introduz o seu número de telefone em formato internacional. Se fornecido, o utilizador deve verificar o número pré-preenchido. |
| **Código do país** | Sugerido automaticamente com base na localização do IP ou na seleção do utilizador. |
| **Tipo de operadora** | Deteta se o número é móvel ou fixo. |**2. Geração e entrega do OTP**O nosso sistema de verificação:- Gera um código de utilização única seguro e com validade temporal limitada
- Entrega o código por SMS para o número fornecido
- Garante uma entrega otimizada através de múltiplas integrações com operadoras
- Disponibiliza opções alternativas para resolver dificuldades na entrega**3. Validação do código**O utilizador conclui a verificação ao:- Introduzir o código recebido na interface de verificação
- Submeter dentro do intervalo de tempo configurado (normalmente 5–10 minutos)
- Solicitar um novo código, se necessário (com o devido limite de pedidos)**4. Avaliação de risco**O nosso sistema realiza verificações avançadas:| Verificação | Descrição |
| - | - |
| **Formato e operadora** | Verifica o formato do número de telefone e as informações da operadora. |
| **Números descartáveis** | Compara com bases de dados de números descartáveis/virtuais conhecidos. |
| **Deteção de SIM swap** | Identifica potenciais riscos de troca de SIM (SIM swap). |
| **Padrões de atividade** | Deteta padrões de atividade suspeita. |
| **Dados históricos** | Cruza com dados históricos de verificação. |**5. Entrega de resultados**Aceda aos resultados da verificação através de múltiplos canais:| Canal | Descrição |
| - | - |
| **Painel** | Atualizações em tempo real no painel. |
| **Webhooks** | Notificações instantâneas por webhook. |
| **API** | Integração via API RESTful. |
| **Relatórios** | Relatórios abrangentes com informações detalhadas da verificação. |## Funcionalidades de verificaçãoO nosso serviço de Verificação de telefone oferece várias funcionalidades-chave para melhorar o seu processo de verificação:#### Verificação OTP- **Geração segura de códigos**: Códigos de utilização única gerados aleatoriamente
- **Entrega por SMS**: Entrega rápida e fiável em dispositivos móveis
- **Tempos limite configuráveis**: Defina tempos de expiração com base nos seus requisitos de segurança
- **Opções de nova tentativa**: Permita que os utilizadores peçam novos códigos com limites de pedidos adequados
- **Códigos com a sua marca**: Os códigos por SMS identificam a sua marca em vez de enviarem uma mensagem genérica, sem custos adicionais. Consulte [Mensagens de verificação com a sua marca](#mensagens-de-verificação-com-a-sua-marca).
- **O seu próprio número de WhatsApp**: Os códigos de WhatsApp podem ser enviados a partir do seu próprio número do WhatsApp Business. Consulte [Enviar códigos de WhatsApp a partir do seu próprio número](#enviar-códigos-de-whatsapp-a-partir-do-seu-próprio-número).#### Mensagens de verificação com a sua marcaOs códigos de verificação por SMS podem identificar a sua marca, para que os seus utilizadores reconheçam a mensagem como sendo sua:> 123456 é o seu código de verificação para **Acme Bank**Apenas o nome é personalizável.
O restante texto é uma mensagem padrão registada junto dos operadores móveis em cada país, o que impede que os códigos sejam filtrados como spam, e é traduzido para o idioma do destinatário.
A inclusão da marca é gratuita: um código com a marca custa o mesmo que um código sem marca.**Defina o seu nome de remetente de SMS** na Business Console, em **Phone Verification → Settings** de um fluxo ou em **White Label → SMS**.
Pertence à sua aplicação, não a um único fluxo: assina todos os códigos por SMS que a aplicação envia, em todos os fluxos e através da API autónoma, com ou sem personalização de marca branca.**Que nome é apresentado num código**, a primeira correspondência prevalece:1) `options.sms_sender_name` em [`POST /v3/phone/send/`](https://docs.didit.me/pt/standalone-apis/phone-send), para esse código específico.
2) O nome de remetente de SMS da sua aplicação.
3) Apenas em envios de marca branca (um fluxo com personalização de marca branca ou `options.use_white_label_customization: true` na API), o seu nome público de marca branca.
4) Caso contrário, o código é enviado sem nome.Um nome de remetente utiliza entre 1 e 30 carateres: apenas letras, dígitos, espaços e ' & - !, não apenas dígitos, com espaços simples entre palavras.
A API rejeita com `400` qualquer nome fora destas regras antes de qualquer código ser enviado.- **Canais**: o nome é adicionado às mensagens SMS, incluindo um SMS enviado como alternativa a partir de outro canal. Os códigos de WhatsApp são enviados com uma mensagem fixa e não o incluem; para que tenham o nome da sua empresa, [envie-os a partir do seu próprio número](#enviar-códigos-de-whatsapp-a-partir-do-seu-próprio-número).
- **Alterações por dia**: cada aplicação pode começar a utilizar até dois novos nomes por dia (UTC), contabilizando tanto novos nomes de remetente como novos valores de `sms_sender_name`. Depois disso, os códigos mantêm o nome atual da aplicação até ao dia seguinte, e um novo nome por pedido é enviado com o nome da aplicação. Um nome que já tenha utilizado anteriormente não volta a contar.
- **A entrega em primeiro lugar**: um problema com a marca nunca impede o envio de um código. Se um nome não puder ser aplicado, o código é enviado com o nome da aplicação ou sem qualquer nome.#### Escreva o seu próprio texto de SMS e ID do remetentePode substituir o texto dos seus códigos por SMS e o remetente que os seus utilizadores veem.
Defina ambos na Business Console em **White Label → SMS**.
Pertencem à sua aplicação, tal como o nome de remetente de SMS, e aplicam-se a todos os códigos por SMS que esta envia, em todos os fluxos e através da API autónoma.**O seu próprio texto** é definido por idioma.
Um código é enviado com o seu texto se tiver escrito um para o idioma em que o código é enviado; todos os outros idiomas mantêm o texto traduzido da Didit.
Utilize `{code}` para o código e, opcionalmente, `{brand}` para o seu nome de remetente de SMS, por exemplo `Acme: {code} is your login code for {brand}.`O texto deve:- conter `{code}` exatamente uma vez e nenhum outro marcador de posição além de `{code}` e `{brand}`;
- não conter hiperligações: os operadores bloqueiam códigos de verificação que as contenham;
- caber num único SMS com um código de 8 dígitos e um nome de 30 carateres: até 160 carateres, ou 70 quando utilizar carateres fora do alfabeto latino básico (por exemplo, cirílico, árabe ou emojis).**O seu próprio ID do remetente** utiliza entre 3 e 11 letras, dígitos e espaços, não apenas dígitos, por exemplo `AcmeBank`.
É utilizado nos países onde a Didit permite IDs de remetente personalizados, que são os países cujos operadores aceitam um nome de remetente sem necessidade de o registar previamente; em todos os restantes casos, os seus códigos são enviados com o remetente da Didit.
Contacte o suporte para solicitar um país que exija o registo prévio do remetente.- **A entrega em primeiro lugar**: quando um código é reenviado por uma rota que não suporta o seu texto ou o seu ID do remetente, é enviado com o texto da Didit, assinado com o seu nome de remetente de SMS e o remetente da Didit, para que o código chegue sempre ao destino.#### Enviar códigos de WhatsApp a partir do seu próprio númeroPor predefinição, os códigos de WhatsApp são enviados a partir do número do WhatsApp Business da Didit.
Em alternativa, pode associar o seu próprio número do WhatsApp Business, para que os seus utilizadores recebam os códigos com o nome e o número da sua empresa.**Associe um número** na Business Console, em **Phone Verification → Settings → WhatsApp number** de um fluxo, e selecione **Connect WhatsApp number**.
Uma janela de início de sessão será aberta: inicie sessão na conta comercial que gere o seu número do WhatsApp Business e, em seguida, escolha a conta do WhatsApp Business e o número a partir do qual pretende enviar.
A Didit regista então o número para envio e cria a respetiva mensagem de verificação.
A edição requer permissão para editar a personalização, tal como o nome de remetente de SMS.O número pertence à sua aplicação, não a um único fluxo: depois de associado, envia todos os códigos de WhatsApp que a aplicação envia, em todos os fluxos e através da API autónoma.- **Aprovação**: a nova mensagem de verificação requer aprovação antes de o número poder enviar códigos, o que normalmente demora alguns minutos. Até lá, o cartão mostra o número como estando a aguardar aprovação, e os códigos continuam a ser enviados a partir do número da Didit durante esse período.
- **Texto da mensagem**: as mensagens de verificação no WhatsApp utilizam um texto padrão no idioma do seu utilizador: o código, uma nota de segurança e um botão para copiar. O texto não pode ser editado, mas o remetente é a sua empresa.
- **Entrega**: se não for possível entregar um código pelo WhatsApp, este é enviado por SMS, assinado com o seu nome de remetente de SMS.
- **Faturação**: as mensagens que o seu número envia são faturadas à sua conta do WhatsApp Business, pelo que a Didit cobra apenas a sua taxa de verificação (\$0.02) por esses códigos. Os códigos enviados por SMS são faturados normalmente.
- **Requer atenção**: se o número deixar de conseguir enviar (por exemplo, se o seu acesso tiver sido removido da sua conta comercial), os códigos voltam a ser enviados a partir do número da Didit e o cartão solicita que associe o número novamente.
- **Desassocie-o** a qualquer momento a partir do mesmo cartão. Os códigos voltam a ser enviados a partir do número da Didit; o número e a sua mensagem de verificação permanecem na sua conta do WhatsApp Business.#### Análise do número de telefone- **Validação de formato**: Garanta que o número de telefone cumpre o formato internacional correto
- **Deteção de operadora**: Identifique o fornecedor de telecomunicações associado ao número
- **Tipo de número**: Distinga entre números móveis, fixos e VoIP
- **Validação de país**: Verifique se o número de telefone corresponde ao formato esperado para o país#### Avaliação de risco- **Deteção de números descartáveis**: Identifique números temporários utilizados para evitar a rastreabilidade
- **Identificação de números virtuais**: Sinalize números que possam ser virtuais ou baseados em VoIP
- **Monitorização da atividade**: Monitorize padrões suspeitos ao longo de várias tentativas de verificação
- **Verificação em lista de bloqueio**: Verifique em listas internas de números previamente utilizados de forma indevida## PreçosA verificação de telefone é cobrada **por mensagem enviada** com preços transparentes e pagamento por utilização:| Componente | Custo |
| - | - |
| **Taxa da Didit** | \$0.02 por verificação |
| **Taxa da operadora** | Varia consoante o país e o canal |
| **Total** | \$0.02 + taxa da operadora |O desconto do seu plano aplica-se apenas à taxa da Didit de \$0.02; a taxa da operadora é cobrada a preço de custo e nunca tem desconto. Consulte [Descontos](https://docs.didit.me/pt/getting-started/pricing.md#descontos).Suportamos múltiplos canais de entrega com preços distintos (a disponibilidade varia consoante o país):| Canal | Descrição |
| - | - |
| **SMS** | Entrega tradicional por mensagem de texto |
| **WhatsApp** | Entrega através de mensagens de WhatsApp |
| **Telegram** | Entrega através de mensagens de Telegram |
| **RCS** | Mensagens através de Rich Communication Services |
| **Viber** | Entrega através de mensagens de Viber |
| **Zalo** | Entrega através de mensagens de Zalo (Vietname) |> [!NOTE]
>
> Apenas paga quando uma mensagem é enviada. Se o utilizador abandonar antes da entrega do OTP, não lhe será cobrado qualquer valor.→ [Preços da Verificação de telefone](https://docs.didit.me/pt/getting-started/phone-verification-pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.