Criar cobrança Pix

Crie uma cobrança Pix e receba na resposta o QR Code copia e cola para exibir ao pagador.

POST/v1/charges

Autentique com a sua chave secreta. A cobrança nasce com status pending e vira paid quando o pagamento é confirmado (no sandbox, via simulate-payment; em produção, pela confirmação do Banco).

Parâmetros do corpo

Parâmetro	Tipo	Descrição
`amount_cents`obrigatório	integer	Valor em centavos, maior que zero. Ex.: 1990 = R$ 19,90.
`description`	string	Descrição livre da cobrança para o seu controle.
`method`	string	Método de pagamento. Hoje só "pix" existe — é o padrão se omitido.
`currency`	string	Moeda. Hoje só "BRL" existe — é o padrão se omitido.
`external_reference`	string	O id do SEU pedido. A CarecaPay só guarda e devolve de volta (aqui, na consulta e no webhook) — não interpreta o valor.

Exemplo de requisição

cURL

curl -X POST https://api-sandbox.carecapay.com/v1/charges \
  -H "Authorization: Bearer SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 1990,
    "description": "Assinatura Premium",
    "external_reference": "order_42"
  }'

method e currency são opcionais — omita para "pix"/"BRL" (únicos disponíveis hoje). Passe explicitamente se preferir deixar o contrato claro no seu código; qualquer outro valor devolve 400 (invalid_method / invalid_currency).

Exemplo de resposta

201 Created

{
  "id": "txn_8f2c1a9b",
  "status": "pending",
  "method": "pix",
  "amount_cents": 1990,
  "currency": "BRL",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "provider_charge_id": "b6f0e3...",
  "external_reference": "order_42",
  "created_at": "2026-07-09T12:00:00Z"
}

Exiba o qr_code (payload copia e cola do Pix) no seu checkout — qualquer app bancário compatível com Pix consegue ler. Prefere não gerar a imagem do QR você mesmo? Use qr_code_base64: é a mesma informação já renderizada em PNG (base64), pronta pra um <img src="data:image/png;base64,...">.

amount_cents menor ou igual a zero devolve 400 (invalid_amount). Campos desconhecidos no corpo também devolvem 400 (invalid_body).

Próximos passos

Consulte o status com GET /v1/charges/{id} para saber quando foi paga.
No sandbox, simule a baixa com POST /v1/charges/{id}/simulate-payment.
Acompanhe o total recebido em GET /v1/balance.