> ## Documentation Index > Fetch the complete documentation index at: https://docs.hg.cash/llms.txt > Use this file to discover all available pages before exploring further. # Verificar destinatario (Venezuela) > Consulta un destinatario antes de un payout. No crea una transacción, no reserva USDT y no guarda una cuenta bancaria. Obligatorios: `accountId` (cuenta USDT operativa desde la que el llamador puede pagar), `email`, `documentoIdentidad`, `tipoDocumento`. Opcional: `numeroCuenta`. Si se envía, `ready` significa que la verificación de identidad está aprobada y esa cuenta ya está registrada. Si se omite, `ready` significa aprobado y que ya hay una cuenta bancaria registrada. `documentoIdentidad` es solo dígitos. La letra va en `tipoDocumento` (`V`, `J`, `P` o `E` de `GET /ve/banks`). Se acepta y se quita un prefijo coincidente `V-`, `J-`, `P-` o `E-`. Una cuenta inexistente devuelve `404`. Quien no puede pagar desde esa cuenta, o una cuenta que no es USDT de Venezuela, devuelve `403`. Una cuenta no operativa devuelve `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` devuelve `403` con `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion` y `ciudad` son obligatorios solo cuando el correo aún no está registrado (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). Si esos campos están presentes y el correo sigue sin estar registrado, la respuesta es `kyc_not_started` sin `kyc_url`. Esta llamada no registra ese correo. Un documento que no coincide con un correo existente devuelve `400` con `code: VE_IDENTITY_UNCONFIRMED` y no inicia la verificación de identidad. El `status` de éxito es `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started` o `kyc_declined`. `kyc_declined` incluye `code: VE_KYC_DECLINED`. Para un correo que ya está registrado y no tiene sesión, esta llamada puede iniciar la verificación y devolver `kyc_url`. Para un destinatario existente, `kyc_not_started` devuelve `kyc_url` cuando se emitió una URL de sesión. `kyc_in_progress` incluye `kyc_url` solo cuando el payload de estado la trae, o cuando un payout de este `accountId` ya guardó una. No lea esa URL desde transacciones de otra cuenta. ## OpenAPI ````yaml /api-reference/openapi.es.yaml post /ve/recipients/kyc openapi: 3.1.0 info: title: HG.Cash API description: > # 🚀 API de transacciones HG.Cash API REST moderna para que los usuarios creen transacciones de salida desde sus cuentas. ## 🧾 Cómo funciona - HG.Cash asigna cuentas a su usuario - Cuando estas cuentas tienen movimientos (entrada o salida), HG.Cash notificará su backend usando la URL de webhook que configure en el panel de HG.Cash - **Firma de webhooks (HMAC)**: En la configuración de la cuenta puede generar un secreto de firma. Cuando está configurado, cada POST de webhook incluye el encabezado `X-HG-Webhook-Signature: sha256=` donde el valor es HMAC-SHA256 del cuerpo JSON sin procesar usando su secreto. Verifíquelo en su endpoint para asegurar que la solicitud es auténtica. - Para crear retiros (dinero que sale de sus cuentas), debe llamar al endpoint **Cash Out**: **Crear solicitud de transacción** (`POST /transactions`) ## 📊 Primeros pasos 1. **Genere su token de API** en la página de configuración de la cuenta 2. **Pruebe los endpoints** usando la documentación interactiva a continuación 3. **Implemente** en sus servicios de backend (nunca exponga tokens en el frontend) 4. **Supervise** su integración y maneje los errores adecuadamente ## 🔐 Autenticación Esta API usa autenticación **Bearer Token**. Incluya el token de API del usuario en el encabezado Authorization, por ejemplo `Authorization: Bearer cash_your_token_here`. ## ⚠️ Notas importantes de seguridad - Nunca comparta ni exponga su token de autenticación de API de usuario - Almacene los tokens de forma segura solo en sus servidores de backend - Todas las llamadas a la API deben realizarse desde servicios de backend seguros - Contacte a los administradores inmediatamente si su token se ve comprometido version: 1.0.0 contact: name: HG.Cash API Support email: api-support@hg.cash license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://hg.cash/api/v1 description: Servidor de producción - url: http://dev.hg.cash/api/v1 description: Servidor de desarrollo security: - bearerAuth: [] tags: - name: Transacciones description: >- Gestión de transacciones - Crear y administrar transacciones en el sistema HG.Cash. Todos los endpoints de transacciones requieren autenticación. - name: Cuentas description: >- Cuentas - Obtener información de cuentas y saldos del usuario autenticado. Todos los endpoints de cuentas requieren autenticación. - name: Datos de referencia description: >- Datos de referencia - Obtener datos de referencia como estados y tipos de transacción. Estos endpoints requieren autenticación. - name: Webhooks description: Webhooks - Notificaciones de eventos enviadas a su endpoint HTTP. - name: Brasil description: Brasil — Crear y consultar transacciones PIX (BRL). - name: Chile description: Chile — Checkout hospedado y payouts bancarios (CLP). - name: Bolivia description: Bolivia — Cash-in con QR y payouts ACH (BOB). - name: Colombia description: >- Colombia — Cash-in con checkout hospedado y payouts bancarios, llave Bre-B o QR Bre-B (COP). - name: Venezuela description: Venezuela — Cash-in y payouts en USDT. - name: Checkouts description: Sesiones de checkout hospedado para AR, BR, CL, BO y CO - name: Claims description: Reclamos con evidencia de comprobante de transferencia paths: /ve/recipients/kyc: post: tags: - Venezuela summary: Verificar destinatario (Venezuela) description: > Consulta un destinatario antes de un payout. No crea una transacción, no reserva USDT y no guarda una cuenta bancaria. Obligatorios: `accountId` (cuenta USDT operativa desde la que el llamador puede pagar), `email`, `documentoIdentidad`, `tipoDocumento`. Opcional: `numeroCuenta`. Si se envía, `ready` significa que la verificación de identidad está aprobada y esa cuenta ya está registrada. Si se omite, `ready` significa aprobado y que ya hay una cuenta bancaria registrada. `documentoIdentidad` es solo dígitos. La letra va en `tipoDocumento` (`V`, `J`, `P` o `E` de `GET /ve/banks`). Se acepta y se quita un prefijo coincidente `V-`, `J-`, `P-` o `E-`. Una cuenta inexistente devuelve `404`. Quien no puede pagar desde esa cuenta, o una cuenta que no es USDT de Venezuela, devuelve `403`. Una cuenta no operativa devuelve `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` devuelve `403` con `code: RESTRICTED`. `firstName`, `lastName`, `prefijoTelefono`, `numeroTelefono`, `direccion` y `ciudad` son obligatorios solo cuando el correo aún no está registrado (`400`, `code: VE_RECIPIENT_DETAILS_REQUIRED`). Si esos campos están presentes y el correo sigue sin estar registrado, la respuesta es `kyc_not_started` sin `kyc_url`. Esta llamada no registra ese correo. Un documento que no coincide con un correo existente devuelve `400` con `code: VE_IDENTITY_UNCONFIRMED` y no inicia la verificación de identidad. El `status` de éxito es `ready`, `kyc_approved_no_account`, `kyc_in_progress`, `kyc_not_started` o `kyc_declined`. `kyc_declined` incluye `code: VE_KYC_DECLINED`. Para un correo que ya está registrado y no tiene sesión, esta llamada puede iniciar la verificación y devolver `kyc_url`. Para un destinatario existente, `kyc_not_started` devuelve `kyc_url` cuando se emitió una URL de sesión. `kyc_in_progress` incluye `kyc_url` solo cuando el payload de estado la trae, o cuando un payout de este `accountId` ya guardó una. No lea esa URL desde transacciones de otra cuenta. operationId: checkVeRecipientKyc requestBody: required: true content: application/json: schema: type: object required: - accountId - email - documentoIdentidad - tipoDocumento properties: accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID email: type: string format: email example: payer@example.com documentoIdentidad: type: string description: >- Solo dígitos. Se quita un prefijo coincidente `V-`, `J-`, `P-` o `E-`. example: '00000000' tipoDocumento: type: string description: >- `value` del catálogo en `country.documentTypes`. `V`, `J`, `P` o `E`. example: V numeroCuenta: type: string firstName: type: string lastName: type: string prefijoTelefono: type: string example: '+58' numeroTelefono: type: string example: '0000000000' direccion: type: string ciudad: type: string example: accountId: YOUR_ACCOUNT_UUID email: payer@example.com documentoIdentidad: '00000000' tipoDocumento: V responses: '200': description: Resultado de la verificación. No crea una transacción. content: application/json: schema: $ref: '#/components/schemas/VenezuelaRecipientKycResponse' examples: ready: summary: Aprobado y hay una cuenta bancaria registrada value: status: ready not_registered: summary: El correo no está registrado value: status: kyc_not_started declined: summary: Verificación rechazada value: status: kyc_declined code: VE_KYC_DECLINED '400': description: >- Falló la validación, faltan datos del destinatario (`VE_RECIPIENT_DETAILS_REQUIRED`), o el documento no coincide con el correo (`VE_IDENTITY_UNCONFIRMED`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaPreflightError' examples: details_required: summary: >- Un correo nuevo no tiene nombre, teléfono, dirección o ciudad value: error: >- Name, phone, address, and city are required to register a new recipient. code: VE_RECIPIENT_DETAILS_REQUIRED identity: summary: El documento no coincide con el correo value: error: >- The document does not match the email. Verification was not started. code: VE_IDENTITY_UNCONFIRMED '401': description: No autorizado '403': description: >- Sin acceso, la cuenta no es USDT de Venezuela, la cuenta no está operativa (`ACCOUNT_NOT_OPERATIVE`), o la cuenta está `Restringida` (`RESTRICTED`). content: application/json: schema: oneOf: - type: object required: - error properties: error: type: string - type: object required: - error - code properties: error: type: string code: type: string enum: - ACCOUNT_NOT_OPERATIVE - RESTRICTED examples: no_access: summary: No puede pagar desde esta cuenta value: error: You do not have access to this account not_operative: summary: La cuenta no está operativa value: error: Account is not operative code: ACCOUNT_NOT_OPERATIVE restricted: summary: Account is restricted value: error: Account is restricted code: RESTRICTED '404': description: Cuenta no encontrada content: application/json: schema: type: object required: - error properties: error: type: string example: Account not found '500': description: Error interno del servidor components: schemas: VenezuelaRecipientKycResponse: type: object required: - status properties: status: type: string enum: - ready - kyc_approved_no_account - kyc_in_progress - kyc_not_started - kyc_declined kyc_url: type: string format: uri description: >- Para un correo que ya está registrado y no tiene sesión, esta llamada puede iniciar la verificación y devolver esta URL. Para un destinatario existente, `kyc_not_started` incluye esto cuando se emitió una URL de sesión. `kyc_in_progress` lo incluye solo cuando el payload de estado lo trae, o cuando un payout de este `accountId` ya guardó uno. Nunca se toma de transacciones de otra cuenta. Se omite en `kyc_not_started` si el correo no está registrado. code: type: string enum: - VE_KYC_DECLINED description: Presente solo cuando `status` es `kyc_declined`. VenezuelaValidationError: type: object required: - error - details properties: error: type: string example: Validation failed details: type: array items: type: object properties: field: type: string message: type: string VenezuelaPreflightError: type: object required: - error - code description: >- Se devuelve cuando un payout o la verificación del destinatario se rechaza antes de que exista una transacción. La cadena `error` indica qué corregir si falla la cuenta bancaria o el documento. properties: error: type: string code: type: string enum: - VE_RECIPIENT_DETAILS_REQUIRED - VE_IDENTITY_UNCONFIRMED - VE_KYC_DECLINED - VE_KYC_NOT_APPROVED - VE_INVALID_DOCUMENT - VE_INVALID_BANK - missing_cuenta_id - missing_terms securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token de autenticación de API de usuario con formato `cash_<64-char-hex>`. Valor de ejemplo `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.