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

# Consultar status da transação (Brasil)

> Obtém o status atual de uma transação direta PIX (entrada ou saída) no Brasil.
Diferente de `GET /transaction/{id}/status`, que retorna o status de uma **solicitação** de transação.




## OpenAPI

````yaml /api-reference/openapi.pt-BR.yaml get /br/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=<hex>` 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: Checkouts
    description: Sessões de checkout hospedado para AR, BR, CL e BO
paths:
  /br/transactions/{id}/status:
    get:
      tags:
        - Brasil
      summary: Consultar status da transação (Brasil)
      description: >
        Obtém o status atual de uma transação direta PIX (entrada ou saída) no
        Brasil.

        Diferente de `GET /transaction/{id}/status`, que retorna o status de uma
        **solicitação** de transação.
      operationId: getBrTransactionStatus
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID da transação
      responses:
        '200':
          description: Status da transação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectTransactionStatus'
        '401':
          description: Não autorizado
        '404':
          description: Transação não encontrada
        '502':
          description: |
            Não foi possível consultar o status da transação.
            Corpo: `error`, `code`, `type` (veja `BrazilProviderError`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrazilProviderError'
components:
  schemas:
    DirectTransactionStatus:
      type: object
      description: Status de uma transação direta (entrada ou saída)
      properties:
        id:
          type: string
          format: uuid
        externalID:
          type: string
        status:
          type: string
          enum:
            - pending
            - done
            - expired
            - cancelled
        direction:
          type: string
          enum:
            - Inbound
            - Outbound
        amount:
          type: string
        currency:
          type: string
    BrazilProviderError:
      type: object
      required:
        - error
        - code
        - type
      description: >
        Erro relacionado à operação de pagamento PIX (Brasil). O corpo é seguro
        para o cliente:

        não expõe detalhes internos nem um segundo campo `message`. Use `code` e
        `type` na sua integração.
      properties:
        error:
          type: string
          description: Mensagem legível para exibir ou registrar no cliente
        code:
          type: string
          description: >
            Código estável para integração. Exemplos:
            `BR_INBOUND_PROVIDER_CREATE_FAILED`,

            `BR_INBOUND_PROVIDER_MISSING_TXID`,
            `BR_TRANSACTION_STATUS_PROVIDER_ERROR`.
        type:
          type: string
          description: >
            Categoria do erro. Exemplos: `provider_error` (falha ao criar ou
            consultar a operação),

            `provider_invalid_response` (HTTP 200 mas resposta incompleta, por
            exemplo sem identificador PIX).
  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`.

````