> ## 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. # Obtener estado de la transacción (Venezuela) > Lee el estado de entrada o de salida. `amount` es una cadena decimal USDT. `status` incluye `pending_kyc`. `externalID` se omite hasta que existe el id de orden, y entonces se devuelve. Campos opcionales, solo cuando están presentes: `orden_id`, `montoFiat`, `tasaCompra`, `banco` y `numero_cuenta` solo de entrada, `kyc_url` de salida, y `kyc_expires_at` mientras la retención `pending_kyc` sigue abierta. `feeBreakdown`, cuando existe un desglose, omite `flatFee.source`. En un payout cancelado porque se requería verificación de identidad, `kyc_url` se incluye solo cuando se guardó una URL no vacía. `cancelledReason` se incluye solo para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` o `VE_KYC_REQUIRED`. Los demás motivos de cancelación se omiten. El webhook `status_change` del comercio incluye `cancelledReason` solo para esos mismos tres códigos. Una transacción que no es un movimiento de Venezuela devuelve `400`. ## OpenAPI ````yaml /api-reference/openapi.es.yaml get /ve/transactions/{id}/status 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/transactions/{id}/status: get: tags: - Venezuela summary: Obtener estado de la transacción (Venezuela) description: > Lee el estado de entrada o de salida. `amount` es una cadena decimal USDT. `status` incluye `pending_kyc`. `externalID` se omite hasta que existe el id de orden, y entonces se devuelve. Campos opcionales, solo cuando están presentes: `orden_id`, `montoFiat`, `tasaCompra`, `banco` y `numero_cuenta` solo de entrada, `kyc_url` de salida, y `kyc_expires_at` mientras la retención `pending_kyc` sigue abierta. `feeBreakdown`, cuando existe un desglose, omite `flatFee.source`. En un payout cancelado porque se requería verificación de identidad, `kyc_url` se incluye solo cuando se guardó una URL no vacía. `cancelledReason` se incluye solo para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` o `VE_KYC_REQUIRED`. Los demás motivos de cancelación se omiten. El webhook `status_change` del comercio incluye `cancelledReason` solo para esos mismos tres códigos. Una transacción que no es un movimiento de Venezuela devuelve `400`. operationId: getVeTransactionStatus parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Estado de la transacción content: application/json: schema: $ref: '#/components/schemas/VenezuelaTransactionStatus' examples: inbound: summary: Cash-in con instrucciones de cobro value: id: 550e8400-e29b-41d4-a716-446655440000 externalID: '1000' status: pending direction: Inbound amount: '100.5' currency: USDT orden_id: 1000 banco: ONRAMP_BANK_NAME numero_cuenta: '00000000000000000000' pending_kyc: summary: Payout retenido por verificación de identidad value: id: 550e8400-e29b-41d4-a716-446655440000 status: pending_kyc direction: Outbound amount: '25.5' currency: USDT kyc_url: https://example.com/verify kyc_expires_at: '2026-01-02T00:00:00.000Z' cancelled: summary: Payout cancelado por un motivo público value: id: 550e8400-e29b-41d4-a716-446655440000 status: cancelled direction: Outbound amount: '25.5' currency: USDT cancelledReason: VE_KYC_EXPIRED '400': description: >- Falta el id de la transacción, o la transacción no admite consulta de estado content: application/json: schema: type: object required: - error properties: error: type: string examples: unsupported: value: error: Transaction is not supported for status polling missing_id: value: error: Transaction ID is required '401': description: No autorizado '404': description: Transacción no encontrada '500': description: Error interno del servidor components: schemas: VenezuelaTransactionStatus: type: object required: - id - status - direction - amount - currency properties: id: type: string format: uuid externalID: type: string description: >- Se omite hasta que existe el id de orden. Se devuelve cuando ya es ese id de orden. status: type: string description: >- Estado actual del libro. Incluye `pending` para el cash-in, `processing` cuando se acepta un payout, `pending_kyc` mientras la verificación de identidad retiene un payout, `done` y `cancelled`. direction: type: string enum: - Inbound - Outbound amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' currency: type: string example: USDT orden_id: type: integer description: Se incluye solo cuando está presente. montoFiat: type: string description: Metadato en VES. Se incluye solo cuando está presente. tasaCompra: type: string description: Metadato en VES. Se incluye solo cuando está presente. banco: type: string description: Banco de cobro, solo de entrada. Nunca se devuelve en un payout. numero_cuenta: type: string description: >- Número de cuenta de cobro, solo de entrada. Nunca se devuelve en un payout. kyc_url: type: string description: >- Solo de salida. Se incluye cuando se guardó una URL no vacía, también si un payout se canceló porque se requería verificación de identidad. kyc_expires_at: type: string format: date-time description: Se incluye mientras la retención `pending_kyc` sigue abierta. cancelledReason: type: string description: >- Se incluye solo para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` o `VE_KYC_REQUIRED`. Los demás motivos de cancelación se omiten. enum: - VE_KYC_EXPIRED - VE_KYC_DECLINED - VE_KYC_REQUIRED feeBreakdown: $ref: '#/components/schemas/VenezuelaStatusFeeBreakdown' VenezuelaUsdtAmount: type: string description: >- Cadena decimal USDT positiva. No es un número JSON. Más de 8 dígitos fraccionarios se redondean hacia abajo a 8 y no se rechazan. Los montos en VES no son este campo. pattern: ^\d+(\.\d+)?$ example: '100.5' VenezuelaStatusFeeBreakdown: type: object description: >- Desglose de comisión opcional en el estado de Venezuela. Los montos y las tasas son cadenas decimales. Se omite cuando no hay desglose. `flatFee` incluye solo `amount`. Esta respuesta no incluye `flatFee.source`. properties: platformFee: type: object properties: amount: type: string rate: type: string nullable: true transactionFee: type: object properties: amount: type: string rate: type: string nullable: true flatFee: type: object properties: amount: type: string collectedAmount: type: string 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.