> ## 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. # Obter status da transação (Venezuela) > Lê o status de entrada ou de saída. `amount` é uma string decimal USDT. `status` inclui `pending_kyc`. `externalID` é omitido até o id da ordem existir, e então é retornado. Campos opcionais, somente quando presentes: `orden_id`, `montoFiat`, `tasaCompra`, `banco` e `numero_cuenta` somente de entrada, `kyc_url` de saída, e `kyc_expires_at` enquanto a retenção `pending_kyc` continua aberta. `feeBreakdown`, quando existe um detalhamento, omite `flatFee.source`. Em um payout cancelado porque a verificação de identidade era exigida, `kyc_url` entra somente quando uma URL não vazia foi armazenada. `cancelledReason` entra somente para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` ou `VE_KYC_REQUIRED`. Outros motivos de cancelamento são omitidos. O webhook `status_change` do comerciante inclui `cancelledReason` somente para esses mesmos três códigos. Uma transação que não é uma movimentação da Venezuela retorna `400`. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml get /ve/transactions/{id}/status 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/{id}/status: get: tags: - Venezuela summary: Obter status da transação (Venezuela) description: > Lê o status de entrada ou de saída. `amount` é uma string decimal USDT. `status` inclui `pending_kyc`. `externalID` é omitido até o id da ordem existir, e então é retornado. Campos opcionais, somente quando presentes: `orden_id`, `montoFiat`, `tasaCompra`, `banco` e `numero_cuenta` somente de entrada, `kyc_url` de saída, e `kyc_expires_at` enquanto a retenção `pending_kyc` continua aberta. `feeBreakdown`, quando existe um detalhamento, omite `flatFee.source`. Em um payout cancelado porque a verificação de identidade era exigida, `kyc_url` entra somente quando uma URL não vazia foi armazenada. `cancelledReason` entra somente para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` ou `VE_KYC_REQUIRED`. Outros motivos de cancelamento são omitidos. O webhook `status_change` do comerciante inclui `cancelledReason` somente para esses mesmos três códigos. Uma transação que não é uma movimentação da Venezuela retorna `400`. operationId: getVeTransactionStatus parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Status da transação content: application/json: schema: $ref: '#/components/schemas/VenezuelaTransactionStatus' examples: inbound: summary: Cash-in com instruções de cobrança value: id: 550e8400-e29b-41d4-a716-446655440000 externalID: '1000' status: pending direction: Inbound amount: '100.5' currency: USDT orden_id: 1000 banco: ONRAMP_BANK_NAME numero_cuenta: '00000000000000000000' pending_kyc: summary: Payout retido para verificação de identidade value: id: 550e8400-e29b-41d4-a716-446655440000 status: pending_kyc direction: Outbound amount: '25.5' currency: USDT kyc_url: https://example.com/verify kyc_expires_at: '2026-01-02T00:00:00.000Z' cancelled: summary: Payout cancelado por um motivo público value: id: 550e8400-e29b-41d4-a716-446655440000 status: cancelled direction: Outbound amount: '25.5' currency: USDT cancelledReason: VE_KYC_EXPIRED '400': description: >- Falta o id da transação, ou a transação não aceita consulta de status content: application/json: schema: type: object required: - error properties: error: type: string examples: unsupported: value: error: Transaction is not supported for status polling missing_id: value: error: Transaction ID is required '401': description: Não autorizado '404': description: Transação não encontrada '500': description: Erro interno do servidor components: schemas: VenezuelaTransactionStatus: type: object required: - id - status - direction - amount - currency properties: id: type: string format: uuid externalID: type: string description: >- Omitido até o id da ordem existir. Retornado quando já é esse id de ordem. status: type: string description: >- Status atual do ledger. Inclui `pending` para o cash-in, `processing` quando um payout é aceito, `pending_kyc` enquanto a verificação de identidade retém um payout, `done` e `cancelled`. direction: type: string enum: - Inbound - Outbound amount: $ref: '#/components/schemas/VenezuelaUsdtAmount' currency: type: string example: USDT orden_id: type: integer description: Incluído somente quando presente. montoFiat: type: string description: Metadado em VES. Incluído somente quando presente. tasaCompra: type: string description: Metadado em VES. Incluído somente quando presente. banco: type: string description: Banco de cobrança, somente de entrada. Nunca retornado em um payout. numero_cuenta: type: string description: >- Número da conta de cobrança, somente de entrada. Nunca retornado em um payout. kyc_url: type: string description: >- Somente de saída. Incluído quando uma URL não vazia foi armazenada, inclusive se um payout foi cancelado porque a verificação de identidade era exigida. kyc_expires_at: type: string format: date-time description: Incluído enquanto a retenção `pending_kyc` continua aberta. cancelledReason: type: string description: >- Incluído somente para `VE_KYC_EXPIRED`, `VE_KYC_DECLINED` ou `VE_KYC_REQUIRED`. Outros motivos de cancelamento são omitidos. enum: - VE_KYC_EXPIRED - VE_KYC_DECLINED - VE_KYC_REQUIRED feeBreakdown: $ref: '#/components/schemas/VenezuelaStatusFeeBreakdown' 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' VenezuelaStatusFeeBreakdown: type: object description: >- Detalhamento de taxa opcional no status da Venezuela. Valores e taxas são strings decimais. Omitido quando não há detalhamento. `flatFee` inclui apenas `amount`. Esta resposta não inclui `flatFee.source`. properties: platformFee: type: object properties: amount: type: string rate: type: string nullable: true transactionFee: type: object properties: amount: type: string rate: type: string nullable: true flatFee: type: object properties: amount: type: string collectedAmount: type: string 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.