Stater Platform

Criar cobrança Pix

POST /accounts/:accountId/charges — gera QR Code Pix nas variantes simple, debtor ou cobv.

Criar cobrança Pix

Cria uma cobrança Pix com QR Code (BR Code + imagem). Suporta 3 variantes: simple (QR sem devedor, expira em 15 min), debtor (QR imediato com dados do pagador, expira em 15 min) e cobv (cobrança com vencimento, multa e juros).

POST/accounts/:accountId/charges

amountCents vai em centavos como string — "100" é R$ 1,00 (atenção: difere de outras rotas WL que aceitam valor decimal em reais). Mande Idempotency-Key em toda chamada pra evitar gerar QR duplicado em retry. simple/debtor expiram em 15 min após criação; cobv expira em expirationDate. Em cobv as datas têm contrato rígido: expirationDate sempre 1 dia após dueDate; fineDate (opcional) também precisa ser 1 dia após dueDate quando enviado. fine usa centavos quando typeFine=VALUE e percentual quando typeFine=PERCENT. brCode/imageBase64/imageUrl referenciam o mesmo QR — escolha o formato conforme o canal (texto pra Copia e Cola, base64 pra render inline, URL pra link/imagem remota).

Path params

  • accountIdObrigatório
    string (UUID)
    ID da conta recebedora.

Headers

  • AcceptObrigatório
    string
    application/json
  • Content-TypeObrigatório
    string
    application/json
  • AuthorizationObrigatório
    string
    Bearer <token> — JWT de /authenticate.
  • X-Tenant-IdObrigatório
    string (UUID)
    Identificador do tenant.
  • Idempotency-Key
    string (UUID)
    Chave de idempotência por requisição. Recomendado em todas as criações pra evitar cobrança duplicada em retry.

Body

  • variantObrigatório
    "simple" | "debtor" | "cobv"
    Tipo da cobrança. simple = QR sem devedor; debtor = QR com dados do pagador; cobv = cobrança com vencimento (multa/juros).
  • amountCentsObrigatório
    string
    Valor da cobrança em centavos, como string. Ex.: "100" = R$ 1,00; "1000" = R$ 10,00.
  • tag
    string
    Identificador livre (ex.: número do pedido) — devolve no webhook de liquidação.
  • debtorName
    string
    Nome do pagador. Obrigatório em variant=debtor e variant=cobv.
  • debtorDocument
    string
    CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, apenas números. Obrigatório em variant=debtor e variant=cobv.
  • debtorTypeDocument
    "CPF" | "CNPJ"
    Tipo do documento do pagador. Obrigatório em variant=debtor e variant=cobv.
  • dueDate
    string (ISO 8601)
    Data de vencimento. Obrigatório em variant=cobv.
  • expirationDate
    string (ISO 8601)
    Data limite para pagamento após o vencimento. Obrigatório em variant=cobv e deve ser sempre 1 dia após dueDate.
  • fineDate
    string (ISO 8601)
    Data a partir da qual a multa começa a valer. Opcional em variant=cobv; quando enviado, precisa ser 1 dia após dueDate.
  • typeFine
    "VALUE" | "PERCENT"
    Modo de cálculo da multa em variant=cobv. VALUE = valor fixo em centavos; PERCENT = percentual sobre o amountCents.
  • fine
    number
    Valor da multa. Em typeFine=VALUE vai em centavos (ex.: 1000 = R$ 10,00); em typeFine=PERCENT vai como percentual (ex.: 2 = 2%).

Exemplo de requisição

curl -X POST https://baas.staterpay.io/accounts/00000000-0000-0000-0000-000000000010/charges \  -H "Accept: application/json" \  -H "Content-Type: application/json" \  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>" \  -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \  -H "Idempotency-Key: 00000000-0000-0000-0000-0000000000f1" \  -d '{    "variant": "simple",    "amountCents": "100",    "tag": "Pedido 123"  }'

Resposta

  • chargeId
    string (cuid)
    ID interno da cobrança — use pra consultar status posterior.
  • status
    "PENDING" | "PAID" | "EXPIRED" | "REFUNDED"
    Estado inicial sempre PENDING.
  • txid
    string
    Identificador do BCB embutido no brCode (32 caracteres hex).
  • brCode
    string
    Payload Pix Copia e Cola — o pagador pode colar direto no app do banco.
  • imageBase64
    string
    PNG do QR Code codificado em base64 (sem prefixo data:image). Útil pra render inline.
  • imageUrl
    string
    URL pública do PNG do QR Code, hospedada pela Stater.
  • providerQrId
    string
    ID da cobrança no provider Pix subjacente.
  • expiresAt
    string (ISO 8601)
    Quando a cobrança expira. Em simple/debtor = createdAt + 15 min; em cobv = expirationDate enviado no body.
  • variant
    "simple" | "debtor" | "cobv"
    Eco do variant enviado.
json
{  "chargeId": "cmoxample0004qkxyzcharge",  "status": "PENDING",  "txid": "00000000000000000000000000000000",  "brCode": "00020101021226920014br.gov.bcb.pix2570qrcode.staterpay.com.br/v2/qr/cob/00000000-0000-0000-0000-0000000000005204000053039865802BR5912FULANO DE TAL6009SAO PAULO62070503***6304XXXX",  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...truncado",  "imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/00000000000000000000000000000000.png",  "providerQrId": "00000000",  "expiresAt": "2026-05-14T08:16:28.467-03:00",  "variant": "simple"}
URL base:https://baas.staterpay.io

Consultar payout

GET /accounts/:accountId/payouts/:payoutId — status atualizado de envios Pix, TEF ou QR Code.

Consultar cobrança Pix

GET /accounts/:accountId/charges/:chargeId — estado atualizado e dados do pagador após liquidação.

On this page

Path paramsHeadersBodyExemplo de requisiçãoResposta