Dashboard

Cobranças

Detalhes da cobrança

Detalhe da cobrança para credencial de API. Não use esta rota no loop de pagamento — para isso, GET /v1/charges/{chargeId}/status.

GET/v1/charges/:chargeId
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Cobrança de outra conta responde 404 com CHARGE_NOT_FOUND, igual a um ID inexistente.

O que vem

  • saleType: ONE_TIME (avulsa) ou RECURRING. Na avulsa, subscription e price vêm null.
  • paymentType: PIX, PIX_AUTOMATICO, BOLETO ou CREDIT_CARD. pix e boleto são excludentes: só o bloco do meio usado vem preenchido; o outro é null. Cartão deixa os dois null.
  • status: PENDING, PROCESSING, AWAITING_PAYMENT, PAID, FAILED, EXPIRED, CANCELED, ARCHIVED, DISPUTE, REFUNDED, PARTIALLY_REFUNDED, CHARGED_BACK.
  • amount é o valor cobrado do pagador (base da nota). netAmount é o líquido do lojista depois da taxa. fee.amount é a taxa total; percentageRate a alíquota; percentage e fixed as partes percentual e fixa, em reais.
  • address é o endereço de cobrança do cliente. Sem endereço, address é null. zipCode sai só com dígitos. cityCode é o código IBGE, número.
  • Depois do pagamento, payer traz name e document. Antes, null.
  • PIX (incluindo PIX Automático) preenche pix com emv, qrCode, dueDate e discount (type PERCENT ou FIXED, value, validUntil, originalAmount). Sem desconto, discount é null.
  • Boleto preenche boleto com emv, qrCode, barCode, digitableLine, dueDate e instructions (fine, interest e o mesmo discount). Aqui emv e qrCode são o Bolepix: o mesmo boleto aceita pagamento por Pix. O PDF não vem neste bloco — baixe em GET /v1/charges/{chargeId}/boleto.pdf.
  • qrCode, dentro de pix e de boleto, é a imagem do EMV já renderizada como data URL PNG, pronta para um <img src>. Sem EMV, é null — cartão deixa o bloco inteiro null.
  • nf (id, status, number, issuedAt, pdfUrl) evita reemitir a nota. Sem nota, null.
  • subscription.subscriptionId serve em DELETE /v1/subscriptions/{subscriptionId}. Confira status e cancelAtPeriodEnd antes. subscription.status: PENDING, TRIALING, ACTIVE, PAST_DUE, DEFAULT, EXPIRED, CANCELED, COMPLETED, ARCHIVED.

Para que serve

  • Nota fiscal: customer, address (cityCode), amount, productName ou price.name
  • Cancelar assinatura: subscription.subscriptionId
  • Conciliação: transactionId, endToEndId, externalTxid, grossAmount, netAmount, fee, paidAmount, payer
  • Cobrar de novo: pix / boleto, failureReason, expiresAt

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

charges/read

Path Parameters

chargeIdstringobrigatório
Identificador devolvido na criação da cobrança
const url = 'https://sandbox.validapay.com.br/v1/charges/:chargeId';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200Cartão recorrente▾
JSON
{
  "chargeId": "cha_1788279663277_8qjtrcyri",
  "status": "PAID",
  "amount": 399.99,
  "currency": "BRL",
  "paymentType": "CREDIT_CARD",
  "saleType": "RECURRING",
  "productName": "Plano Mensal",
  "createdAt": "2026-09-01T16:21:03.277Z",
  "paidAt": "2026-09-01T16:20:46.147Z",
  "failedAt": null,
  "dueDate": null,
  "expiresAt": null,
  "expiredAt": null,
  "invoiceId": "inv_1788279648820_3yicz75vb",
  "cycleNumber": 1,
  "transactionId": "gGpaxlAgjh5GiTtGQFn1",
  "endToEndId": null,
  "externalTxid": null,
  "grossAmount": 399.99,
  "netAmount": 379.14,
  "paidAmount": 399.99,
  "fee": {
    "amount": 20.85,
    "percentageRate": 5.17,
    "percentage": 20.68,
    "fixed": 0.17
  },
  "failureReason": null,
  "customer": {
    "customerId": "cus_1788279647000_maria01",
    "name": "Maria Silva",
    "document": "12345678900",
    "email": "maria@example.com",
    "phone": "11999998888",
    "additionalEmails": []
  },
  "address": {
    "type": "BILLING",
    "street": "Rua das Flores",
    "number": "100",
    "complement": "Ap 12",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "cityCode": 3550308,
    "state": "SP",
    "zipCode": "01001000",
    "country": "BR"
  },
  "payer": null,
  "subscription": {
    "subscriptionId": "sub_1788279647976_v510bg6w0",
    "status": "ACTIVE",
    "interval": "MONTHLY",
    "currentCycleNumber": 1,
    "cancelAtPeriodEnd": false,
    "priceId": "pri_1788279600000_mensal",
    "productId": "pro_1788279500000_plano",
    "customerId": "cus_1788279647000_maria01"
  },
  "price": {
    "priceId": "pri_1788279600000_mensal",
    "productId": "pro_1788279500000_plano",
    "name": "Plano Mensal"
  },
  "nf": null,
  "pix": null,
  "boleto": null
}
200PIX com vencimento▾
JSON
{
  "chargeId": "cha_1788279700000_pixcobv",
  "status": "PENDING",
  "amount": 49.9,
  "currency": "BRL",
  "paymentType": "PIX",
  "saleType": "ONE_TIME",
  "productName": "Pedido 1001",
  "createdAt": "2026-09-01T18:00:00.000Z",
  "paidAt": null,
  "failedAt": null,
  "dueDate": "2026-09-10",
  "expiresAt": "2026-09-10T23:59:59.000Z",
  "expiredAt": null,
  "invoiceId": null,
  "cycleNumber": null,
  "transactionId": null,
  "endToEndId": null,
  "externalTxid": "pedido-1001",
  "grossAmount": 49.9,
  "netAmount": 48.9,
  "paidAmount": null,
  "fee": {
    "amount": 1,
    "percentageRate": 0,
    "percentage": 0,
    "fixed": 1
  },
  "failureReason": null,
  "customer": {
    "customerId": "cus_1788279647000_ana01",
    "name": "Ana Silva",
    "document": "12345678909",
    "email": "ana@email.com",
    "phone": "11988887777",
    "additionalEmails": []
  },
  "address": null,
  "payer": null,
  "subscription": null,
  "price": null,
  "nf": null,
  "pix": {
    "emv": "00020101021226910014br.gov.bcb.pix2563qrcode.example/v2/abc",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAAB...",
    "dueDate": "2026-09-10",
    "discount": {
      "type": "PERCENT",
      "value": 10,
      "validUntil": "2026-09-08",
      "originalAmount": 49.9
    }
  },
  "boleto": null
}
200Boleto pago▾
JSON
{
  "chargeId": "cha_1788279800000_boleto01",
  "status": "PAID",
  "amount": 120,
  "currency": "BRL",
  "paymentType": "BOLETO",
  "saleType": "ONE_TIME",
  "productName": "Mensalidade setembro",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "paidAt": "2026-09-03T14:12:00.000Z",
  "failedAt": null,
  "dueDate": "2026-09-10",
  "expiresAt": null,
  "expiredAt": null,
  "invoiceId": null,
  "cycleNumber": null,
  "transactionId": "tx_boleto_1788279800",
  "endToEndId": null,
  "externalTxid": null,
  "grossAmount": 120,
  "netAmount": 116.5,
  "paidAmount": 120,
  "fee": {
    "amount": 3.5,
    "percentageRate": 0,
    "percentage": 0,
    "fixed": 3.5
  },
  "failureReason": null,
  "customer": {
    "customerId": "cus_1788279647000_joao01",
    "name": "Joao da Silva",
    "document": "12345678901",
    "email": "joao@email.com",
    "phone": "11977776666",
    "additionalEmails": []
  },
  "address": null,
  "payer": {
    "name": "Joao da Silva",
    "document": "12345678901"
  },
  "subscription": null,
  "price": null,
  "nf": {
    "id": "nfe_1788279800000_abc123",
    "status": "ISSUED",
    "number": "1234",
    "issuedAt": "2026-09-03T14:20:00.000Z",
    "pdfUrl": "https://exemplo.validapay.com.br/nf/nfe_1788279800000_abc123.pdf"
  },
  "pix": null,
  "boleto": {
    "emv": "00020101021226910014br.gov.bcb.pix2563qrcode.example/boleto",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAAB...",
    "barCode": "34191790010104351004791020150008291070026000",
    "digitableLine": "34191.79001 01043.510047 91020.150008 2 91070026000",
    "dueDate": "2026-09-10",
    "instructions": {
      "fine": 2,
      "interest": 0.1,
      "discount": {
        "type": "FIXED",
        "value": 5,
        "validUntil": "2026-09-08",
        "originalAmount": null
      }
    }
  }
}

← Anterior

Cobrança imediata

Próximo →

Status da cobrança