API Reference
Re-consultar status da cobrança
POST /v1/charges/:id/refresh força sincronização com o provider.
Re-consulta status da cobrança
Força a sincronização com o provider Pix subjacente. Útil para reconciliação quando o webhook de pagamento foi perdido.
POST/v1/charges/:id/refresh
Use refresh com moderação — está sujeito a um rate limit mais restrito (60/min) e força uma chamada ao provider. A resposta inclui pixAccount embutida com a configuração corrente da conta. Prefira webhooks para o fluxo principal de conciliação.
Path params
- idObrigatóriostringIdentificador da cobrança.
Headers
- AuthorizationObrigatóriostringBearer SUA_API_KEY
- Idempotency-KeyObrigatóriostringUUID para retry seguro.
Exemplo de requisição
bash
curl -X POST https://api.staterpay.io/v1/charges/cmoxample0001qkxyzcharge/refresh \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Idempotency-Key: ddcb9e92-08b6-46d1-a6ba-60cbecb0a4e1"Resposta
- kind"unchanged" | "updated"unchanged: o status não mudou. updated: o status foi sincronizado e a cobrança evoluiu.
- chargeobjectCobrança após o refresh — mesmos campos do GET /v1/charges/:id.
- providerStatusstringStatus bruto reportado pelo provider Pix (ex.: NEW, PAID, EXPIRED).
json
{ "kind": "unchanged", "charge": { "id": "cmoxample0001qkxyzcharge", "pixAccountId": "cmoxample0001qkxyzaccount", "variant": "cobv", "status": "PENDING", "amountCents": "10000", "txid": "837efc90cc554a42ab779c15f0f40092", "providerQrId": "0000000000", "brCode": "00020101021226920014br.gov.bcb.pix2570qrcode...", "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQAAAACxRhsSAAA...", "imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/837efc90cc554a42ab779c15f0f40092.png", "expiresAt": "2026-05-09T21:00:00.000-03:00", "dueDate": null, "fineDate": null, "debtorName": "Fulano de Tal", "debtorDocument": "12345678900", "debtorTypeDocument": "CPF", "typeFine": "NONE", "fine": 1, "tag": "Mensalidade Maio/2026", "endToEndId": null, "coreMovementId": null, "paidAt": null, "payerName": null, "payerDocument": null, "payerInstitution": null, "refundEndToEndId": null, "refundedAt": null, "refundedAmountCents": "0", "depositSnapshot": { "request": { "...": "..." }, "providerResponse": { "...": "..." } }, "failureReason": null, "createdAt": "2026-05-07T18:35:37.165-03:00", "updatedAt": "2026-05-07T18:35:37.165-03:00", "pixAccount": { "id": "cmoxample0001qkxyzaccount", "tenantId": "00000000-0000-0000-0000-000000000000", "label": "12345678000190", "enabled": true, "limitPerTransactionCents": "1000000", "limitDailyCents": "1000000", "limitNightCents": "500000", "createdAt": "2026-05-04T10:26:23.895-03:00" } }, "providerStatus": "NEW"}URL base:
https://api.staterpay.io