PaymentIntents

Um PaymentIntent representa a intenção de cobrar um valor de um pagador. Você cria, confirma com Pix ou cartão de teste e acompanha o estado até succeeded, failed ou canceled.

Operações

post /v1/payment-intents — Criar PaymentIntent
post /v1/payment-intents/{id}/confirm — Confirmar PaymentIntent
get /v1/payment-intents/{id} — Consultar PaymentIntent
get /v1/payment-intents/{id}/activity — Linha do tempo do PaymentIntent
post /v1/orders/{id}/payment-intents — Criar PaymentIntent do pedido

Criar

Corpo de criação de PaymentIntent
Campo	Tipo	Detalhes
`amount_minor` obrigatório	string	Padrão `^[1-9][0-9]*$`
`currency`	string	Padrão `^[A-Z]{3}$` Padrão: `"BRL"`
`payment_method_types`	string[]	Valores: `card`, `pix` 1 a 2 itens
`payer`	PayerInput
`description`	string	1 a 500 caracteres
`metadata`	mapa de string	Chaves: `^[A-Za-z0-9_.-]{1,40}$`

amount_minor: inteiro positivo em centavos, como string. currency é BRL.
payment_method_types: métodos aceitos (pix, card); o padrão é ["card"]. Confirmar com um método fora da lista responde 400.
payer: nome, e-mail e, opcionalmente, CPF ou CNPJ (validado pelo dígito verificador). O documento é transformado em HMAC na borda da API e nunca é armazenado, registrado em log nem devolvido — a resposta traz só o tipo e os dois últimos dígitos.
description até 500 caracteres; metadata com até 20 chaves ([A-Za-z0-9_.-], até 40 caracteres) e valores de até 500 caracteres.

Confirmar

{"payment_method": {"type": "pix"}} → 202, status: "processing" e next_action com o QR sintético. Veja Pix simulado.
{"payment_method": {"type": "card", "test_card": "approved"}} → 200 succeeded; recusas → 402 PAYMENT_DECLINED; indisponibilidade → 202 processing até a reconciliação. Veja Cartões de teste.
Confirmar exige Idempotency-Key: uma nova tentativa com a mesma chave nunca cobra duas vezes.

Estados

Estado	Significado	Pode ir para
`requires_payment_method`	Criado; aguarda a confirmação com um método de `payment_method_types`.	`requires_action`,`processing`,`canceled`
`requires_action`	Reservado para ações do pagador; não é usado pelos métodos desta edição.	`processing`,`failed`,`canceled`
`processing`	Pix aguardando pagamento (com `next_action`) ou cartão com resultado desconhecido no provedor, em reconciliação.	`succeeded`,`failed`,`canceled`
`succeeded`final	Pago: Charge criada e ledger lançado. Só reembolsos e disputas vêm depois.	—
`failed`final	Recusado definitivamente; `failure_code` diz o motivo.	—
`canceled`final	Cancelado. Nesta edição acontece quando o Pix vence (`cancellation_reason: "expired"`), sem lançamento no ledger.	—

O objeto PaymentIntent

Objeto PaymentIntent

Objeto PaymentIntent
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pi_`
`order_id` obrigatório	string \| null
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`provider_id` obrigatório	string
`latest_provider_attempt_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null
`payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_method_type` obrigatório	string \| null
`description` obrigatório	string \| null
`metadata` obrigatório	mapa de string
`payer` obrigatório	PayerView \| null
`next_action` obrigatório	PaymentNextAction \| null
`expires_at` obrigatório	string \| null
`cancellation_reason` obrigatório	string \| null

Eventos

payment.created, payment.processing, payment.paid, payment.failed, payment.canceled, payment.reconciliation_required e payment.reconciled. O data traz payment_intent_id, order_id, status, amount_minor, currency, provider_id e, quando existem, payment_method_type, expires_at e cancellation_reason — nunca dados do pagador. Veja Webhooks.