POST/v1/charges

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

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer hpx_...`
`Content-Type`	Sim	`application/json`
`Idempotency-Key`	Não	UUID para garantir idempotência. Mesma key + mesmo body retorna a mesma cobrança.

Body

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor em centavos. Ex: `5000` = R$ 50,00
`provider`	string	Sim	`"asaas"` ou `"mercadopago"`
`description`	string	Não	Descrição da cobrança (max 500 chars)
`expires_in_seconds`	integer	Não	Expiração em segundos. Default: 86400 (24h)
`payer.name`	string	Não	Nome do pagador
`payer.document`	string	Não	CPF (11 dígitos) ou CNPJ (14 dígitos), só números
`payer.email`	string	Não	Email do pagador
`metadata`	object	Não	Dados livres. Ex: `{"order_id": "123"}`

Exemplos

bash

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

json

{
  "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"
}

Erros possíveis

Status	type	Quando
`400`	invalid_request	Body malformado ou campo inválido
`401`	unauthorized	API key ausente, inválida ou revogada
`402`	psp_not_configured	Nenhum PSP ativo para o ambiente/provider
`403`	forbidden	Quota do plano excedida ou conta suspensa
`409`	idempotency_conflict	Mesma Idempotency-Key com body diferente
`502`	psp_error	PSP retornou erro (detalhes em `message`)