Skip to main content
POST
Cria uma nova cobrança para uma fatura em aberto, com o meio de pagamento que você enviar em payment (cartão ou PIX). Cobranças ainda pendentes da fatura são canceladas antes da nova tentativa.
Só é possível pagar uma fatura pendente ou recusada de uma assinatura que não esteja cancelada nem concluída (active, past_due e suspended são aceitas). Faturas pagas, canceladas, estornadas ou aguardando código de verificação retornam 422 (invoice_not_payable).
A resposta é 200 com a fatura atualizada, ou 402 quando a nova cobrança é recusada (com o motivo em failure_reason). 200 não significa pago: com cartão, a fatura costuma ficar em processing até a confirmação; com PIX, fica em requires_action com o QR Code em next_action.
Outros erros possíveis: 422 card_token_invalid (cartão salvo de outra conta) e 422 acquirer_feature_not_supported (a conta não tem adquirente para o meio escolhido). Envie Idempotency-Key para evitar cobrança duplicada em reenvios.

Authorizations

Authorization
string
header
required

Chave de API (secret key) da conta, no formato sk_live_... (produção) ou sk_test_... (Dev mode). Envie no header Authorization: Bearer <chave>. Autentica todas as rotas da API v2 e as rotas de Análise de Fraude. A chave identifica a conta, então a API v2 não usa o header account. Uma chave só é aceita no ambiente em que foi criada. Gere a sua no dashboard em Configurações → Chaves de API.

Headers

Idempotency-Key
string

Chave de idempotência opcional e recomendada. Tem até 128 caracteres e vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a resposta original (mesmo status e mesmo corpo), sem processar de novo. Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode ser reutilizada. A mesma chave com um corpo diferente retorna 422 (idempotency_key_conflict), uma requisição original ainda em andamento retorna 409 (idempotency_key_in_use) e uma chave com mais de 128 caracteres retorna 400 (idempotency_key_invalid).

Maximum string length: 128
Example:

"pedido-1024-tentativa-1"

Path Parameters

id
string
required

Identificador do recurso (o campo id devolvido pela API)

Body

application/json
payment
object
required
statement_descriptor
string | null

Texto na fatura do cartão

Maximum string length: 50

Response

Pagamento processado. Confira o status da fatura

Fatura de um ciclo da assinatura. processing: em processamento. requires_action: PIX aguardando pagamento ou verificação por código (veja next_action). paid: paga. failed: recusada (veja failure_reason). canceled: cancelada. refunded e partially_refunded: estornada. chargeback: contestada.

id
string
Example:

"719305"

object
enum<string>
Available options:
invoice
subscription
string
Example:

"sub_4Hn8Qw2Rt6Yp1Zx3"

number
integer

Número da fatura na assinatura

Example:

1

status
enum<string>
Available options:
processing,
requires_action,
paid,
failed,
canceled,
refunded,
partially_refunded,
chargeback
currency
string
Example:

"brl"

amount
integer

Valor da fatura, em centavos, já com descontos e acréscimos

Example:

9000

attempts
integer

Tentativas de cobrança

items
object[]
discounts
object[]
increments
object[]
payments
object[]
next_action
object | null

O que precisa acontecer para o pagamento seguir. pix_display_qr_code: exiba o QR Code para o pagador. otp_confirmation: a análise de fraude pediu verificação — nada é cobrado até o código ser confirmado na rota /confirm.

created_at
string
failure_reason
object

Motivo da recusa. Presente só quando o status é failed