Receber um Pix
Crie cobranças com QR Code e concilie pagamentos recebidos.
Para receber um Pix você cria uma cobrança, exibe o QR Code (ou copia-e-cola) ao pagador e aguarda a confirmação por webhook.
Variantes de cobrança
simple— QR estático, sem dados do pagador.debtor— QR com nome e documento do pagador.cobv— QR com vencimento (dueDate) e multa (fine/typeFine).
1. Criar a cobrança
curl -X POST https://api.staterpay.io/v1/charges \-H "Authorization: Bearer SUA_API_KEY" \-H "Idempotency-Key: 4a32aa03-9ee1-4c5d-971f-fdd4814e4f3b" \-H "Content-Type: application/json" \-d '{ "variant": "simple", "amountCents": "1990", "expiresIn": 3600, "tag": "Assinatura mensal"}'expiresIn é um TTL relativo em segundos (60 a 2.592.000 =
30 dias) contado a partir da criação — recomendado por evitar
ambiguidades de fuso horário. A alternativa é
expirationDate em ISO-8601 UTC com sufixo Z
obrigatório (ex.: 2026-05-07T21:50:00.000Z = 18:50 BRT).
Se ambos forem enviados, expiresIn tem precedência.
{"chargeId": "cmoxample0001qkxyzcharge","status": "PENDING","txid": "b308e8ec0c0a47b192f8db35703eab0c","brCode": "00020101021226920014br.gov.bcb.pix2570qrcode.staterpay.com.br/v2/qr/cob/b308e8ec-0c0a-47b1-92f8-db35703eab0c5204000053039865802BR5921NOME EMPRESA LTDA6009SAO PAULO62070503***6304F103","imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQAAAACxRhsSAAA...","imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/b308e8ec0c0a47b192f8db35703eab0c.png","providerQrId": "0000000000","expiresAt": "2026-05-07T18:50:00.000-03:00","variant": "simple"}Note que expiresAt retorna no fuso de Brasília
(UTC-3) — mesmo instante que você enviou em UTC, formatado para
exibição local.
2. Exibir o QR Code
Três opções para renderizar o QR ao pagador:
brCode— string copia-e-cola do QR Code (padrão BR Code do BCB).imageBase64— PNG já codificado, pronto para usar como<img src="data:image/png;base64,...">.imageUrl— URL pública da imagem PNG hospedada.
3. Receber confirmação por webhook
Quando o pagamento ocorre, a Stater envia um evento
pix.charge.paid ao seu endpoint registrado.
{"event": "pix.charge.paid","data": { "tag": "Assinatura mensal", "txid": "b308e8ec0c0a47b192f8db35703eab0c", "chargeId": "cmoxample0001qkxyzcharge", "endToEndId": "E18236120202605071234abcd1234", "movementId": "cmoxample0001qkxyzmovement", "occurredAt": "2026-05-07T18:55:12.879Z", "amountCents": "1990", "refundEndToEndId": null}}Caso desconfie de um webhook perdido, force a sincronização com o
provider Pix em POST /v1/charges/{id}/refresh.