> ## 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 entrada (Venezuela) > Acredita una cuenta USDT operativa. `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. `montoFiat` y `tasaCompra` son metadatos en VES. Si la integración de pago no está configurada, la API devuelve `500` con `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, incluso cuando se omite `bancoPago`, y no se crea una transacción. `502` `VE_BANKS_PROVIDER_ERROR` ocurre solo cuando se envía `bancoPago`. La lista de bancos se comprueba antes de que exista una fila de transacción. Esa respuesta no crea una fila y no cancela ninguna. `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` y `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` significan que la fila ya existe, esa fila se cancela y la respuesta es `502`. Obligatorios: `accountId`, `amount`. Opcionales: `bancoPago`, `webhookUrl`. `bancoPago` debe ser un `onramp.banks[].name` exacto de `GET /ve/banks`. No es el id numérico ni un `country.banks[].label`. Omítalo para dejar el banco del pagador sin definir. Un nombre desconocido o un id crudo devuelve `400` con `code: VE_INBOUND_INVALID_BANCO_PAGO`. El éxito es `201` con `id`, `status: pending`, `amount`, `orden_id`, y `montoFiat` / `tasaCompra` solo cuando la respuesta de creación los incluye. 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/inbound 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/inbound: post: tags: - Venezuela summary: Crear transacción de entrada (Venezuela) description: > Acredita una cuenta USDT operativa. `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. `montoFiat` y `tasaCompra` son metadatos en VES. Si la integración de pago no está configurada, la API devuelve `500` con `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, incluso cuando se omite `bancoPago`, y no se crea una transacción. `502` `VE_BANKS_PROVIDER_ERROR` ocurre solo cuando se envía `bancoPago`. La lista de bancos se comprueba antes de que exista una fila de transacción. Esa respuesta no crea una fila y no cancela ninguna. `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` y `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` significan que la fila ya existe, esa fila se cancela y la respuesta es `502`. Obligatorios: `accountId`, `amount`. Opcionales: `bancoPago`, `webhookUrl`. `bancoPago` debe ser un `onramp.banks[].name` exacto de `GET /ve/banks`. No es el id numérico ni un `country.banks[].label`. Omítalo para dejar el banco del pagador sin definir. Un nombre desconocido o un id crudo devuelve `400` con `code: VE_INBOUND_INVALID_BANCO_PAGO`. El éxito es `201` con `id`, `status: pending`, `amount`, `orden_id`, y `montoFiat` / `tasaCompra` solo cuando la respuesta de creación los incluye. 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: createVeInboundTransaction requestBody: required: true content: application/json: schema: type: object required: - accountId - amount properties: accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' bancoPago: type: string description: >- `onramp.banks[].name` exacto de `GET /ve/banks`. No es el id numérico. example: ONRAMP_BANK_NAME webhookUrl: type: string format: uri example: accountId: YOUR_ACCOUNT_UUID amount: '100.5' bancoPago: ONRAMP_BANK_NAME responses: '201': description: Cash-in creado content: application/json: schema: $ref: '#/components/schemas/VenezuelaInboundCreated' example: id: 550e8400-e29b-41d4-a716-446655440000 status: pending amount: '100.5' orden_id: 1000 '400': description: >- Falló la validación, la cuenta no está admitida, la moneda no es USDT, o `bancoPago` no es un nombre de banco de entrada (`VE_INBOUND_INVALID_BANCO_PAGO`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/VenezuelaValidationError' - $ref: '#/components/schemas/VenezuelaProviderError' - type: object required: - error properties: error: type: string examples: invalid_banco_pago: summary: '`bancoPago` no es un nombre de banco de entrada' value: error: >- bancoPago must match an on-ramp bank name from GET /ve/banks (onramp.banks[].name). code: VE_INBOUND_INVALID_BANCO_PAGO type: validation_error unsupported_account: summary: La cuenta no está admitida value: error: Account is not supported for this operation currency: summary: La moneda no es USDT value: error: Account currency must be USDT for this operation '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: summary: Sin acceso 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: La integración de pago no está configurada, o un error interno content: application/json: schema: $ref: '#/components/schemas/VenezuelaProviderError' example: error: The payment integration is not configured. code: VE_BANKS_PROVIDER_NOT_CONFIGURED type: provider_error '502': description: >- `VE_BANKS_PROVIDER_ERROR` ocurre solo cuando se envía `bancoPago`. La lista de bancos se comprueba antes de que exista una fila de transacción. Esa respuesta no crea una fila y no cancela ninguna. `VE_INBOUND_PROVIDER_CREATE_FAILED` y `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` significan que la fila ya existe, esa fila se cancela y la respuesta es 502. content: application/json: schema: $ref: '#/components/schemas/VenezuelaProviderError' examples: create_failed: summary: No se pudo crear el cash-in value: error: Unable to complete this request with the payment provider. code: VE_INBOUND_PROVIDER_CREATE_FAILED type: provider_error missing_orden_id: summary: La respuesta de creación no trajo id de orden value: error: >- The payment provider returned an incomplete response. Please try again or contact support. code: VE_INBOUND_PROVIDER_MISSING_ORDEN_ID type: provider_invalid_response banks_failed: summary: >- La lista de bancos de entrada falló antes de existir una fila, solo si se envió bancoPago value: error: Unable to fetch banks from the payment provider. code: VE_BANKS_PROVIDER_ERROR type: provider_error 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' VenezuelaInboundCreated: type: object required: - id - status - amount - orden_id properties: id: type: string format: uuid status: type: string enum: - pending amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' orden_id: type: integer montoFiat: type: string description: >- Metadato en VES. Se incluye solo cuando la respuesta de creación lo trae. tasaCompra: type: string description: >- Metadato en VES. Se incluye solo cuando la respuesta de creación lo trae. 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 VenezuelaProviderError: type: object required: - error - code - type properties: error: type: string code: type: string enum: - VE_BANKS_PROVIDER_NOT_CONFIGURED - VE_BANKS_PROVIDER_ERROR - VE_INBOUND_INVALID_BANCO_PAGO - VE_INBOUND_PROVIDER_CREATE_FAILED - VE_INBOUND_PROVIDER_MISSING_ORDEN_ID type: type: string enum: - provider_error - provider_invalid_response - validation_error 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.