> ## 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.

# Cash-in

> Recibir USDT en cuentas de Venezuela

## Resumen

El cash-in de Venezuela acredita una cuenta **USDT** operativa. Envíe `amount` como cadena decimal positiva. No envíe 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. No son el monto del libro.

No es un checkout hospedado. Cree el cash-in con `POST /api/v1/ve/transactions/inbound`.

## Requisitos

* Token Bearer con acceso a la cuenta USDT
* Nombre opcional del banco del pagador, desde `GET /api/v1/ve/banks` (`onramp.banks[].name`)

## Flujo

1. Llame a `GET /api/v1/ve/banks` si quiere fijar el banco del pagador
2. `POST /api/v1/ve/transactions/inbound` con `accountId` y `amount`
3. Consulte `GET /api/v1/ve/transactions/{id}/status`, o defina `webhookUrl` — vea [Recepción de webhooks](/es/developers/receiving-webhooks)

## Solicitud

Obligatorios: `accountId`, `amount`.

Opcionales: `bancoPago`, `webhookUrl`.

`bancoPago` debe ser un `onramp.banks[].name` exacto. 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`.

## Ejemplo

`ONRAMP_BANK_NAME` es un marcador. Copie el nombre exacto de `onramp.banks[].name` en `GET /api/v1/ve/banks`.

```bash theme={null}
curl -X POST https://hg.cash/api/v1/ve/transactions/inbound \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_UUID",
    "amount": "100.5",
    "bancoPago": "ONRAMP_BANK_NAME",
    "webhookUrl": "https://merchant.example/hooks/hg"
  }'
```

## Éxito

`201` devuelve `id`, `status: pending`, `amount` (cadena decimal USDT) y `orden_id`. `montoFiat` y `tasaCompra` se incluyen solo cuando la respuesta de creación los trae.

## Estado

`GET /api/v1/ve/transactions/{id}/status` lee el estado del cash-in y del payout. `amount` es una cadena decimal USDT.

Cuando ya existen las instrucciones de pago, el cuerpo puede incluir `banco` y `numero_cuenta`, solo de entrada. Esos campos de cobro no se devuelven en un payout.

Vea [Payouts](/es/countries/venezuela/payouts) para `pending_kyc`, `kyc_url`, `kyc_expires_at` y `cancelledReason`.

## Errores

| HTTP | Cuándo |
| - | - |
| `404` | La cuenta no existe |
| `403` | No puede usar esta cuenta |
| `403` `ACCOUNT_NOT_OPERATIVE` | La cuenta está `Bloqueada` o `Cerrada` |
| `403` `RESTRICTED` | La cuenta está `Restringida` |
| `400` | La cuenta no admite esta operación, o su moneda no es USDT |
| `400` `VE_INBOUND_INVALID_BANCO_PAGO` | `bancoPago` no es un nombre de banco de entrada |
| `500` `VE_BANKS_PROVIDER_NOT_CONFIGURED` | La integración de pago no está configurada. No se crea una transacción, incluso si se omite `bancoPago` |
| `502` `VE_BANKS_PROVIDER_ERROR` | Solo cuando se envía `bancoPago`. La lista de bancos se comprueba antes de que exista una fila. No se crea ni se cancela una fila |
| `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` | No se pudo crear el cash-in. La fila ya existe y se cancela |
| `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` | La respuesta de creación no incluyó un id de orden. La fila ya existe y se cancela |

Si la integración de pago no está configurada, la API devuelve `500` con `code: VE_BANKS_PROVIDER_NOT_CONFIGURED` y no 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`.

## Estado de la cuenta

La cuenta debe estar **`Operativa`** y en **USDT**. **`Bloqueada`** o **`Cerrada`** devuelve `403` con `code: ACCOUNT_NOT_OPERATIVE`. **`Restringida`** devuelve `403` con `code: RESTRICTED`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.