> ## 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 verificació de telèfon: OTP, SMS i WhatsApp

> Verifica telèfons amb OTP per SMS, WhatsApp, RCS i veu amb Didit. $0.02 per crida + operador, detecció d'operador i puntuació de risc.

La Verificació de telèfon de Didit ofereix un mètode fiable per verificar els números de telèfon dels usuaris mitjançant codis d'un sol ús (OTP). Aquesta funcionalitat afegeix una capa de seguretat essencial al teu procés de verificació d'identitat, garantint que la informació de contacte de l'usuari sigui legítima.

Prompt d'integració de la verificació de telèfon
        Copia el prompt al porta-retalls



      
      

\<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>



      
      

Enganxa a

A la lliçó de l'Academy sobre com interpretar el resultat d'una verificació, el capítol del minut 8:08 tracta la verificació de telèfon i la detecció de duplicats.[Verificació de telèfon i duplicats — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![Diagrama del flux de verificació de telèfon](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)## Com funcionaLa nostra solució de Verificació de telèfon ofereix una validació exhaustiva del número de telèfon mitjançant un procés senzill i fàcil d'utilitzar. El sistema combina la verificació per OTP amb una avaluació avançada del risc per oferir una verificació de telèfon fiable a gran escala.**1. Recollida del telèfon**El sistema recopila de manera segura la informació següent:| Dades recopilades | Detalls |
| - | - |
| **Número de telèfon** | Si no s'ha proporcionat durant la creació de la sessió, l'usuari introdueix el seu número de telèfon en format internacional. Si s'ha proporcionat, l'usuari ha de verificar el número emplenat prèviament. |
| **Codi de país** | Se suggereix automàticament en funció de la ubicació de la IP o de la selecció de l'usuari. |
| **Tipus d'operador** | Es detecta si és un número de mòbil o de línia fixa. |**2. Generació i lliurament de l'OTP**El nostre sistema de verificació:- Genera un codi d'un sol ús segur i amb temps limitat
- Lliura el codi per SMS al número proporcionat
- Garanteix un lliurament optimitzat mitjançant integracions amb múltiples operadors
- Ofereix opcions alternatives davant d'incidències en el lliurament**3. Validació del codi**L'usuari completa la verificació:- Introduint el codi rebut a la interfície de verificació
- Enviant-lo dins del termini configurat (habitualment entre 5 i 10 minuts)
- Sol·licitant un nou codi si és necessari (amb el límit de freqüència corresponent)**4. Avaluació del risc**El nostre sistema duu a terme comprovacions avançades:| Comprovació | Descripció |
| - | - |
| **Format i operador** | Verifica el format del número de telèfon i la informació de l'operador. |
| **Números d'un sol ús** | Comprova amb bases de dades de números virtuals o d'un sol ús coneguts. |
| **Detecció de canvi de SIM** | Identifica possibles riscos de canvi de SIM. |
| **Patrons d'activitat** | Detecta patrons d'activitat sospitosos. |
| **Dades històriques** | Contrasta amb dades històriques de verificació. |**5. Lliurament del resultat**Accedeix als resultats de la verificació a través de múltiples canals:| Canal | Descripció |
| - | - |
| **Tauler** | Actualitzacions en temps real al tauler. |
| **Webhooks** | Notificacions instantànies de webhook. |
| **API** | Integració amb una API RESTful. |
| **Informes** | Informes complets amb informació detallada de la verificació. |## Funcionalitats de la verificacióEl nostre servei de Verificació de telèfon ofereix diverses funcionalitats clau per millorar el teu procés de verificació:#### Verificació OTP- **Generació de codis segura**: Codis d'un sol ús generats aleatòriament
- **Lliurament per SMS**: Lliurament ràpid i fiable a dispositius mòbils
- **Temps d'espera configurables**: Estableix temps de caducitat segons els teus requisits de seguretat
- **Opcions de reintent**: Permet als usuaris sol·licitar nous codis amb un límit de freqüència adequat
- **Codis de marca**: Els codis per SMS inclouen el nom de la teva marca en lloc d'enviar un missatge genèric, sense cap cost addicional. Consulta [Missatges de verificació de marca](#missatges-de-verificació-de-marca).
- **El teu propi número de WhatsApp**: Els codis de WhatsApp poden provenir del teu propi número de WhatsApp Business. Consulta [Enviar codis de WhatsApp des del teu propi número](#enviar-codis-de-whatsapp-des-del-teu-propi-número).#### Missatges de verificació de marcaEls codis de verificació per SMS poden incloure el nom de la teva marca perquè els teus usuaris reconeguin el missatge com a teu:> 123456 és el teu codi de verificació per a **Acme Bank**Només el nom és personalitzable.
La resta de la redacció és un text estàndard registrat amb operadors mòbils a cada país, fet que evita que els codis es filtrin com a correu brossa, i es tradueix a l'idioma del destinatari.
La marca és gratuïta: un codi de marca costa el mateix que un sense marca.**Defineix el teu nom de remitent d'SMS** a la Business Console, a **Verificació de telèfon → Configuració** d'un flux de treball o a **Marca blanca → SMS**.
Pertany a la teva aplicació, no a un únic flux de treball: signa cada codi per SMS que envia l'aplicació, en tots els fluxos de treball i mitjançant l'API independent, amb personalització de marca blanca o sense.**Quin nom porta un codi**: guanya la primera coincidència:1) `options.sms_sender_name` a [`POST /v3/phone/send/`](https://docs.didit.me/ca/standalone-apis/phone-send), per a aquest codi en concret.
2) El nom de remitent d'SMS de la teva aplicació.
3) Només en enviaments de marca blanca (un flux de treball amb personalització de marca blanca o `options.use_white_label_customization: true` a l'API), el teu nom públic de marca blanca.
4) En cas contrari, el codi s'envia sense nom.Un nom de remitent utilitza d'1 a 30 caràcters: només lletres, dígits, espais i ' & - !, no només dígits, amb un sol espai entre paraules.
L'API rebutja qualsevol nom que no compleixi aquestes regles amb un error `400` abans d'enviar cap codi.- **Canals**: el nom s'afegeix als missatges SMS, incloent-hi els SMS enviats com a alternativa des d'un altre canal. Els codis de WhatsApp s'envien amb un missatge fix i no el porten; per mostrar-hi el nom de la teva empresa, [envia'ls des del teu propi número](#enviar-codis-de-whatsapp-des-del-teu-propi-número).
- **Canvis per dia**: cada aplicació pot començar a utilitzar fins a dos noms nous per dia (UTC), comptant tant noms de remitent nous com nous valors de `sms_sender_name`. A partir d'aquí, els codis mantenen el nom actual de l'aplicació fins l'endemà, i qualsevol nou nom per sol·licitud s'envia amb el nom de l'aplicació. Un nom utilitzat anteriorment no torna a comptar.
- **Prioritat al lliurament**: un problema de marca mai atura l'enviament d'un codi. Si un nom no es pot aplicar, el codi s'envia amb el nom de l'aplicació o sense nom.#### Escriu el teu propi text d'SMS i ID del remitentPots substituir el text dels teus codis per SMS i el remitent que veuen els teus usuaris.
Configura tots dos a la Business Console a **Marca blanca → SMS**.
Pertanyen a la teva aplicació, com el nom de remitent d'SMS, i s'apliquen a cada codi per SMS que envia, en tots els fluxos de treball i mitjançant l'API independent.**El teu propi text** es redacta per a cada idioma.
Un codi s'envia amb el teu text quan n'hagis escrit un per a l'idioma en què s'envia el codi; la resta d'idiomes mantenen el text traduït de Didit.
Fes servir `{code}` per al codi i, opcionalment, `{brand}` per al teu nom de remitent d'SMS, per exemple `Acme: {code} is your login code for {brand}.`Un text ha de:- contenir `{code}` exactament una vegada, i cap altre marcador de posició a part de `{code}` i `{brand}`;
- no contenir enllaços: els operadors bloquegen els codis de verificació que en porten;
- cabre en un sol SMS amb un codi de 8 dígits i un nom de 30 caràcters: fins a 160 caràcters, o 70 quan utilitza caràcters que no pertanyen a l'alfabet llatí bàsic (per exemple ciríl·lic, àrab o emojis).**El teu propi ID del remitent** utilitza de 3 a 11 lletres, dígits i espais, no només dígits, per exemple `AcmeBank`.
S'utilitza als països on Didit habilita ID del remitent personalitzats; aquests són els països on els operadors accepten un nom de remitent sense registrar-lo prèviament; a la resta de llocs, els teus codis s'envien amb el remitent de Didit.
Posa't en contacte amb el servei de suport per sol·licitar que s'habiliti un país que requereixi el registre del remitent.- **Prioritat al lliurament**: quan un codi es reenvia per una ruta que no admet el teu text o el teu ID del remitent, s'envia amb el text de Didit, signat amb el teu nom de remitent d'SMS i el remitent de Didit, de manera que el codi sempre arriba.#### Enviar codis de WhatsApp des del teu propi númeroPer defecte, els codis de WhatsApp provenen del número de WhatsApp Business de Didit.
En lloc d'això, pots connectar el teu propi número de WhatsApp Business perquè els teus usuaris rebin els codis amb el nom i el número de la teva empresa.**Connecta un número** a la Business Console, a **Verificació de telèfon → Configuració → Número de WhatsApp** d'un flux de treball, i selecciona **Connectar número de WhatsApp**.
S'obrirà una finestra d'inici de sessió: inicia sessió al compte comercial que gestiona el teu número de WhatsApp Business i, a continuació, tria el compte de WhatsApp Business i el número des del qual enviar.
A continuació, Didit registra el número per a l'enviament i crea el seu missatge de verificació.
Per editar-lo cal permís per editar la personalització, com passa amb el nom de remitent d'SMS.El número pertany a la teva aplicació, no a un únic flux de treball: un cop connectat, envia cada codi de WhatsApp que envia l'aplicació, en tots els fluxos de treball i mitjançant l'API independent.- **Aprovació**: el nou missatge de verificació requereix aprovació abans que el número pugui enviar codis, normalment en pocs minuts. Fins aleshores, la targeta mostra el número com a pendent d'aprovació, i mentrestant els codis continuen enviant-se des del número de Didit.
- **Text del missatge**: els missatges de verificació a WhatsApp utilitzen un text estàndard en l'idioma del teu usuari: el codi, una nota de seguretat i un botó de còpia. El text no es pot editar, però el remitent és la teva empresa.
- **Lliurament**: si un codi no es pot lliurar per WhatsApp, s'envia per SMS, signat amb el teu nom de remitent d'SMS.
- **Facturació**: els missatges que envia el teu número es facturen al teu compte de WhatsApp Business, de manera que Didit només cobra la seva tarifa de verificació (\$0.02) per aquests codis. Els codis enviats per SMS es facturen com de costum.
- **Requereix atenció**: si el número ja no pot enviar missatges (per exemple, si se li ha revocat l'accés al teu compte comercial), els codis tornen a sortir del número de Didit i la targeta et demana que tornis a connectar el número.
- **Desconnectar** en qualsevol moment des de la mateixa targeta. Els codis tornen a sortir del número de Didit; el número i el seu missatge de verificació romanen al teu compte de WhatsApp Business.#### Anàlisi del número de telèfon- **Validació de format**: assegura que el número de telèfon segueixi el format internacional correcte
- **Detecció de l'operador**: identifica el proveïdor de telecomunicacions associat al número
- **Tipus de número**: distingeix entre números mòbils, fixos i VoIP
- **Validació de país**: verifica que el número de telèfon coincideixi amb el format esperat del país#### Avaluació de riscos- **Detecció de números d'un sol ús**: identifica números temporals utilitzats per evitar la traçabilitat
- **Identificació de números virtuals**: marca els números que puguin ser virtuals o basats en VoIP
- **Monitoratge de l'activitat**: rastreja patrons sospitosos al llarg dels intents de verificació
- **Comprovació de llistes de bloqueig**: comprova amb llistes internes de números utilitzats de manera indeguda anteriorment## PreusLa verificació de telèfon es cobra **per missatge enviat** amb uns preus transparents de pagament per ús:| Component | Cost |
| - | - |
| **Tarifa de Didit** | \$0.02 per verificació |
| **Tarifa de l'operador** | Varia segons el país i el canal |
| **Total** | \$0.02 + tarifa de l'operador |El descompte del teu pla s'aplica només a la tarifa de Didit de \$0.02; la tarifa de l'operador es repercuteix a preu de cost i mai es descompta. Consulta [Descomptes](https://docs.didit.me/ca/getting-started/pricing.md#descomptes).Admetem múltiples canals de lliurament amb diferents preus (la disponibilitat varia segons el país):| Canal | Descripció |
| - | - |
| **SMS** | Lliurament tradicional de missatges de text |
| **WhatsApp** | Lliurament mitjançant missatgeria de WhatsApp |
| **Telegram** | Lliurament mitjançant missatgeria de Telegram |
| **RCS** | Missatgeria de Rich Communication Services |
| **Viber** | Lliurament mitjançant missatgeria de Viber |
| **Zalo** | Lliurament mitjançant missatgeria de Zalo (Vietnam) |> [!NOTE]
>
> Només pagues quan s'envia un missatge. Si l'usuari abandona abans del lliurament de l'OTP, no se't cobra.→ [Preus de la verificació de telèfon](https://docs.didit.me/ca/getting-started/phone-verification-pricing.md)


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