> ## 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 solicitação de transação (Cash Out) > Cria uma nova solicitação de transação a partir de uma das suas contas. Isso não executa uma transferência bancária imediata. Você pode informar um `webhookUrl` para receber atualizações de status. ## 📝 Campos obrigatórios - `accountId`: ID da sua conta a debitar - `toCBU` ou `toCVU`: CBU/CVU do destinatário (22 dígitos) - `amount`: Número decimal positivo - `webhookUrl` opcional: URL para receber atualizações de status ## 🔍 Regras de validação - A conta deve pertencer ao usuário autenticado - O CBU deve ser um número válido de 22 dígitos - O `externalID` opcional deve ser único por conta, se informado ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /transactions 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: /transactions: post: tags: - Transações summary: Criar solicitação de transação (Cash Out) description: > Cria uma nova solicitação de transação a partir de uma das suas contas. Isso não executa uma transferência bancária imediata. Você pode informar um `webhookUrl` para receber atualizações de status. ## 📝 Campos obrigatórios - `accountId`: ID da sua conta a debitar - `toCBU` ou `toCVU`: CBU/CVU do destinatário (22 dígitos) - `amount`: Número decimal positivo - `webhookUrl` opcional: URL para receber atualizações de status ## 🔍 Regras de validação - A conta deve pertencer ao usuário autenticado - O CBU deve ser um número válido de 22 dígitos - O `externalID` opcional deve ser único por conta, se informado operationId: createTransactionRequest requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Transaction' examples: basic_request_cbu: summary: Solicitação básica description: >- Campos mínimos obrigatórios para uma solicitação de transferência de saída value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCBU: '1100015400000000000021' amount: 15000.5 basic_request_cvu: summary: Solicitação básica com CVU description: Campos mínimos obrigatórios usando destino CVU value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCVU: '0000003100012345678901' amount: 15000.5 complete_request: summary: Solicitação completa com webhook description: >- Solicitação de transferência de saída com metadados opcionais e URL de webhook para atualizações de status value: accountId: 550e8400-e29b-41d4-a716-446655440123 toCBU: '1100015400000000000021' amount: 25000 toName: María García toCUIT: 27987654321 concept: Payment for consulting services externalDate: '2024-06-19T10:30:00Z' coelsaCode: COELSA123456 data: reference: REF-001 category: services client_id: CLIENT-789 webhookUrl: https://client.example.com/webhooks/transaction-request responses: '201': description: Solicitação de transação criada com sucesso content: application/json: schema: $ref: '#/components/schemas/TransactionRequestResponse' examples: success: summary: Criação bem-sucedida value: id: 789e0123-e89b-12d3-a456-426614174999 externalID: REQ-2024-001234 createdAt: '2024-06-19T10:30:00Z' status: PENDING '400': description: Requisição inválida — dados fornecidos inválidos content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Erro de validação value: error: Validation failed message: The provided data is invalid details: amount: Amount must be positive currency: Currency must be 3 letters '401': description: Não autorizado — token inválido ou ausente content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Token ausente value: error: Authentication required message: Bearer token is required invalid_token: summary: Token inválido value: error: Invalid token message: The provided token is invalid or expired '403': description: Proibido — a conta não pertence ao usuário autenticado content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden_account: summary: Acesso à conta negado value: error: You do not have access to this account '404': description: Não encontrado '409': description: Conflito — a solicitação não pode ser criada content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate_external_id: summary: ID externo duplicado value: error: >- Transaction request with this external ID already exists for this account code: DUPLICATE_EXTERNAL_ID message: The provided externalID already exists for this account insufficient_net_balance: summary: Saldo líquido insuficiente description: >- Rejeitado porque o saldo líquido (saldo - taxas pendentes) é menor que o valor solicitado value: error: Insufficient net balance code: INSUFFICIENT_NET_BALANCE message: >- Net available balance (balance - pending fees) is not enough to cover the requested amount details: accountId: 550e8400-e29b-41d4-a716-446655440123 currency: ARS amount: 15000.5 balance: 12000 pendingFees: 2000 netBalance: 10000 '500': description: Erro interno do servidor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: server_error: summary: Erro do servidor value: error: Internal server error message: An unexpected error occurred components: schemas: Transaction: type: object description: Solicitação de criação de transação de saída por um usuário required: - accountId - amount properties: accountId: type: string format: uuid description: ID da conta do usuário de onde enviar os fundos example: 550e8400-e29b-41d4-a716-446655440123 fromName: type: string description: Nome do remetente da transação example: Juan Pérez maxLength: 255 toName: type: string description: Nome do destinatário da transação example: María García maxLength: 255 fromCBU: type: number description: CBU (número da conta bancária) do remetente example: 170001540000000020000 toCBU: type: string description: CBU do destinatário (22 dígitos). Informe toCBU ou toCVU. example: '1100015400000000000021' toCVU: type: string description: CVU do destinatário (22 dígitos). Informe toCBU ou toCVU. example: '0000003100012345678901' amount: type: number format: decimal description: Valor da transação (deve ser positivo) example: 15000.5 fromCUIT: type: number description: CUIT/CUIL do remetente example: 20123456789 toCUIT: type: number description: CUIT/CUIL do destinatário example: 27987654321 concept: type: string description: Conceito ou descrição da transação example: Payment for services maxLength: 500 externalDate: type: string format: date-time description: Data da transação no seu sistema (formato ISO 8601) example: '2024-06-19T10:30:00Z' coelsaCode: type: string description: Código de transação Coelsa example: COELSA123456 maxLength: 100 data: type: object description: Dados JSON adicionais da transação example: reference: REF-001 category: services metadata: source: mobile_app version: 1.2.3 webhookUrl: type: string format: uri description: >- URL de webhook opcional para receber atualizações de status desta solicitação example: https://client.example.com/webhooks/transaction-request TransactionRequestResponse: type: object properties: id: type: string format: uuid description: ID interno da solicitação de transação example: 789e0123-e89b-12d3-a456-426614174999 externalID: type: string example: REQ-2024-001234 createdAt: type: string format: date-time example: '2024-06-19T10:30:00Z' status: type: string enum: - PENDING - AWAITING_REVIEW - PROCESSING - DONE - ERROR - CANCELLED example: PENDING ErrorResponse: type: object description: Payload de erro retornado pela API. additionalProperties: true required: - error properties: error: type: string example: Invalid request code: type: string description: Código de erro legível por máquina (quando disponível) example: INSUFFICIENT_NET_BALANCE message: type: string example: The provided data is invalid details: type: object description: Detalhes adicionais do erro example: field: amount code: INVALID_VALUE 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`. ````