Criar Cobrança

Cria uma nova cobrança Pix via PSP configurado. Retorna o Pix copia-e-cola e o QR code em base64.

Headers

Body

Exemplos

curl https://api.hubpay.dev/v1/charges \
  -X POST \
  -H "Authorization: Bearer hpx_test_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 5000,
    "provider": "asaas",
    "description": "Pedido #1234",
    "payer": {
      "name": "Maria Souza",
      "document": "12345678901",
      "email": "maria@exemplo.com"
    },
    "metadata": {
      "order_id": "1234"
    }
  }'

Resposta 201

{
  "id": "chg_a1b2c3d4e5f6...",
  "object": "charge",
  "status": "pending",
  "amount": 5000,
  "currency": "BRL",
  "description": "Pedido #1234",
  "provider": "asaas",
  "environment": "test",
  "pix": {
    "copy_paste": "00020126580014br.gov.bcb.pix...",
    "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "payer": {
    "name": "Maria Souza",
    "document": "12345678901",
    "email": "maria@exemplo.com"
  },
  "metadata": { "order_id": "1234" },
  "expires_at": "2026-04-16T14:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-04-15T14:00:00.000Z",
  "updated_at": "2026-04-15T14:00:00.000Z"
}

Provider “random” — distribuição automática

Ao enviar "provider": "random", o Hubpay distribui automaticamente as cobranças entre todos os PSPs que você tem conectados, usando round-robin (rodízio sequencial por usuário).

Como funciona: com Asaas, Efí e Mercado Pago conectados, as requisições são roteadas em ordem alfabética: Asaas → Efí → Mercado Pago → Asaas → ...

Fallback automático: se o PSP selecionado retornar erro, o Hubpay tenta automaticamente o próximo da lista. Se todos falharem, retorna 502 psp_error.

Requisitos: pelo menos 2 PSPs ativos conectados no mesmo ambiente (test ou live). Com apenas 1 PSP, use o nome do provider diretamente — retorna 400 invalid_request caso contrário.

Quando "random" é usado, a resposta inclui o campo extra routing:

{
  "id": "chg_a1b2c3d4e5f6...",
  "status": "pending",
  "provider": "mercadopago",
  "routing": {
    "mode": "round_robin",
    "selected_provider": "mercadopago",
    "attempted_providers": ["asaas", "mercadopago"]
  },
  "pix": { "copy_paste": "00020126..." },
  ...
}

attempted_providers lista os PSPs tentados na ordem. Se tem um item, o primeiro funcionou. Se tem dois ou mais, houve fallback. O campo routing não aparece quando um provider específico é usado.

Limites de volume por PSP

Configure quanto cada PSP processa antes de passar pro próximo. O sistema preenche o PSP até o limite, zera o acumulado e avança automaticamente. O ciclo é contínuo.

Exemplo: PSP1 com limite R$ 10.000 e PSP3 com limite R$ 15.000. PSP1 recebe cobranças até atingir R$ 10.000, então o acumulado zera e o PSP3 assume. O PSP3 recebe até R$ 15.000, então zera e o ciclo volta pro PSP1.

Se nenhum PSP tem limite, o roteamento é round-robin simples (1 cobrança pra cada, alternando). Configure em Dashboard → PSPs → ações → Configurar roteamento.

Quando o PSP selecionado tem limite, o routing inclui o estado atual do ciclo:

{
  "routing": {
    "mode": "round_robin",
    "selected_provider": "asaas",
    "attempted_providers": ["asaas"],
    "volume": {
      "limit_cents": 1000000,
      "accumulated_cents": 450000,
      "remaining_cents": 550000
    }
  }
}

Você também pode desativar um PSP do roteamento (routeEnabled: false) sem desativá-lo por completo: cobranças com provider: "random" ignoram esse PSP, mas cobranças com provider: "<nome>" diretamente continuam funcionando.

Erros possíveis