Faturas

Visão geral

Cada ciclo de uma assinatura gera uma fatura. A fatura tem os próprios itens, descontos, pagamentos e status, e pode receber mais de uma tentativa de cobrança.

Método	Rota	O que faz
`GET`	`/v2/invoices/{id}`	Consulta a fatura
`POST`	`/v2/invoices/{id}/pay`	Paga a fatura com um novo meio de pagamento
`POST`	`/v2/invoices/{id}/confirm`	Confirma o código de verificação
`POST`	`/v2/invoices/{id}/confirm/resend`	Reenvia o código de verificação

Para listar as faturas de uma assinatura, use GET /v2/subscriptions/{id}/invoices.

As rotas de fatura só encontram faturas de assinaturas.

Status da fatura

Status	Significado
`processing`	A cobrança está em andamento
`requires_action`	O comprador precisa agir: pagar o QR Code PIX ou informar o código de verificação
`paid`	A fatura foi paga
`failed`	A cobrança foi recusada. O motivo está em `failure_reason`
`canceled`	A fatura foi cancelada
`refunded`	A fatura foi estornada
`partially_refunded`	A fatura foi estornada parcialmente
`chargeback`	A fatura sofreu chargeback

Enquanto a fatura está em aberto ou recusada, o status reflete a cobrança mais recente. Uma fatura failed pode receber uma nova cobrança com Pagar fatura e passar a processing, requires_action ou paid.

Campos da fatura

Campo	Tipo	Descrição
`id`	string	Identificador da fatura (`ord_` seguido de 16 caracteres)
`object`	string	Sempre `invoice`
`subscription`	string	`id` da assinatura (`sub_...`)
`number`	integer	Número sequencial da fatura na assinatura. A primeira é `1`
`status`	string	Veja Status da fatura
`amount`	integer	Valor cobrado, em centavos de real, com descontos e acréscimos aplicados
`currency`	string	Sempre `brl`
`original_amount`	integer	Valor da fatura na moeda da assinatura, em centavos. Igual a `amount` em BRL
`original_currency`	string	Moeda da assinatura, em minúsculas (`brl`, `usd`)
`exchange_rate`	number	Cotação usada (1 unidade da moeda da assinatura = `exchange_rate` reais). `null` em BRL
`attempts`	integer	Quantidade de tentativas de cobrança registradas
`items`	array	Itens da fatura: `code`, `description`, `quantity`, `amount` (valor unitário, em centavos de real, convertido pela `exchange_rate` da fatura) e `amount_total` (total bruto da linha, em centavos de real)
`discounts`	array	Descontos da fatura: `type`, `value` (o valor declarado: em `fixed`, centavos de real convertidos pela `exchange_rate`; em `percentage`, o percentual, sem conversão), `invoice_number` e `amount_applied` (valor efetivamente descontado, em centavos de real, inclusive em `percentage`)
`increments`	array	Acréscimos da fatura, com os mesmos campos de `discounts`. `amount_applied` é o valor efetivamente acrescido, em centavos de real
`payments`	array	Tentativas de cobrança da fatura, da mais antiga para a mais recente, no formato payment_intent
`next_action`	object	Ação pendente do comprador ou `null` (veja abaixo)
`created_at`	string	Data de criação (ISO 8601)
`failure_reason`	object	Presente apenas quando `status` é `failed`

A fatura informa o valor cobrado, em real. Cada fatura tem uma única exchange_rate: uma nova tentativa de cobrança reaproveita a cotação da primeira cobrança da fatura, em vez de converter de novo. O preço acordado, na moeda da assinatura, fica na assinatura.Os items e os descontos e acréscimos fixed também saem em real, convertidos pela mesma exchange_rate. O tipo percentage não é convertido, porque percentual não tem moeda. Em faturas em BRL nada é convertido.A soma que fecha ao centavo, em BRL e em moeda estrangeira, é a dos campos conciliados:Σ items[].amount_total − Σ discounts[].amount_applied + Σ increments[].amount_applied = amountSomar items[].amount × quantity (os valores unitários) não tem essa garantia: numa fatura em moeda estrangeira, o resultado pode divergir em centavos.

Desconto maior que os itens: o total dos descontos aplicados é limitado ao valor dos itens. Nesse caso, o amount_applied fica menor que o value declarado, e o limite é repartido entre os descontos na proporção do valor declarado de cada um.
Acréscimos não têm limite e podem superar o valor dos itens.

Ação pendente (`next_action`)

Uma fatura em requires_action nem sempre traz um next_action: quando o código de verificação já foi confirmado ou expirou, o campo vem null. Trate o nulo em vez de assumir que o objeto existe. Quando a análise de fraude pede verificação, nada é cobrado até a confirmação do código:

{
  "type": "otp_confirmation",
  "otp": {
    "confirmation_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
    "expires_at": "2026-09-14T13:15:00.000000Z"
  }
}

Quando a cobrança é PIX e ainda não foi paga:

{
  "type": "pix_display_qr_code",
  "pix": {
    "qr_code": "00020126360014br.gov.bcb.pix...",
    "qr_code_url": "https://...",
    "expires_at": "2026-09-15 10:00:00"
  }
}

Motivo da recusa (`failure_reason`)

{
  "code": "insufficient_funds",
  "message": "O cartão não possui saldo suficiente para concluir o pagamento.",
  "customer_message": "Não foi possível concluir o pagamento. Revise os dados informados ou tente outro meio de pagamento.",
  "merchant_message": "O pagamento não foi concluído. Oriente o comprador a revisar os dados informados ou tentar outro meio de pagamento."
}

Mostre ao pagador apenas o customer_message. O message é técnico e não deve ser exibido. Veja Pagamento recusado.

Exemplo de fatura paga

Resposta (HTTP 200)

{
  "id": "ord_7Hk2Pq9Xm4Ln8Rt3",
  "object": "invoice",
  "subscription": "sub_4Hn8Qw2Rt6Yp1Zx3",
  "number": 1,
  "status": "paid",
  "currency": "brl",
  "amount": 9000,
  "original_amount": 9000,
  "original_currency": "brl",
  "exchange_rate": null,
  "attempts": 0,
  "items": [
    { "code": "SKU-SUB", "description": "Assinatura", "quantity": 1, "amount": 10000, "amount_total": 10000 }
  ],
  "discounts": [
    { "type": "fixed", "value": 1000, "invoice_number": 1, "amount_applied": 1000 }
  ],
  "increments": [],
  "payments": [
    {
      "id": "cha_8Kq2Lm9XvB3nT7pZ",
      "object": "payment_intent",
      "status": "paid",
      "amount": 9000,
      "amount_refunded": 0,
      "currency": "brl",
      "original_amount": 9000,
      "original_currency": "brl",
      "exchange_rate": null,
      "payment_method_details": {
        "type": "card",
        "card": { "brand": "visa", "first_six": "411111", "last_four": "1111", "holder_name": "John Doe", "exp_month": 12, "exp_year": 2030 }
      }
    }
  ],
  "next_action": null,
  "created_at": "2026-09-14T10:00:00-03:00"
}

Pagar uma fatura em aberto

Quando uma fatura é recusada, a assinatura fica past_due e recebe novas tentativas automáticas. Você também pode cobrar a fatura na hora, com outro cartão ou PIX:

Request — POST /v2/invoices/ord_7Hk2Pq9Xm4Ln8Rt3/pay

{
  "payment": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "holder_name": "John Doe",
      "exp_month": "12",
      "exp_year": "2030",
      "cvc": "123"
    }
  }
}

A resposta é 200 com a fatura atualizada (em geral processing para cartão ou requires_action para PIX), ou 402 quando a nova cobrança é recusada.

Só é possível pagar uma fatura pendente ou recusada de uma assinatura active, past_due ou suspended. Nos demais casos, a resposta é 422 (invoice_not_payable).

O PayPal processa apenas cobranças em BRL. Uma fatura de assinatura com currency diferente de BRL cobrada pelo PayPal é recusada, mesmo com a conversão para real: a resposta é 402 com failure_reason, como qualquer recusa de pagamento, e não um erro de requisição.

Código de verificação

A fatura fica requires_action com next_action.type = "otp_confirmation".
O comprador recebe o código.
Você envia o código em POST /v2/invoices/{id}/confirm: { "code": "123456" }.
A cobrança é retomada e a fatura passa a processing (ou 402 se for recusada).

O reenvio do código (POST /v2/invoices/{id}/confirm/resend) aceita 5 requisições por minuto por IP de origem. Se a sua plataforma atende várias contas a partir do mesmo servidor, todas dividem esse limite. O 429 desse limite vem fora do envelope de erro da v2.

Webhooks

Faturas de assinaturas criadas pela v2 enviam eventos no formato v2, com a fatura em data:

Evento	Quando
`invoice.created`	Uma nova fatura é gerada em uma renovação (não na primeira)
`invoice.paid`	A fatura é paga
`invoice.failed`	Uma tentativa de cobrança da fatura é recusada

Veja Eventos de fatura.

Uma fatura paga gera invoice.paid, e não charge.paid. O estorno de uma fatura é notificado por eventos de cobrança (charge.refunded ou charge.partial_refunded).

Erros específicos

Status	`code`	Quando acontece
`402`	—	A cobrança foi recusada. A resposta traz a fatura com `failure_reason`
`404`	`resource_missing`	Fatura inexistente, de outra conta ou que não pertence a uma assinatura
`422`	`validation_error`	Campo inválido (veja `param`)
`422`	`invoice_not_payable`	A fatura não pode ser paga no status atual
`422`	`card_token_invalid`	O `card.token` não pertence à conta
`422`	`acquirer_feature_not_supported`	A conta não tem adquirente para o meio de pagamento escolhido
`422`	`parameter_missing`	O `code` não foi enviado na confirmação
`422`	`confirmation_code_invalid`	O código de verificação é inválido ou expirou
`422`	`order_not_confirmable`	A fatura não está aguardando código de verificação
`429`	—	Limite de reenvio do código excedido (fora do envelope)

Veja o catálogo completo em Erros.

Pedidos

Cobranças

Cartões

Assinaturas

Contestações

Links de pagamento

Análise de fraude

Faturas

Visão geral

Status da fatura

Campos da fatura

Ação pendente (`next_action`)

Motivo da recusa (`failure_reason`)

Exemplo de fatura paga

Pagar uma fatura em aberto

Código de verificação

Webhooks

Erros específicos

​Visão geral

​Status da fatura

​Campos da fatura

​Ação pendente (next_action)

​Motivo da recusa (failure_reason)

​Exemplo de fatura paga

​Pagar uma fatura em aberto

​Código de verificação

​Webhooks

​Erros específicos

Visão geral

Status da fatura

Campos da fatura

Ação pendente (`next_action`)

Motivo da recusa (`failure_reason`)

Exemplo de fatura paga

Pagar uma fatura em aberto

Código de verificação

Webhooks

Erros específicos