Tu primera verificación

Con tu API key creada en el entorno que te corresponde, esta es la única llamada que necesitas para empezar. El ejemplo usa pre-official-integration (sandbox-api.fraudeg.com). En producción cambia el host a https://api.fraudeg.com/api; el path es el mismo. No existe /verifications/sandbox.

Request

curl -X POST https://sandbox-api.fraudeg.com/api/v1/verifications \
  -H "X-Api-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ref": "CUS-48213",
    "language": "es",
    "callback_url": "https://tu-app.example.com/kyc/volver"
  }'

Campo	Obligatorio	Detalle
`customer_ref`	No, pero mándalo	Tu identificador de la persona. Máximo 128 caracteres
`template_code`	No	Qué flujo correr. Sin él se usa el que tengas por defecto
`language`	No	ISO 639-1, para las pantallas que ve la persona
`callback_url`	No	A dónde vuelve la persona al terminar. `https`, o `http` en `localhost`

La llamada requiere el scope KYC_WRITE. Manda siempre customer_ref. Sin él generamos uno, y entonces la verificación no se puede unir a tu propio registro. Además es lo que hace barato reintentar: mientras haya una verificación en curso para esa referencia, una segunda llamada te devuelve la misma, no cobra de nuevo, y te da una url para seguir donde la persona iba.

Respuesta

{
  "data": {
    "id": 4821,
    "customer_ref": "CUS-48213",
    "session_token": "…",
    "url": "https://…",
    "status": "PENDING"
  },
  "timestamp": "2026-09-13T14:02:11",
  "status": "CREATED"
}

Con esta respuesta haces exactamente dos cosas:

Guardas id en tu registro.
Mandas a la persona a url, o se la entregas a tu página para que la abra.

session_token es una credencial. No lo registres en logs, no lo guardes y no lo pongas en una URL que la persona pueda compartir. Si tu framework serializa respuestas enteras a los logs, excluye esta.

Mientras la persona se verifica

No necesitas preguntar nada: la decisión llega a tu backend por webhook. Si quieres consultar el estado igualmente —para una pantalla interna, o para reconciliar— usa:

curl https://sandbox-api.fraudeg.com/api/v1/verifications/4821 \
  -H "X-Api-Key: tu_api_key"

Esa lectura requiere el scope KYC_READ. Una key con solo ese scope no puede crear nada, que es lo que conviene darle a un proceso que únicamente reconcilia.

Probando desde tu máquina

Las dos URLs que nos das las alcanzan cosas distintas, y solo una necesita un túnel.

	Quién hace la petición	En localhost
`callback_url`	El navegador de la persona	Funciona. `http://localhost:3000/kyc/volver` se acepta en todos los entornos
Tu endpoint de webhook	Nuestros servidores	No te alcanzan. Usa un túnel y registra la URL `https` que te dé

Siguiente paso

Decisiones de identidad: qué significa cada estado y qué hacer con él.

Inicio

Transacciones: conceptos

Transacciones: integrar

Identidad

Referencia

Entornos

Tu primera verificación

Request

Respuesta

Mientras la persona se verifica

Probando desde tu máquina

Siguiente paso

​Request

​Respuesta

​Mientras la persona se verifica

​Probando desde tu máquina

​Siguiente paso

Request

Respuesta

Mientras la persona se verifica

Probando desde tu máquina

Siguiente paso