> ## 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 (Brasil) > Cria uma cobrança para receber um pagamento. Retorna dados de QR/copia e cola PIX para o pagador. A conta deve ser Brasil (BRL). A transação inicia em `pending` até a confirmação do pagamento. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /br/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: Checkouts description: Sessões de checkout hospedado para AR, BR, CL e BO paths: /br/transactions/inbound: post: tags: - Brasil summary: Criar transação de entrada (Brasil) description: > Cria uma cobrança para receber um pagamento. Retorna dados de QR/copia e cola PIX para o pagador. A conta deve ser Brasil (BRL). A transação inicia em `pending` até a confirmação do pagamento. operationId: createBrInboundTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InboundTransactionRequest' responses: '201': description: Transação criada content: application/json: schema: $ref: '#/components/schemas/InboundTransactionResponse' '400': description: Requisição inválida '401': description: Não autorizado '403': description: Proibido '404': description: Conta não encontrada '502': description: > Não foi possível concluir a operação de pagamento ou a resposta foi inválida/incompleta (por exemplo, sem `txid`). Corpo: `error`, `code`, `type` (veja `BrazilProviderError`). content: application/json: schema: $ref: '#/components/schemas/BrazilProviderError' components: schemas: InboundTransactionRequest: type: object description: >- Solicitação para criar uma transação de entrada (cobrança) em contas BRL do Brasil required: - accountId - amount - email - document properties: accountId: type: string format: uuid description: ID da conta que receberá os fundos amount: type: number format: decimal description: Valor a receber (positivo) email: type: string format: email description: E-mail do pagador para a cobrança document: type: string description: CPF ou CNPJ do pagador (somente dígitos, ou com pontuação) webhookUrl: type: string format: uri description: URL opcional para receber atualizações de status InboundTransactionResponse: type: object required: - id - status properties: id: type: string format: uuid description: ID da transação HG.Cash qrCode: type: string description: String do QR code para o pagador escanear (base64 ou string PIX) pixCopiaECola: type: string description: String PIX copia e cola (alternativa ao QR code) status: type: string enum: - pending 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`. ````