Verificar PIN de Seguridad

Verifica el PIN (o biometría, según verificationType). Para SESSION puede aprobar una sesión (presencia) temporal.

POST/auth/pin/verify

Verifica PIN o BIOMETRY según verificationType

📤 Respuesta

{
"code": 1016,
"message": "PIN verified successfully.",
"data": {
  "verified": true,
  "verifiedAt": "2025-01-20T14:45:00.000Z",
  "verificationType": "PIX_PAYMENT",
  "verificationUuid": "uuid-verification",
  "expiresAt": "2025-01-20T14:50:00.000Z",
  "message": "PIN verified for PIX_PAYMENT",
  "authMethod": "pin"
}
}

Headers

Header	Value
Authorization	Bearer `<JWT>`
Content-Type	application/json

Body

Campos comunes

Campo	Tipo	Requerido	Descripción
verificationType	"SESSION" \| "PIX_PAYMENT" \| "BIOMETRY" \| "WITHDRAWAL" \| "CARD_VIEW"	Sí	Tipo de verificación
pin	string	Condicional	Requerido cuando `verificationType` NO es `BIOMETRY`. Debe ser exactamente 6 dígitos

Campos por tipo

SESSION

Campo	Tipo	Requerido	Descripción
wssReauthId	string	Sí	Requerido para `SESSION` (cuando se verifica por PIN)

Nota: el backend valida que exista y sea válido.

PIX_PAYMENT / WITHDRAWAL / CARD_VIEW

Campo	Tipo	Requerido	Descripción
verificationUuid	string	Sí	UUID requerido para este tipo de verificación

BIOMETRY

Campo	Tipo	Requerido	Descripción
deviceId	string	Sí	Identificador del dispositivo
challengeId	string	Sí	ID del challenge
challenge	string	Sí	Challenge
signature	string	Sí	Firma
algorithm	"P-256"	Sí	Algoritmo requerido

Opcional:

Campo	Tipo	Requerido	Descripción
wssReauthId	string	No	Puede incluirse para escenarios de reautenticación

Response (200)

Verificación exitosa

code 1016 — PIN verified successfully.

Caso A — SESSION (sesión aprobada)

{
  "code": 1016,
  "message": "PIN verified successfully.",
  "data": {
    "verified": true,
    "verifiedAt": "2025-01-20T14:45:00.000Z",
    "sessionApproved": true,
    "sessionId": "sid-from-jwt",
    "verificationType": "SESSION",
    "verificationUuid": "value",
    "expiresAt": "2025-01-20T14:50:00.000Z",
    "presenceDuration": "5 minutes",
    "authMethod": "pin",
    "wssReauthId": "wss-reauth-id"
  }
}

Caso B — Tipos PIX_PAYMENT / WITHDRAWAL / CARD_VIEW

{
  "code": 1016,
  "message": "PIN verified successfully.",
  "data": {
    "verified": true,
    "verifiedAt": "2025-01-20T14:45:00.000Z",
    "verificationType": "PIX_PAYMENT",
    "verificationUuid": "uuid-verification",
    "expiresAt": "2025-01-20T14:50:00.000Z",
    "message": "PIN verified for PIX_PAYMENT",
    "authMethod": "pin"
  }
}

Caso C — BIOMETRY

{
  "code": 1016,
  "message": "PIN verified successfully.",
  "data": {
    "verified": true,
    "verifiedAt": "2025-01-20T14:45:00.000Z",
    "verificationType": "BIOMETRY",
    "verificationUuid": "value",
    "expiresAt": "2025-01-20T14:50:00.000Z",
    "authMethod": "biometric"
  }
}

Errores

No autorizado

Casos reales de HTTP 401.

JWT inválido / ausente

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Sesión revocada (cuando el JWT incluye `sid`)

{
  "code": 4032,
  "message": "Session has been revoked. Please login again."
}

WSS re-auth no pertenece al usuario actual

{
  "code": 4033,
  "message": "WSS re-auth ID does not belong to current user"
}

Bad Request

Casos reales de HTTP 400.

verificationType inválido

{
  "code": 4006,
  "message": "Invalid verification type. Must be SESSION, PIX_PAYMENT, BIOMETRY, WITHDRAWAL, or CARD_VIEW"
}

PIN inválido (cuando aplica)

{
  "code": 4006,
  "message": "PIN must be exactly 6 digits"
}

verificationUuid requerido (PIX_PAYMENT / WITHDRAWAL / CARD_VIEW)

{
  "code": 4006,
  "message": "Verification UUID is required for PIX_PAYMENT. Please call /pin/verification/request first."
}

verification UUID inválido o expirado (no SESSION)

{
  "code": 4031,
  "message": "Invalid or expired verification UUID. Please request a new verification."
}

WSS re-auth inválido o expirado

{
  "code": 4031,
  "message": "Invalid or expired WSS re-authentication ID"
}

SESSION requiere WSS re-auth ID (cuando se verifica por PIN)

{
  "code": 4031,
  "message": "WSS re-authentication ID is required for SESSION verification. Connect to WSS first."
}

Forbidden

Caso real de HTTP 403.

{
  "code": 5012,
  "message": "Device not registered or revoked"
}

Errores de biometría

Errores reales que pueden ocurrir en verificationType: "BIOMETRY".

{
  "code": 5011,
  "message": "Challenge expired or not found"
}

{
  "code": 5011,
  "message": "Challenge expired"
}

{
  "code": 5011,
  "message": "Challenge already used"
}

{
  "code": 5010,
  "message": "Invalid signature"
}

{
  "code": 5010,
  "message": "Signature verification failed"
}

Usuario no encontrado

HTTP 404 — code 4001.

{
  "code": 4001,
  "message": "User not found."
}

Error interno

HTTP 500 — code 5001.

{
  "code": 5001,
  "message": "Failed to save user to the database.",
  "details": "..."
}

Ejemplo (cURL)

Verificación para PIX_PAYMENT

curl -X POST 'https://api.swapbits.co/auth/pin/verify' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -d '{
    "verificationType": "PIX_PAYMENT",
    "verificationUuid": "uuid-verification",
    "pin": "123456"
  }'

⚡ Quick Test

POSThttps://api.swapbits.co/auth/pin/verify

curl -X POST 'https://api.swapbits.co/auth/pin/verify' \
  -H 'Content-Type: application/json' \
  -d '{
"verificationType": "PIX_PAYMENT",
"verificationUuid": "uuid-verification",
"pin": "123456"
}'

📤 Respuesta

Headers​

Body​

Campos comunes​

Campos por tipo​

SESSION​

PIX_PAYMENT / WITHDRAWAL / CARD_VIEW​

BIOMETRY​

Response (200)​

Verificación exitosa

Caso A — SESSION (sesión aprobada)​

Caso B — Tipos PIX_PAYMENT / WITHDRAWAL / CARD_VIEW​

Caso C — BIOMETRY​

Errores​