Verificación del SSN
Verificar el SSN/ITIN de una persona de EE. UU. contra registros de crédito para depositar con tarjeta y PayPal (nivel «SSN verificado»).
Una persona de EE. UU. (ficha CIP con us_person: true) puede contrastar su SSN/ITIN, junto con el nombre y la fecha de nacimiento de su documento verificado, contra registros de una agencia de crédito. Con el SSN verificado, la cuenta puede depositar con tarjeta (CARD) y PayPal (PAYPAL) sin ser VIP, tener TrustScore de 85 o ser cuenta empresa, con un tope combinado de $500 cada 30 días (ventana rodante, sobre lo cobrado). Es el método no documental del programa de identificación de clientes (CIP).
Requisitos para iniciar la verificación: cuenta GOLD vigente, identidad verificada con documento (KYC), us_person: true con el SSN/ITIN y la dirección de EE. UU. completos en la ficha CIP (PUT /user/update con el objeto cip). Máximo 3 intentos con respuesta del proveedor cada 30 días; un error del proveedor no consume intento. Cambiar el SSN de la ficha invalida la verificación.
Por ahora el nivel «SSN verificado» solo se aplica a las apps móviles (x-qvapay-client-platform: ios | android); desde la web o la API la verificación se puede hacer pero el depósito sigue las reglas de siempre.
GET /user/cip
Devuelve la ficha CIP y, en ssn_verification, el estado de la verificación.
curl https://api.qvapay.com/user/cip \
-H "Authorization: Bearer {token}"{
"us_person": true,
"ssn_itin_last4": "1234",
"addr_line1": "818 Leahy Cir", "addr_line2": "", "addr_city": "Dover", "addr_state": "DE", "addr_postal": "19901", "addr_country": "US",
"cip_status": "complete",
"has_document_hash": true,
"ssn_verification": {
"status": "none",
"verified_at": null,
"attempts_left": 3,
"attempts_max": 3,
"can_start": true,
"block_reason": null,
"message": null
}
}| Campo | Descripción |
|---|---|
status | none (sin verificar), verified, partial (última consulta con coincidencia parcial), no_match |
verified_at | Fecha de la verificación vigente, o null |
attempts_left / attempts_max | Intentos con respuesta que quedan en los últimos 30 días |
can_start | true si POST /user/cip/verify-ssn puede lanzarse ahora |
block_reason | Por qué no: GOLD_REQUIRED, KYC_REQUIRED, NOT_US_PERSON, SSN_MISSING, DOCUMENT_REQUIRED, ADDRESS_REQUIRED, ATTEMPTS_EXHAUSTED, SDN_BLOCKED, STAFF_ACCOUNT, UNAVAILABLE |
message | Texto para el usuario que explica block_reason |
POST /user/cip/verify-ssn
Lanza una consulta al proveedor con el nombre y la fecha de nacimiento del documento verificado y el SSN/ITIN de la ficha. No recibe parámetros. Límite: 3 llamadas cada 10 minutos por usuario.
curl -X POST https://api.qvapay.com/user/cip/verify-ssn \
-H "Authorization: Bearer {token}" \
-H "x-qvapay-client-platform: android"{ "result": "OK", "data": { "status": "verified", "verified_at": "2026-11-02T15:04:05.000Z", "attempts_left": 2 } }Errores
| HTTP | code | Significado |
|---|---|---|
403 | uno de block_reason | No puede iniciarse (el error trae el texto para el usuario) |
409 | SSN_NO_MATCH | Los datos no coinciden con los registros; consume un intento (attempts_left) |
409 | SSN_PARTIAL_MATCH | Coincidencia parcial (p. ej. nombre sí, fecha no); consume un intento |
429 | RATE_LIMITED | Demasiadas llamadas seguidas |
503 | SSN_VERIFY_UNAVAILABLE | El proveedor no respondió; no consume intento |
GET /user/deposit-eligibility
Qué métodos de depósito gateados (CARD, PAYPAL, BANK) aceptará POST /topup a esta cuenta desde este canal, y el cupo del nivel SSN. Úsalo para pintar los métodos: GET /coins/v2 es público y no sabe quién pregunta.
curl https://api.qvapay.com/user/deposit-eligibility \
-H "Authorization: Bearer {token}" \
-H "x-qvapay-client-platform: ios"{
"result": "OK",
"data": {
"channel": "ios",
"card": { "eligible": true, "tier": "ssn", "reason": null },
"paypal": { "eligible": true, "tier": "ssn", "reason": null },
"bank": { "eligible": false, "tier": null, "reason": "NOT_ELIGIBLE" },
"ssn_tier": { "enabled": true, "verified": true, "cap": 500, "used_30d": 120.5, "remaining": 379.5, "window_days": 30, "resets_at": "2026-11-20T10:00:00.000Z" }
}
}| Campo | Descripción |
|---|---|
tier | full (VIP, TrustScore ≥ 85 o cuenta empresa: sin tope) · ssn (SSN verificado: con tope) · null |
reason | Si no es elegible: NOT_ELIGIBLE, GEO_CU (tarjeta desde Cuba o sin geolocalización), SSN_TIER_OFF (nivel apagado), CHANNEL (canal sin el nivel SSN) |
ssn_tier.used_30d / remaining | Lo cobrado por tarjeta y PayPal en los últimos 30 días (pagado, más lo pendiente de la última hora) y lo que queda del tope |
ssn_tier.resets_at | Cuándo sale de la ventana el cobro más antiguo (libera cupo); null sin cobros |
Un POST /topup con CARD o PAYPAL que supere el cupo responde 400 con code: "DEPOSIT_MONTHLY_LIMIT" y cap, used, remaining, window_days, resets_at. Como toda persona de EE. UU., el depósito debe llevar el objeto compliance (atestación de propósito).