> ## 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 (Colômbia) > Cria um payout em COP a partir de uma conta COP operativa. Omita `destinationType` ou envie `bank` para Fast Pay / ACH. Envie `breb_key` ou `breb_qr` para Bre-B. O sucesso é `201` com `id` e `status: processing`. O valor mais a taxa de saída precisa caber no saldo líquido, ou a API retorna `409` com `code: INSUFFICIENT_NET_BALANCE`. Uma conta que não é COP retorna `400`. `Bloqueada` ou `Cerrada` retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /co/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: 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: /co/transactions/outbound: post: tags: - Colômbia summary: Criar transação de saída (Colômbia) description: > Cria um payout em COP a partir de uma conta COP operativa. Omita `destinationType` ou envie `bank` para Fast Pay / ACH. Envie `breb_key` ou `breb_qr` para Bre-B. O sucesso é `201` com `id` e `status: processing`. O valor mais a taxa de saída precisa caber no saldo líquido, ou a API retorna `409` com `code: INSUFFICIENT_NET_BALANCE`. Uma conta que não é COP retorna `400`. `Bloqueada` ou `Cerrada` retorna `403` com `code: ACCOUNT_NOT_OPERATIVE`. `Restringida` retorna `403` com `code: RESTRICTED`. operationId: createCoOutboundTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundRequest' examples: bank: summary: Payout bancário value: accountId: YOUR_ACCOUNT_UUID amount: '50000.00' accountType: cc bankCode: '1001' accountNumber: '0000000001' beneficiaryFullName: Ana Ejemplo documentType: cc documentNumber: '1000000000' brebKey: summary: Chave Bre-B value: destinationType: breb_key accountId: YOUR_ACCOUNT_UUID amount: '25000.00' keyValue: '@EXAMPLEKEY' beneficiaryFullName: Ana Ejemplo documentType: cc documentNumber: '1000000000' email: payer@example.com brebQr: summary: QR Bre-B value: destinationType: breb_qr accountId: YOUR_ACCOUNT_UUID amount: '15000.00' qrValue: 000201010212EXAMPLEQR responses: '201': description: Payout aceito content: application/json: schema: $ref: '#/components/schemas/ColombiaOutboundResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 status: processing '400': description: > Validação falhou, a moeda da conta não é COP, a conta não aceita esta operação, ou o valor do QR Bre-B não coincide (`code: BREB_QR_AMOUNT_MISMATCH`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ColombiaValidationError' - $ref: '#/components/schemas/ColombiaBrebQrAmountMismatch' - type: object required: - error properties: error: type: string example: Account currency must be COP for this operation '401': description: Não autorizado '403': description: >- A conta não está operativa (`Bloqueada` ou `Cerrada`) ou está restrita (`Restringida`) content: application/json: schema: $ref: '#/components/schemas/ColombiaAccountStatusError' examples: notOperative: summary: A conta não está operativa value: error: Account is not operative code: ACCOUNT_NOT_OPERATIVE restricted: summary: A conta está restrita value: error: Account is restricted code: RESTRICTED '404': description: Conta não encontrada '409': description: O valor mais a taxa de saída excede o saldo líquido content: application/json: schema: $ref: '#/components/schemas/ColombiaInsufficientNetBalance' '500': description: Erro interno do servidor '502': description: Não foi possível concluir este payout com o provedor de pagamento content: application/json: schema: $ref: '#/components/schemas/ColombiaProviderError' example: error: Unable to complete this payout with the payment provider. code: CO_OUTBOUND_PROVIDER_CREATE_FAILED type: provider_error components: schemas: ColombiaOutboundRequest: type: object description: > Payout de saída em COP. Omita `destinationType` ou envie `bank` para Fast Pay / ACH. Banco exige `accountType`, `bankCode`, `accountNumber` (máx. 20), `beneficiaryFullName`, `documentType` e `documentNumber`. O banco precisa aceitar Fast Pay ou ACH e o tipo de conta escolhido. `breb_key` exige `keyValue`, `beneficiaryFullName`, `documentType` e `documentNumber`. Não envie campos bancários. `breb_qr` exige `qrValue` (EMV ou base64). Beneficiário e documento são opcionais. Se o QR tiver um valor fixo, `amount` precisa coincidir ou a API retorna `400` com `code: BREB_QR_AMOUNT_MISMATCH`. required: - accountId - amount properties: destinationType: type: string enum: - bank - breb_key - breb_qr description: O padrão é `bank` quando omitido accountId: type: string format: uuid example: YOUR_ACCOUNT_UUID amount: description: Valor positivo. Strings aceitam no máximo 2 casas decimais. oneOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d{1,2})?$ accountType: type: string enum: - cc - ch - dp description: >- Obrigatório para banco. `cc` corrente, `ch` poupança, `dp` depósito eletrônico. bankCode: type: string pattern: ^\d{4}$ description: Obrigatório para banco. Código de 4 dígitos de GET /co/banks. accountNumber: type: string maxLength: 20 description: Obrigatório para banco beneficiaryFullName: type: string description: Obrigatório para banco e chave Bre-B. Opcional para QR Bre-B. documentType: $ref: '#/components/schemas/ColombiaDocumentType' documentNumber: type: string keyValue: type: string description: Obrigatório para `breb_key` qrValue: type: string description: Obrigatório para `breb_qr`. Payload EMV ou base64. phone: type: string description: Telefone E.164 opcional. Obrigatório quando `documentType` é `nd`. example: '+570000000000' email: type: string format: email example: payer@example.com description: type: string maxLength: 40 webhookUrl: type: string format: uri ColombiaOutboundResponse: type: object required: - id - status properties: id: type: string format: uuid status: type: string enum: - processing ColombiaValidationError: 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 ColombiaBrebQrAmountMismatch: type: object required: - error - code properties: error: type: string example: Bre-B QR amount does not match the amount encoded in the QR code: type: string enum: - BREB_QR_AMOUNT_MISMATCH details: type: object properties: qrAmountCents: type: integer requestedAmountCents: type: integer ColombiaAccountStatusError: type: object required: - error - code properties: error: type: string code: type: string enum: - ACCOUNT_NOT_OPERATIVE - RESTRICTED ColombiaInsufficientNetBalance: type: object required: - error - code properties: error: type: string example: Insufficient balance to cover transfer and fee code: type: string enum: - INSUFFICIENT_NET_BALANCE details: type: object ColombiaProviderError: type: object required: - error - code - type description: >- Erro quando um payout da Colômbia não pode ser concluído ou o status não pode ser atualizado properties: error: type: string code: type: string description: >- CO_OUTBOUND_PROVIDER_CREATE_FAILED ou CO_TRANSACTION_STATUS_PROVIDER_ERROR type: type: string description: provider_error ColombiaDocumentType: type: string enum: - cc - nit - ce - pa - ppt - ti - rc - te - die - nd description: > `cc` cédula de cidadania, `nit` NIT, `ce` cédula de estrangeiro, `pa` passaporte, `ppt` PPT, `ti` carteira de identidade, `rc` registro civil, `te` carteira de estrangeiro, `die` documento de identificação estrangeiro, `nd` sem documento (Nequi). A maioria dos números é somente dígitos. Passaporte (`pa`) e PPT (`ppt`) são alfanuméricos. `nd` é só bancário e só para o código de banco `1507`. `documentNumber` deve ser `ND` e `phone` (E.164) é obrigatório. `nd` é rejeitado no Bre-B. 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.