Cria cobrança Pix

Gera um QR Code Pix com TXID único. Suporta três variantes via discriminator variant: simple (estático, sem dados do pagador), debtor (com nome e documento do pagador) e cobv (com vencimento e multa).

POST/v1/charges

Expiração do QR: envie expirationDate (ISO-8601 UTC com sufixo Z) ou expiresIn (TTL relativo em segundos, 60 a 2.592.000). Ambos opcionais; se vierem juntos, expiresIn tem precedência. Prefira expiresIn para evitar problemas de fuso horário. Datas em UTC: expirationDate, dueDate e fineDate sempre em UTC com sufixo Z. expiresAt na resposta volta em UTC-3 (Brasília). Regras da variante cobv: expirationDate deve ser pelo menos 1 dia depois de dueDate; fineDate normalmente é igual a dueDate (pode ser maior, nunca maior que expirationDate). Idempotency-Key é obrigatório em todas as variantes.

Headers

AuthorizationObrigatório
string
Bearer SUA_API_KEY
Idempotency-KeyObrigatório
string
UUID para retry seguro.
Content-TypeObrigatório
string
application/json

Body

variantObrigatório
"simple" | "debtor" | "cobv"
Tipo da cobrança.
amountCentsObrigatório
string
Valor em centavos.
expirationDate
string (ISO-8601 UTC)
Quando o QR expira, em UTC com sufixo Z. Ex.: 2026-05-07T21:50:00.000Z (= 18:50 BRT). Opcional se expiresIn for informado.
expiresIn
integer (60–2592000)
TTL relativo em segundos a partir da criação (60s até 30 dias = 2.592.000s). Alternativa a expirationDate que evita ambiguidades de fuso horário. Se ambos vierem, expiresIn tem precedência.
tag
string
Texto livre para conciliação interna. Volta no payload do webhook.
externalRef
string (≤ 64)
Referência externa do seu sistema (ex.: ID do pedido, da fatura). Até 64 caracteres. Permite consultar a cobrança depois via GET /v1/charges/external-ref/:externalRef.
debtorName
string
Nome do pagador (obrigatório em debtor e cobv).
debtorDocument
string
CPF ou CNPJ do pagador, apenas dígitos (obrigatório em debtor e cobv).
debtorTypeDocument
"CPF" | "CNPJ"
Tipo do documento (obrigatório em debtor e cobv).
dueDate
string (ISO-8601 UTC)
Data de vencimento — somente cobv.
fineDate
string (ISO-8601 UTC)
Data a partir da qual multa começa a incidir — somente cobv. Geralmente igual a dueDate.
typeFine
"NONE" | "VALUE" | "PERCENT"
Tipo da multa — somente cobv. NONE desabilita.
fine
number
Valor (em reais) ou percentual da multa — somente cobv.

Exemplo de requisição

curl -X POST https://api.staterpay.io/v1/charges \  -H "Authorization: Bearer SUA_API_KEY" \  -H "Idempotency-Key: 0947ab02-d7ae-428c-8681-fb8b57e8f4f6" \  -H "Content-Type: application/json" \  -d '{    "variant": "simple",    "amountCents": "100",    "expiresIn": 3600,    "tag": "Assinatura mensal"  }'

Resposta

chargeId
string
Identificador interno da cobrança (cuid).
status
"PENDING" | "PAID" | "EXPIRED" | "REFUNDED"
Estado atual.
txid
string
TXID Pix de 32 caracteres hexadecimais.
brCode
string
QR Code copia-e-cola (padrão BR Code do BCB).
imageBase64
string
PNG do QR em base64 cru (sem prefixo data:).
imageUrl
string (URL)
URL pública da imagem PNG hospedada.
providerQrId
string
ID do QR no provider Pix subjacente.
expiresAt
string (ISO-8601 UTC-3)
Quando o QR expira, retornado no fuso de Brasília.
variant
string
Variante criada (eco do request).

json

{  "chargeId": "cmoxample0001qkxyzcharge",  "status": "PENDING",  "txid": "79cefaf1d718440897cd80e682de6aa7",  "brCode": "00020101021226920014br.gov.bcb.pix2570qrcode.staterpay.com.br/v2/qr/cob/79cefaf1-d718-4408-97cd-80e682de6aa75204000053039865802BR5921NOME EMPRESA LTDA6009SAO PAULO62070503***630449B2",  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQAAAACxRhsSAAA...",  "imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/79cefaf1d718440897cd80e682de6aa7.png",  "providerQrId": "0000000000",  "expiresAt": "2026-05-07T18:50:00.000-03:00",  "variant": "simple"}

URL base:https://api.staterpay.io

Criar cobrança Pix

Cria cobrança Pix

Headers

Body

Exemplo de requisição

Resposta

On this page