> ## 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. # Crear transacción de salida (Venezuela) > Crea un payout en USDT. `amount` es una cadena decimal positiva, no un número JSON. Más de 8 dígitos fraccionarios se redondean hacia abajo a 8 y no se rechazan. Obligatorios: `accountId`, `amount`, `firstName`, `lastName`, `email`, `documentoIdentidad`, `tipoDocumento`, `prefijoTelefono`, `numeroTelefono`, `direccion`, `ciudad`, `pais` (`VE`), `banco`, `tipoCuenta`, `numeroCuenta`, `nombreTitular`, `apellidoTitular`. Opcionales: `celular`, `webhookUrl`. `celular` es obligatorio cuando `tipoCuenta` es Pago Móvil (`13`, `Pago Móvil` o `pago_movil`). Envíe `banco`, `tipoCuenta` y `tipoDocumento` como el `value` del catálogo de `GET /ve/banks`. Las etiquetas de texto se aceptan. `BANK_VALUE` y `ACCOUNT_TYPE_VALUE` en el ejemplo son marcadores de esos valores. `documentoIdentidad` es solo dígitos. La letra va en `tipoDocumento` (`V`, `J`, `P` o `E`). Un prefijo coincidente se quita. Saldo insuficiente devuelve `409` con `{ error, code }` y `code: INSUFFICIENT_NET_BALANCE`. Si el destinatario aún necesita verificación de identidad, la respuesta es `201` con `status: pending_kyc`, `kyc_url` cuando se guardó una URL, y `kyc_expires_at` (24 horas desde la creación). Ese monto y su comisión de salida quedan reservados. El saldo de la cuenta no se debita. No se crea una orden de payout hasta que la verificación esté aprobada. Una verificación aprobada con una cuenta bancaria usable devuelve `201` con `status: processing`. Una verificación rechazada, una verificación que terminó sin aprobación, un correo cuyo documento no coincide, un documento rechazado o una cuenta bancaria rechazada no crea una transacción y devuelve `400` con `code` `VE_KYC_DECLINED`, `VE_KYC_NOT_APPROVED`, `VE_IDENTITY_UNCONFIRMED`, `VE_INVALID_DOCUMENT`, `VE_INVALID_BANK`, `missing_cuenta_id` o `missing_terms`. `missing_cuenta_id` significa que no se pudo guardar la cuenta del payout. Revise `numeroCuenta` y reintente. `missing_terms` significa que no se pudo preparar al destinatario. Reintente en breve. La cadena `error` indica qué corregir cuando falla la cuenta bancaria o el documento. Una cuenta inexistente devuelve `404`. Sin acceso devuelve `403`. `Bloqueada` o `Cerrada` devuelve `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` devuelve `403` con `code: RESTRICTED`. Una cuenta no admitida o una moneda distinta de USDT devuelve `400`. ## OpenAPI ````yaml /api-reference/openapi.es.yaml post /ve/transactions/outbound 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/outbound: post: tags: - Venezuela summary: Crear transacción de salida (Venezuela) description: > Crea un payout en USDT. `amount` es una cadena decimal positiva, no un número JSON. Más de 8 dígitos fraccionarios se redondean hacia abajo a 8 y no se rechazan. Obligatorios: `accountId`, `amount`, `firstName`, `lastName`, `email`, `documentoIdentidad`, `tipoDocumento`, `prefijoTelefono`, `numeroTelefono`, `direccion`, `ciudad`, `pais` (`VE`), `banco`, `tipoCuenta`, `numeroCuenta`, `nombreTitular`, `apellidoTitular`. Opcionales: `celular`, `webhookUrl`. `celular` es obligatorio cuando `tipoCuenta` es Pago Móvil (`13`, `Pago Móvil` o `pago_movil`). Envíe `banco`, `tipoCuenta` y `tipoDocumento` como el `value` del catálogo de `GET /ve/banks`. Las etiquetas de texto se aceptan. `BANK_VALUE` y `ACCOUNT_TYPE_VALUE` en el ejemplo son marcadores de esos valores. `documentoIdentidad` es solo dígitos. La letra va en `tipoDocumento` (`V`, `J`, `P` o `E`). Un prefijo coincidente se quita. Saldo insuficiente devuelve `409` con `{ error, code }` y `code: INSUFFICIENT_NET_BALANCE`. Si el destinatario aún necesita verificación de identidad, la respuesta es `201` con `status: pending_kyc`, `kyc_url` cuando se guardó una URL, y `kyc_expires_at` (24 horas desde la creación). Ese monto y su comisión de salida quedan reservados. El saldo de la cuenta no se debita. No se crea una orden de payout hasta que la verificación esté aprobada. Una verificación aprobada con una cuenta bancaria usable devuelve `201` con `status: processing`. Una verificación rechazada, una verificación que terminó sin aprobación, un correo cuyo documento no coincide, un documento rechazado o una cuenta bancaria rechazada no crea una transacción y devuelve `400` con `code` `VE_KYC_DECLINED`, `VE_KYC_NOT_APPROVED`, `VE_IDENTITY_UNCONFIRMED`, `VE_INVALID_DOCUMENT`, `VE_INVALID_BANK`, `missing_cuenta_id` o `missing_terms`. `missing_cuenta_id` significa que no se pudo guardar la cuenta del payout. Revise `numeroCuenta` y reintente. `missing_terms` significa que no se pudo preparar al destinatario. Reintente en breve. La cadena `error` indica qué corregir cuando falla la cuenta bancaria o el documento. Una cuenta inexistente devuelve `404`. Sin acceso devuelve `403`. `Bloqueada` o `Cerrada` devuelve `403` con `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` devuelve `403` con `code: RESTRICTED`. Una cuenta no admitida o una moneda distinta de USDT devuelve `400`. operationId: createVeOutboundTransaction requestBody: required: true content: application/json: schema: type: object required: - accountId - amount - firstName - lastName - email - documentoIdentidad - tipoDocumento - prefijoTelefono - numeroTelefono - direccion - ciudad - pais - banco - tipoCuenta - numeroCuenta - nombreTitular - apellidoTitular properties: accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' firstName: type: string example: Ada lastName: type: string example: Example email: type: string format: email example: payer@example.com documentoIdentidad: type: string example: '00000000' tipoDocumento: type: string description: '`value` del catálogo en `country.documentTypes`.' example: V prefijoTelefono: type: string example: '+58' numeroTelefono: type: string example: '0000000000' direccion: type: string example: Example street ciudad: type: string example: Example city pais: type: string enum: - VE banco: description: >- `value` del catálogo en `country.banks`. Marcador `BANK_VALUE`. oneOf: - type: string - type: integer minimum: 1 example: BANK_VALUE tipoCuenta: description: >- `value` del catálogo en `country.accountTypes`. Marcador `ACCOUNT_TYPE_VALUE`. `celular` es obligatorio para Pago Móvil (`13`, `Pago Móvil` o `pago_movil`). oneOf: - type: string - type: integer minimum: 1 example: ACCOUNT_TYPE_VALUE numeroCuenta: type: string example: '00000000000000000000' nombreTitular: type: string example: Ada apellidoTitular: type: string example: Example celular: type: string description: Obligatorio para Pago Móvil. Marcador `+580000000000`. example: '+580000000000' webhookUrl: type: string format: uri example: accountId: YOUR_ACCOUNT_UUID amount: '25.5' firstName: Ada lastName: Example email: payer@example.com documentoIdentidad: '00000000' tipoDocumento: V prefijoTelefono: '+58' numeroTelefono: '0000000000' direccion: Example street ciudad: Example city pais: VE banco: BANK_VALUE tipoCuenta: ACCOUNT_TYPE_VALUE numeroCuenta: '00000000000000000000' nombreTitular: Ada apellidoTitular: Example responses: '201': description: >- `processing` cuando la verificación está aprobada y hay una cuenta bancaria usable. `pending_kyc` cuando aún se requiere verificación. El monto y la comisión de salida quedan reservados. El saldo no se debita y no se crea una orden de payout hasta que la verificación esté aprobada. `kyc_expires_at` es 24 horas desde la creación. content: application/json: schema: $ref: '#/components/schemas/VenezuelaOutboundCreated' examples: processing: summary: Payout aceptado value: id: 550e8400-e29b-41d4-a716-446655440000 status: processing pending_kyc: summary: Retenido por verificación de identidad value: id: 550e8400-e29b-41d4-a716-446655440000 status: pending_kyc kyc_url: https://example.com/verify kyc_expires_at: '2026-01-02T00:00:00.000Z' '400': description: >- Falló la validación, la cuenta no es USDT de Venezuela, o el destinatario fue rechazado antes de crear una transacción. content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaPreflightError' - type: object required: - error properties: error: type: string examples: kyc_declined: value: error: >- The recipient identity verification was declined. This payout was not created. code: VE_KYC_DECLINED kyc_not_approved: value: error: >- The recipient completed identity verification but it was not approved. This payout was not created. code: VE_KYC_NOT_APPROVED identity: value: error: The document does not match the email. code: VE_IDENTITY_UNCONFIRMED invalid_document: value: error: >- Send digits only. The letter belongs in tipoDocumento (V, J, P, or E). A matching prefix such as V- is removed. code: VE_INVALID_DOCUMENT invalid_bank: value: error: >- The payout account was rejected. Check banco, tipoCuenta, numeroCuenta, and the account holder name and identity document, then retry. code: VE_INVALID_BANK missing_cuenta_id: value: error: >- The payout account could not be saved. Check numeroCuenta and retry. code: missing_cuenta_id missing_terms: value: error: The recipient could not be prepared. Retry shortly. code: missing_terms '401': description: No autorizado '403': description: >- Sin acceso, la cuenta está `Bloqueada` o `Cerrada`, o la cuenta está `Restringida` 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: value: error: You do not have access to this account not_operative: 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 '409': description: Saldo neto insuficiente para el monto y la comisión de salida content: application/json: schema: $ref: '#/components/schemas/VenezuelaInsufficientNetBalance' '500': description: >- Error interno del servidor. Un payout guardado como `processing` puede devolver `Failed to enqueue outbound processing` si no se pudo encolar el envío. components: schemas: 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' VenezuelaOutboundCreated: type: object required: - id - status properties: id: type: string format: uuid status: type: string enum: - processing - pending_kyc kyc_url: type: string format: uri description: Se incluye en `pending_kyc` solo cuando se guardó una URL. kyc_expires_at: type: string format: date-time description: Presente en `pending_kyc`. 24 horas desde la creación. 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 VenezuelaInsufficientNetBalance: type: object required: - error - code properties: error: type: string example: Insufficient balance to cover transfer and fee code: type: string enum: - INSUFFICIENT_NET_BALANCE 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.