Skip to main content

​
Visão geral

A Argentina é o mercado principal da HG.Cash para transferências bancárias em ARS. A HG.Cash atribui contas bancárias aos seus usuários na plataforma. Quando há movimentação nessas contas—cash-in (entrada) ou cash-out (saída)—a HG.Cash notifica seu backend na URL de webhook configurada nas definições da conta. Para cash-outs, você inicia transferências bancárias instantâneas pela API. Para cash-ins, não cria recebimentos pela API; a HG.Cash detecta movimentos nas contas atribuídas e os envia ao seu webhook.

​
Como funciona

  1. Contas — A HG.Cash provisiona contas ARS (CBU/CVU) vinculadas ao seu usuário. Use GET /api/v1/accounts e GET /api/v1/account/{id}/balance para saldos e status.
  2. Cash-in — Transferências recebidas são registradas e enviadas ao seu webhook (movimentos de conta / ledger).
  3. Cash-out — Chame POST /api/v1/transactions para solicitar um cash-out bancário instantâneo para CBU ou CVU do beneficiário. Atualizações de status chegam por webhook (e opcionalmente webhookUrl por solicitação).
Configure a URL de webhook e o segredo de assinatura em Configurações da HG.Cash. Veja Recebimento de webhooks para payloads, HMAC e tentativas.

​
Cash-outs (transferências instantâneas)

Pagamentos de saída são solicitações de transação para CBU ou CVU do beneficiário. A HG.Cash processa solicitações elegíveis como cash-outs bancários instantâneos quando a conta e os limites permitem.

​
Pré-requisitos

  • Token Bearer com acesso à conta ARS
  • CBU ou CVU do beneficiário (22 dígitos)
  • Saldo líquido suficiente na conta de origem para o valor da transferência mais a taxa de saída
A HG.Cash calcula a taxa de saída ao criar uma solicitação de transação (painel ou POST /api/v1/transactions). A solicitação é rejeitada se amount + outboundFee exceder netBalance (balance - pendingFees de GET /api/v1/account/{id}/balance). Por exemplo, com netBalance de 1.000.000 ARS e taxa de saída de 1%, o máximo que você pode sacar em uma solicitação é 990.000 ARS — não o saldo integral. Se a conta não cobrir valor e taxa, a API retorna 409 com code: INSUFFICIENT_NET_BALANCE e um objeto details com outboundFee, requiredTotal, netBalance e maxWithdrawableAmount.

​
Fluxo

  1. Opcional: confirme saldo com GET /api/v1/accounts ou GET /api/v1/account/{id}/balance
  2. POST /api/v1/transactions — accountId, amount, toCBU ou toCVU
  3. Acompanhe com GET /api/v1/transaction/{id}/status, webhook do painel ou webhookUrl na solicitação
  4. Quando o processamento terminar, resolva a linha de ledger com GET /api/v1/transaction-requests/{id}/transaction-id ({ "transactionId": "<uuid>" } ou null enquanto não vinculada) ou aguarde o webhook Solicitação de transação associada (topic TRANSACTION_REQUEST, eventType transaction_associated)

​
Exemplo

A resposta inclui id e status inicial (por exemplo PENDING). Use webhooks ou polling até um estado terminal.

​
Erro de saldo insuficiente

Quando o valor solicitado mais a taxa de saída excede netBalance, a HG.Cash retorna 409:
Use maxWithdrawableAmount do erro (ou consulte o endpoint de saldo antes) para tentar novamente com um amount menor.

​
Endpoints relacionados

  • GET /api/v1/transaction-requests/{id}/transaction-id — ID da transação de ledger vinculada (null enquanto processa)
  • GET /api/v1/alias-lookup — resolver alias para CBU/CVU (se habilitado)
  • GET /api/v1/transaction-statuses e GET /api/v1/transaction-types — dados de referência (sem autenticação)