> ## 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. # Criar transação de entrada (Venezuela) > Credita uma conta USDT operativa. `amount` é uma string decimal positiva, não 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. Se a integração de pagamento não estiver configurada, a API retorna `500` com `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, inclusive quando `bancoPago` é omitido, e nenhuma transação é criada. `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`. Obrigatórios: `accountId`, `amount`. Opcionais: `bancoPago`, `webhookUrl`. `bancoPago` deve ser um `onramp.banks[].name` exato de `GET /ve/banks`. 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`. O sucesso é `201` com `id`, `status: pending`, `amount`, `orden_id`, e `montoFiat` / `tasaCompra` somente quando a resposta de criação os inclui. Uma conta inexistente retorna `404`. Sem acesso retorna `403`. `Bloqueada` ou `Cerrada` retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. Uma conta incompatível ou uma moeda diferente de USDT retorna `400`. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /ve/transactions/inbound openapi: 3.1.0 info: title: HG.Cash API description: > # 🚀 API de transações HG.Cash API REST moderna para usuários criarem transações de saída a partir de suas contas. ## 🧾 Como funciona - A HG.Cash atribui contas ao seu usuário - Quando essas contas têm movimentação (entrada ou saída), a HG.Cash notifica o seu backend usando a URL de webhook configurada no painel - **Assinatura de webhooks (HMAC)**: Nas configurações da conta é possível gerar um segredo de assinatura. Quando configurado, cada POST de webhook inclui o cabeçalho `X-HG-Webhook-Signature: sha256=` com HMAC-SHA256 do corpo JSON usando o seu segredo. Verifique no seu endpoint para garantir autenticidade. - Para criar saques é necessário chamar o endpoint **Cash Out**: **Criar solicitação de transação** (`POST /transactions`) ## 📊 Primeiros passos 1. **Gere seu token de API** na página de configurações da conta 2. **Teste os endpoints** com a documentação interativa 3. **Implemente** nos seus serviços de backend (nunca exponha tokens no frontend) 4. **Monitore** a integração e trate erros adequadamente ## 🔐 Autenticação Esta API usa autenticação **Bearer Token**. Inclua o token de API do usuário no cabeçalho Authorization, por exemplo `Authorization: Bearer cash_your_token_here`. ## ⚠️ Segurança - Não compartilhe nem exponha o token de autenticação da API - Armazene tokens apenas em servidores backend seguros - Todas as chamadas devem ser feitas a partir de backends seguros - Se o token for comprometido, entre em contato com os administradores imediatamente 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 produção - url: http://dev.hg.cash/api/v1 description: Servidor de desenvolvimento security: - bearerAuth: [] tags: - name: Transações description: >- Gestão de transações — Criar e gerenciar transações no sistema HG.Cash. Todos os endpoints de transação exigem autenticação. - name: Contas description: >- Contas — Obter informações de conta e saldos do usuário autenticado. Todos os endpoints de conta exigem autenticação. - name: Dados de referência description: >- Dados de referência — Obter dados de referência como status e tipos de transação. Esses endpoints exigem autenticação. - name: Webhooks description: Webhooks — Notificações de eventos enviadas ao seu endpoint HTTP. - name: Brasil description: Brasil — Criar e consultar transações PIX (BRL). - name: Chile description: Chile — Checkout hospedado e payouts bancários (CLP). - name: Bolívia description: Bolívia — Cash-in com QR e payouts ACH (BOB). - name: Colômbia description: >- Colômbia — Cash-in com checkout hospedado e payouts bancários, chave Bre-B ou QR Bre-B (COP). - name: Venezuela description: Venezuela — Cash-in e payouts em USDT. - name: Checkouts description: Sessões de checkout hospedado para AR, BR, CL, BO e CO - name: Claims description: Reclamações com evidência de comprovante de transferência paths: /ve/transactions/inbound: post: tags: - Venezuela summary: Criar transação de entrada (Venezuela) description: > Credita uma conta USDT operativa. `amount` é uma string decimal positiva, não 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. Se a integração de pagamento não estiver configurada, a API retorna `500` com `code: VE_BANKS_PROVIDER_NOT_CONFIGURED`, inclusive quando `bancoPago` é omitido, e nenhuma transação é criada. `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`. Obrigatórios: `accountId`, `amount`. Opcionais: `bancoPago`, `webhookUrl`. `bancoPago` deve ser um `onramp.banks[].name` exato de `GET /ve/banks`. 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`. O sucesso é `201` com `id`, `status: pending`, `amount`, `orden_id`, e `montoFiat` / `tasaCompra` somente quando a resposta de criação os inclui. Uma conta inexistente retorna `404`. Sem acesso retorna `403`. `Bloqueada` ou `Cerrada` retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. Uma conta incompatível ou uma moeda diferente de USDT retorna `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` exato de `GET /ve/banks`. Não é o 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 criado 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: >- A validação falhou, a conta não é compatível, a moeda não é USDT, ou `bancoPago` não é um nome 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` não é um nome 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: A conta não é compatível value: error: Account is not supported for this operation currency: summary: A moeda não é USDT value: error: Account currency must be USDT for this operation '401': description: Não autorizado '403': description: >- Sem acesso, a conta está `Bloqueada` ou `Cerrada`, ou a conta 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: Sem acesso value: error: You do not have access to this account not_operative: summary: A conta não 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: Conta não encontrada content: application/json: schema: type: object required: - error properties: error: type: string example: Account not found '500': description: A integração de pagamento não está configurada, ou um erro 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` 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. `VE_INBOUND_PROVIDER_CREATE_FAILED` e `VE_INBOUND_PROVIDER_MISSING_ORDEN_ID` significam que a linha já existe, essa linha é cancelada e a resposta é 502. content: application/json: schema: $ref: '#/components/schemas/VenezuelaProviderError' examples: create_failed: summary: Não foi possível criar o 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: A resposta de criação não trouxe o id da ordem 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: >- A lista de bancos de entrada falhou antes de existir uma linha, somente quando bancoPago é enviado value: error: Unable to fetch banks from the payment provider. code: VE_BANKS_PROVIDER_ERROR type: provider_error components: schemas: VenezuelaUsdtAmount: type: string description: >- String decimal USDT positiva. Não é um número JSON. Mais de 8 dígitos fracionários são arredondados para baixo até 8 e não são rejeitados. Valores em VES não são 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: >- Metadado em VES. Incluído somente quando a resposta de criação o traz. tasaCompra: type: string description: >- Metadado em VES. Incluído somente quando a resposta de criação o traz. 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 autenticação da API do usuário com o formato `cash_<64-char-hex>`. Valor de exemplo `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.