Skip to main content
Um payment_intent representa uma cobrança ao longo de todo o seu ciclo de vida — da intenção de cobrar até o desfecho final. Ele concentra num só lugar o valor, a moeda, o customer, os métodos permitidos, a tentativa de cobrança mais recente, o estado atual e a próxima ação que cabe ao comprador, e é por ele que o seu sistema sabe se o dinheiro entrou, está em trânsito ou foi recusado. Ele nasce quando uma cobrança começa, seja criada diretamente pela API ou resolvida por um checkout hospedado, e atravessa um status que reflete o que falta para concluir o pagamento: cartão costuma resolver na hora, enquanto PIX e boleto ficam pending até a confirmação assíncrona chegar. À medida que avança, ele se liga à charge que materializa cada tentativa e, quando origina de uma cobrança recorrente, à invoice correspondente — sendo o estado financeiro que conecta esses objetos à pessoa que paga.

​
Objeto payment_intent

Este é o formato completo retornado em create, get, update, confirm, capture, cancel, itens de list e em data.object dos webhooks payment.intent.*. 
{
  "id": "pi_123",
  "object": "payment_intent",
  "amount": 7500,
  "amount_capturable": 0,
  "amount_details": {
    "installment_interest": 0,
    "subtotal": 7500,
    "total": 7500
  },
  "amount_received": 0,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_123_secret_abc",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T18:34:58Z",
  "currency": "brl",
  "customer": "cus_123",
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": "ch_123",
  "livemode": true,
  "metadata": {
    "order_id": "id_456"
  },
  "next_action": {
    "pix_display_qr_code": {
      "expires_at": "2026-05-16T19:35:00Z",
      "qr_code": "00020101021226860014br.gov.bcb.pix...",
      "qr_code_url": null
    },
    "type": "pix_display_qr_code"
  },
  "payment_method": null,
  "payment_method_options": {},
  "payment_method_types": ["pix"],
  "setup_future_usage": null,
  "status": "pending",
  "updated_at": "2026-05-16T18:35:00Z"
}
​
id
string
Identificador do payment intent. Usa o prefixo pi_*.
​
object
string
Sempre "payment_intent".
​
amount
integer
Valor total do intent em centavos. Quando há juros de parcelamento, pode ser maior que o subtotal original.
​
amount_capturable
integer
Valor autorizado e ainda não capturado. Fica preenchido em captura manual.
​
amount_details
object
Quebra do valor usado na cobrança.
​
amount_received
integer
Valor já recebido. Em geral fica 0 antes do pagamento e igual a amount quando o intent chega a succeeded.
​
canceled_at
string | null
Data de cancelamento em ISO 8601.
​
cancellation_reason
string | null
Motivo do cancelamento: duplicate, fraudulent, requested_by_customer, abandoned ou null.
​
capture_method
string
automatic para capturar na confirmação, ou manual para autorizar agora e capturar depois.
​
client_secret
string
Credencial de runtime do intent. Use apenas em contexto controlado pelo seu frontend quando o fluxo exigir confirmação client-side.
​
confirmation_method
string
Como o intent é confirmado. Hoje retorna automatic ou manual.
​
created_at
string
Data de criação em ISO 8601.
​
currency
string
Moeda em ISO 4217 minúsculo, como brl.
​
customer
string | null
Customer associado ao pagamento, quando houver.
​
invoice
string | null
Invoice associada, quando o intent nasceu de uma invoice.
​
last_payment_error
object | null
Motivo da recusa da última tentativa, quando houver. Vem null enquanto não houve falha. Veja Códigos de falhas para a lista completa de códigos e categorias.
​
latest_charge
string | object | null
Tentativa de cobrança mais recente. Por padrão vem como ID ch_*; pode vir expandida quando você usa expand[]=latest_charge.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Objeto livre para correlacionar o intent com o seu sistema. Quando vazio, retorna {}.
​
next_action
object | null
Próxima ação para o comprador. Vem preenchido em fluxos assíncronos como PIX e boleto.
​
payment_method
string | object | null
Método de pagamento salvo usado no intent. Por padrão vem como ID pm_*; pode vir expandido quando você usa expand[]=payment_method.
​
payment_method_options
object
Opções por método de pagamento, como parcelamento de cartão.
​
payment_method_types
array
Métodos permitidos para a cobrança. Hoje pode incluir credit_card, pix e boleto, conforme o fluxo.
​
setup_future_usage
string | null
off_session, on_session ou null, quando o método também será usado no futuro.
​
status
string
Estado atual da cobrança.
​
updated_at
string | null
Data da última atualização em ISO 8601.

​
Operações

​
Test helpers

Em sandbox, você pode avançar um payment_intent de teste sem esperar a compensação assíncrona. Test helpers só aceitam chaves ch_test_...; chamadas em live mode retornam erro testmode_required.
AçãoEndpointResultado
Succeed a Test Payment IntentPOST /v1/test-helpers/payment-intents/{id}/succeedMarca o intent como succeeded, atualiza a charge como paga e emite os webhooks de sucesso.
Fail a Test Payment IntentPOST /v1/test-helpers/payment-intents/{id}/failMarca o intent como failed, registra last_payment_error e emite os webhooks de falha.
Expire a Test Payment IntentPOST /v1/test-helpers/payment-intents/{id}/expireCancela o intent com cancellation_reason: "abandoned" e emite os webhooks de expiração/falha.
Todos retornam 200 OK com o objeto payment_intent completo atualizado.

​
Webhooks

Para liberar produto, crédito, assinatura ou acesso, prefira webhooks em vez de depender só da resposta síncrona. Eventos principais: