Criar checkouts

​

Painel

1. Abra Checkouts na barra lateral (/app/checkouts).
2. Revise a linha de estatísticas e as sessões recentes no resumo.
3. Em Criar checkout, escolha país, conta (opcional — a HG.Cash escolhe uma conta operativa elegível se omitida), valor e URL de sucesso.
4. Clique em Criar checkout. Copie o link do checkout no painel de sucesso e envie ao pagador.

​

Notas por país (painel)

​

API

{
  "country": "AR",
  "amount": "1500.00",
  "successUrl": "https://merchant.example/success"
}

​

Argentina (AR)

• A resposta inclui accountDisplay (alias, CVU/CBU, titular).
• O pagador preenche nome, valor e DNI de 8 dígitos na página hospedada.
• Conclusão quando uma transferência de entrada coincide valor + DNI na conta atribuída.

​

Brasil (BR)

• payer.name, payer.document (CPF ou CNPJ — somente dígitos ou com pontuação) e payer.email obrigatórios na criação.
• A resposta pode incluir qrCode e pixCopiaECola.

​

Chile (CL)

• paymentMethodId e customer obrigatórios — veja Cash-in Chile para listar métodos de pagamento.

​

Bolívia (BO)

• payer.name, payer.document (CI ou documento do pagador) e payer.email obrigatórios na criação.
• A resposta pode incluir qrCode para o pagador escanear.

​

Colômbia (CO)

• Somente checkout hospedado. Não existe POST /api/v1/co/transactions/inbound. Veja Cash-in Colômbia.
• Obrigatório: country: "CO", amount e successUrl. Sem nome, documento ou e-mail do pagador.
• A HG configura os meios de pagamento disponíveis. A requisição de criação não os escolhe.
• A conta deve ser COP e Operativa.
• Opcional: accountId, cancelUrl, webhookUrl, metadata, reference, idempotencyKey, expiresInSeconds e locale.
• expiresInSeconds é opcional. O padrão é 86400 segundos. O máximo é 604800 segundos. locale é opcional e só aceita es ou en.
• A resposta inclui checkoutUrl e omite checkoutUrlProvider.
• GET /api/v1/checkouts, GET /api/v1/checkouts/{id} e POST /api/v1/checkouts/{id}/cancel omitem providerData para a Colômbia.
• O pagador abre checkoutUrl, conclui o pagamento e volta à página de sucesso da HG. Sua successUrl é usada somente depois que o pagamento é confirmado.
• Depois de expiresAt, o get e o list do comerciante ainda retornam status: pending. A sessão do pagador informa expired. Cancelar um checkout pendente ainda define cancelled.
• Bloqueada ou Cerrada retorna 403 com code: ACCOUNT_NOT_OPERATIVE. Restringida retorna 403 com code: RESTRICTED. Uma conta que não está pronta para o checkout retorna 400 com error: "Account is not ready for checkout".
• Uma conta que não é uma conta de checkout em COP retorna 400 com error: "Account is not supported for this checkout country". Isso é separado do 400 com error: "Account is not ready for checkout".
• Se a sessão hospedada não puder ser criada, a API retorna 502 com error: "Failed to create CO payment with provider".

​

Exemplo (Brasil)

curl -X POST https://hg.cash/api/v1/checkouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "amount": "100.50",
    "successUrl": "https://merchant.example/success",
    "payer": {
      "name": "Federico Autuori",
      "document": "957.937.532-14",
      "email": "fautuori@gmail.com"
    }
  }'

​

Exemplo (Bolívia)

curl -X POST https://hg.cash/api/v1/checkouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BO",
    "amount": "150.00",
    "successUrl": "https://merchant.example/success",
    "payer": {
      "name": "Juan Pérez",
      "document": "12345678",
      "email": "payer@example.com"
    }
  }'

​

Exemplo (Colômbia)

curl -X POST https://hg.cash/api/v1/checkouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CO",
    "accountId": "YOUR_ACCOUNT_UUID",
    "amount": "50000.00",
    "successUrl": "https://merchant.example/success"
  }'

​

Exemplo (Argentina)

curl -X POST https://hg.cash/api/v1/checkouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "AR",
    "amount": "1500.00",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "webhookUrl": "https://merchant.example/hooks/checkout",
    "metadata": { "orderId": "ORD-42" }
  }'

​

Relacionado

• Introdução — Status e webhooks
• Validar pagamentos
• Conciliar checkouts
• Referência da API → Checkouts → Create checkout session