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

> Receber USDT em contas da Venezuela

## Visão geral

O cash-in da Venezuela credita uma conta **USDT** operativa. Envie `amount` como string decimal positiva. Não envie um número JSON. Mais de 8 dígitos fracionários são arredondados para baixo até 8 e não são rejeitados. `montoFiat` e `tasaCompra` são metadados em VES. Não são o valor do ledger.

Não é um checkout hospedado. Crie o cash-in com `POST /api/v1/ve/transactions/inbound`.

## Pré-requisitos

* Token Bearer com acesso à conta USDT
* Nome opcional do banco do pagador, de `GET /api/v1/ve/banks` (`onramp.banks[].name`)

## Fluxo

1. Chame `GET /api/v1/ve/banks` quando quiser definir o banco do pagador
2. `POST /api/v1/ve/transactions/inbound` com `accountId` e `amount`
3. Consulte `GET /api/v1/ve/transactions/{id}/status`, ou defina `webhookUrl` — veja [Recebimento de webhooks](/pt-BR/developers/receiving-webhooks)

## Requisição

Obrigatórios: `accountId`, `amount`.

Opcionais: `bancoPago`, `webhookUrl`.

`bancoPago` deve ser um `onramp.banks[].name` exato. Não é o id numérico e não é um `country.banks[].label`. Omita para deixar o banco do pagador indefinido. Um nome desconhecido ou um id cru retorna `400` com `code: VE_INBOUND_INVALID_BANCO_PAGO`.

## Exemplo

`ONRAMP_BANK_NAME` é um marcador. Copie o nome exato de `onramp.banks[].name` em `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"
  }'
```

## Sucesso

`201` retorna `id`, `status: pending`, `amount` (string decimal USDT) e `orden_id`. `montoFiat` e `tasaCompra` entram somente quando a resposta de criação os inclui.

## Status

`GET /api/v1/ve/transactions/{id}/status` lê o status do cash-in e do payout. `amount` é uma string decimal USDT.

Depois que as instruções de pagamento existem, o corpo pode incluir `banco` e `numero_cuenta`, somente de entrada. Esses campos de cobrança nunca voltam em um payout.

Veja [Payouts](/pt-BR/countries/venezuela/payouts) para `pending_kyc`, `kyc_url`, `kyc_expires_at` e `cancelledReason`.

## Erros

| HTTP | Quando |
| - | - |
| `404` | A conta não existe |
| `403` | Você não pode usar esta conta |
| `403` `ACCOUNT_NOT_OPERATIVE` | A conta está `Bloqueada` ou `Cerrada` |
| `403` `RESTRICTED` | A conta está `Restringida` |
| `400` | A conta não é compatível com esta operação, ou a moeda não é USDT |
| `400` `VE_INBOUND_INVALID_BANCO_PAGO` | `bancoPago` não é um nome de banco de entrada |
| `500` `VE_BANKS_PROVIDER_NOT_CONFIGURED` | A integração de pagamento não está configurada. Nenhuma transação é criada, inclusive quando `bancoPago` é omitido |
| `502` `VE_BANKS_PROVIDER_ERROR` | Somente quando `bancoPago` é enviado. A lista de bancos é conferida antes de existir uma linha. Nenhuma linha é criada ou cancelada |
| `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` | Não foi possível criar o cash-in. A linha já existe e é cancelada |
| `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` | A resposta de criação não incluiu um id de ordem. A linha já existe e é cancelada |

Quando a integração de pagamento não está configurada, a API retorna `500` com `code: VE_BANKS_PROVIDER_NOT_CONFIGURED` e não cria uma transação. `502` `VE_BANKS_PROVIDER_ERROR` ocorre somente quando `bancoPago` é enviado. A lista de bancos é conferida antes de existir uma linha de transação. Essa resposta não cria uma linha e não cancela nenhuma. `502` `VE_INBOUND_PROVIDER_CREATE_FAILED` e `502` `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` significam que a linha já existe, essa linha é cancelada e a resposta é `502`.

## Status da conta

A conta deve estar **`Operativa`** e em **USDT**. **`Bloqueada`** ou **`Cerrada`** retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. **`Restringida`** retorna `403` com `code: RESTRICTED`.


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