> ## 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 saída (Venezuela) > Cria um payout em USDT. `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. Obrigatórios: `accountId`, `amount`, `firstName`, `lastName`, `email`, `documentoIdentidad`, `tipoDocumento`, `prefijoTelefono`, `numeroTelefono`, `direccion`, `ciudad`, `pais` (`VE`), `banco`, `tipoCuenta`, `numeroCuenta`, `nombreTitular`, `apellidoTitular`. Opcionais: `celular`, `webhookUrl`. `celular` é obrigatório quando `tipoCuenta` é Pago Móvil (`13`, `Pago Móvil` ou `pago_movil`). Envie `banco`, `tipoCuenta` e `tipoDocumento` como o `value` do catálogo de `GET /ve/banks`. Rótulos em texto são aceitos. `BANK_VALUE` e `ACCOUNT_TYPE_VALUE` no exemplo são marcadores desses valores. `documentoIdentidad` é somente dígitos. A letra fica em `tipoDocumento` (`V`, `J`, `P` ou `E`). Um prefixo correspondente é removido. Saldo insuficiente retorna `409` com `{ error, code }` e `code: INSUFFICIENT_NET_BALANCE`. Se o destinatário ainda precisa de verificação de identidade, a resposta é `201` com `status: pending_kyc`, `kyc_url` quando uma URL foi armazenada, e `kyc_expires_at` (24 horas a partir da criação). Esse valor e a taxa de saída ficam reservados. O saldo da conta não é debitado. Nenhuma ordem de payout é criada até a verificação ser aprovada. Verificação aprovada com uma conta bancária utilizável retorna `201` com `status: processing`. Verificação recusada, verificação que terminou sem aprovação, um e-mail cujo documento não corresponde, um documento rejeitado ou uma conta bancária rejeitada não cria uma transação e retorna `400` com `code` `VE_KYC_DECLINED`, `VE_KYC_NOT_APPROVED`, `VE_IDENTITY_UNCONFIRMED`, `VE_INVALID_DOCUMENT`, `VE_INVALID_BANK`, `missing_cuenta_id` ou `missing_terms`. `missing_cuenta_id` significa que não foi possível salvar a conta do payout. Confira `numeroCuenta` e tente de novo. `missing_terms` significa que não foi possível preparar o destinatário. Tente novamente em breve. A string `error` diz o que corrigir em uma falha de conta bancária ou de documento. 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/outbound 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/outbound: post: tags: - Venezuela summary: Criar transação de saída (Venezuela) description: > Cria um payout em USDT. `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. Obrigatórios: `accountId`, `amount`, `firstName`, `lastName`, `email`, `documentoIdentidad`, `tipoDocumento`, `prefijoTelefono`, `numeroTelefono`, `direccion`, `ciudad`, `pais` (`VE`), `banco`, `tipoCuenta`, `numeroCuenta`, `nombreTitular`, `apellidoTitular`. Opcionais: `celular`, `webhookUrl`. `celular` é obrigatório quando `tipoCuenta` é Pago Móvil (`13`, `Pago Móvil` ou `pago_movil`). Envie `banco`, `tipoCuenta` e `tipoDocumento` como o `value` do catálogo de `GET /ve/banks`. Rótulos em texto são aceitos. `BANK_VALUE` e `ACCOUNT_TYPE_VALUE` no exemplo são marcadores desses valores. `documentoIdentidad` é somente dígitos. A letra fica em `tipoDocumento` (`V`, `J`, `P` ou `E`). Um prefixo correspondente é removido. Saldo insuficiente retorna `409` com `{ error, code }` e `code: INSUFFICIENT_NET_BALANCE`. Se o destinatário ainda precisa de verificação de identidade, a resposta é `201` com `status: pending_kyc`, `kyc_url` quando uma URL foi armazenada, e `kyc_expires_at` (24 horas a partir da criação). Esse valor e a taxa de saída ficam reservados. O saldo da conta não é debitado. Nenhuma ordem de payout é criada até a verificação ser aprovada. Verificação aprovada com uma conta bancária utilizável retorna `201` com `status: processing`. Verificação recusada, verificação que terminou sem aprovação, um e-mail cujo documento não corresponde, um documento rejeitado ou uma conta bancária rejeitada não cria uma transação e retorna `400` com `code` `VE_KYC_DECLINED`, `VE_KYC_NOT_APPROVED`, `VE_IDENTITY_UNCONFIRMED`, `VE_INVALID_DOCUMENT`, `VE_INVALID_BANK`, `missing_cuenta_id` ou `missing_terms`. `missing_cuenta_id` significa que não foi possível salvar a conta do payout. Confira `numeroCuenta` e tente de novo. `missing_terms` significa que não foi possível preparar o destinatário. Tente novamente em breve. A string `error` diz o que corrigir em uma falha de conta bancária ou de documento. 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: 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` do catálogo em `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` do catálogo em `country.banks`. Marcador `BANK_VALUE`. oneOf: - type: string - type: integer minimum: 1 example: BANK_VALUE tipoCuenta: description: >- `value` do catálogo em `country.accountTypes`. Marcador `ACCOUNT_TYPE_VALUE`. `celular` é obrigatório para Pago Móvil (`13`, `Pago Móvil` ou `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: Obrigatório 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` quando a verificação está aprovada e há uma conta bancária utilizável. `pending_kyc` quando a verificação ainda é necessária. O valor e a taxa de saída ficam reservados. O saldo não é debitado e nenhuma ordem de payout é criada até a verificação ser aprovada. `kyc_expires_at` é 24 horas a partir da criação. content: application/json: schema: $ref: '#/components/schemas/VenezuelaOutboundCreated' examples: processing: summary: Payout aceito value: id: 550e8400-e29b-41d4-a716-446655440000 status: processing pending_kyc: summary: Retido para verificação de identidade 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: >- A validação falhou, a conta não é USDT da Venezuela, ou o destinatário foi rejeitado antes de criar uma transação. 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: 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: 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: Conta não encontrada '409': description: Saldo líquido insuficiente para o valor e a taxa de saída content: application/json: schema: $ref: '#/components/schemas/VenezuelaInsufficientNetBalance' '500': description: >- Erro interno do servidor. Um payout salvo como `processing` pode retornar `Failed to enqueue outbound processing` se o envio não pôde ser enfileirado. 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' 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: Incluído em `pending_kyc` somente quando uma URL foi armazenada. kyc_expires_at: type: string format: date-time description: Presente em `pending_kyc`. 24 horas a partir da criação. 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: >- Devolvido quando um payout ou a verificação do destinatário é rejeitado antes de existir uma transação. A string `error` diz o que corrigir em uma falha de conta bancária ou de 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 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.