Traducción Automática

Esta página utiliza traducción automática. Para cualquier inconsistencia, consulte la documentación en inglés.

Verificación de dirección

Crypto2B permite que el sistema cliente compruebe el nivel de riesgo (AML) de cualquier dirección cripto antes de realizar una operación con ella. Un escenario típico es verificar una dirección que el usuario ingresó en un formulario de retiro, antes de que se cree la solicitud de retiro.

La verificación se realiza de forma asíncrona. El sistema cliente registra una verificación llamando a la API /addressChecks/create, y obtiene el resultado de una de dos maneras:

1. Procesar el callback de Crypto2B con el resultado de la verificación (ver Callbacks).
2. Volver a llamar a la API /addressChecks/create con los mismos parámetros hasta recibir el resultado.

Proceso de verificación de dirección

Secuencia de acciones

1. El usuario ingresa una dirección en el sistema cliente, por ejemplo, para un retiro.
2. El sistema cliente envía a Crypto2B una solicitud para verificar la dirección, especificando la moneda, el protocolo de transporte y la dirección.
3. Crypto2B valida los parámetros de la solicitud, las restricciones del cliente y la disponibilidad de fondos para pagar la verificación, registra la verificación y devuelve su identificador checkId con estado Pending.
4. Crypto2B realiza la verificación de la dirección y determina su nivel de riesgo.
5. Cuando la verificación se completa, Crypto2B descuenta la tarifa de verificación del saldo del cliente y pasa la verificación al estado Completed.
6. Si el sistema cliente utiliza el mecanismo de callback, Crypto2B envía un callback con el resultado de la verificación.
7. De lo contrario, el sistema cliente repite la solicitud con los mismos parámetros y recibe el resultado con estado Completed.
8. El sistema cliente decide si acepta la dirección según el nivel de riesgo amlRiskGrade.

Solicitud

POST /api/v1/addressChecks/create

Parámetro	Tipo	Obligatorio	Descripción
currencyShortName	string	sí	Nombre corto de la moneda, por ejemplo USDT
transportProtocol	string	sí	Protocolo de transporte, por ejemplo Tron
address	string	sí	Dirección a verificar, no más de 200 caracteres

{
  "currencyShortName": "USDT",
  "transportProtocol": "Tron",
  "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b"
}

Respuesta

Verificación registrada o en curso — 202 Accepted

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Pending",
    "amlRiskGrade": null,
    "description": null,
    "fromCache": null
  }
}

Verificación completada — 200 OK

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "fromCache": true
  }
}

Campo	Descripción
checkId	Identificador único de la verificación
status	Estado de la verificación: Pending, Completed
amlRiskGrade	Nivel de riesgo de la dirección (ver Diccionarios). Se completa solo cuando el estado es Completed
description	Descripción de la dirección basada en el resultado de la verificación, si está disponible
fromCache	true si se devuelve un resultado obtenido previamente (ver Verificaciones repetidas)

Errores

Código HTTP	Código de error	Descripción
400	—	Error de validación de parámetros de la solicitud, incluido un formato de dirección inválido para la moneda y el protocolo especificados
400	INVALID_CURRENCY	Moneda no encontrada o no compatible con el protocolo especificado
400	INVALID_TRANSPORT_PROTOCOL	Protocolo de transporte no encontrado
402	INSUFFICIENT_BALANCE	El saldo del cliente no tiene fondos suficientes para pagar la verificación
422	OPERATION_RESTRICTED	La verificación de dirección no está disponible para este cliente
422	TARIFF_NOT_FOUND	No hay una tarifa configurada para el cliente

Estados de verificación

Estado	Descripción
Pending	La verificación está registrada y en curso
Completed	La verificación se completó correctamente, se obtuvo el nivel de riesgo y se cobró la tarifa
Error	La verificación falló debido a un error. No se cobra la tarifa
Unknown	No se pudo determinar el resultado de la verificación, por ejemplo, la verificación no es compatible con la moneda especificada. No se cobra la tarifa

info

Los estados Error y Unknown solo se entregan en el callback. Si la solicitud se repite después de una verificación de este tipo, Crypto2B registra una nueva verificación y devuelve 202 Accepted con un nuevo checkId.

Verificaciones repetidas

El resultado de una verificación exitosa se almacena durante 10 minutos. Una solicitud repetida con la misma moneda, protocolo y dirección dentro de este tiempo:

• mientras la verificación está en curso — devuelve 202 Accepted con el mismo checkId; no se crea una nueva verificación;
• después de completarse — devuelve 200 OK con el resultado almacenado y fromCache: true; la tarifa no se cobra nuevamente.

Después de 10 minutos, la solicitud registra una nueva verificación, por la cual se cobra la tarifa.

tip

Si el sistema cliente no utiliza callbacks, se recomienda repetir la solicitud cada pocos segundos hasta recibir 200 OK. Un cambio en el checkId de la respuesta significa que la verificación anterior terminó en error y se registró una nueva.

Tarifa de verificación

Por cada verificación completada con éxito, se descuenta del saldo del cliente una tarifa fija en USD; su monto lo determina la tarifa contratada por el cliente (ver Facturación).

• La tarifa se cobra cuando la verificación se completa con estado Completed.
• La tarifa se descuenta del saldo en stablecoins del cliente (USDT o USDC) al tipo de cambio vigente en el momento del cobro. El monto y la moneda del cobro se envían en el callback.
• Si ninguno de los saldos en stablecoins tiene fondos suficientes, la solicitud se rechaza con el código 402.
• No se cobra tarifa por verificaciones con estado Error o Unknown.
• Los cargos por verificación de dirección se muestran en la lista de operaciones de la cuenta personal.

Callback

Si hay una URL de callback configurada para el cliente, Crypto2B envía un callback cuando la verificación se completa en cualquier estado final: Completed, Error, Unknown.

{
  "data": {
    "type": "AddressCheck",
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "currency": "USDT",
    "protocol": "Tron",
    "feeAmount": 0.5,
    "feeCurrencyShortName": "USDT",
    "timestamp": "2024-01-15T10:30:00Z",
    "errorCode": null,
    "errorMessage": null
  }
}

Campo	Descripción
type	Tipo de operación: AddressCheck
checkId	Identificador de la verificación
address	Dirección verificada
status	Estado de la verificación: Completed, Error, Unknown
amlRiskGrade	Nivel de riesgo de la dirección. Se completa solo cuando el estado es Completed
description	Descripción de la dirección basada en el resultado de la verificación, si está disponible
currency	Nombre corto de la moneda
protocol	Protocolo de transporte
feeAmount	Monto de la tarifa cobrada, en la moneda feeCurrencyShortName. null si no se cobró ninguna tarifa
feeCurrencyShortName	Moneda en la que se cobró la tarifa
timestamp	Fecha y hora en que se generó el callback (ISO 8601)
errorCode	Código de error para los estados Error y Unknown
errorMessage	Descripción del error para los estados Error y Unknown

Códigos de error del callback

Código	Estado	Descripción
INSUFFICIENT_BALANCE	Error	En el momento del cobro, el saldo del cliente no tenía fondos suficientes para pagar la verificación
ANTIFRAUD_ERROR	Error	Error al realizar la verificación
ANTIFRAUD_INVALID_RESULT	Unknown	La verificación se completó sin determinar un nivel de riesgo
CURRENCY_NOT_SUPPORTED	Unknown	La verificación de dirección no es compatible con la moneda o el protocolo especificados
INTERNAL_ERROR	Error	Error interno de procesamiento

nota

Para los callbacks de verificación de dirección, la unicidad se determina por la combinación de type y checkId, no de type e id como en otras operaciones.