capture_method aceita automatic ou manual. Não existe um
terceiro modo configurável de captura assíncrona.
O que pode acontecer de forma assíncrona é a conclusão do pagamento. PIX e
boleto retornam antes da confirmação financeira e mudam de status depois. Em
cartão, captura significa outra coisa: efetivar um valor que já foi autorizado.
Captura automática
Comcapture_method: "automatic", a confirmação de um cartão tenta autorizar e
capturar o valor no mesmo fluxo. Quando a operação termina em succeeded, o
pagamento pode ser processado.
Esse é o padrão. Omita capture_method se você não precisa separar autorização
e captura.
Captura manual
Use captura manual quando você precisa reservar o valor no cartão e efetivar a cobrança depois, por exemplo após confirmar estoque ou concluir uma reserva. Esse fluxo está disponível somente para cartão.1
Crie o intent com captura manual
Envie
capture_method: "manual" e confirme o cartão.2
Aguarde requires_capture
Uma autorização aprovada deixa o intent em
requires_capture e preenche
amount_capturable.3
Capture ou cancele
Capture o valor integral pelo endpoint
/capture. Se não for concluir a
venda, cancele o intent para liberar a autorização.4
Processe o resultado
Uma captura concluída leva o intent a
succeeded e emite
payment.intent.succeeded.requires_capture:
A captura atual é integral. Se você enviar
amount_to_capture, o valor deve
ser igual a amount_capturable.Pagamentos que terminam de forma assíncrona
PIX e boleto não usam captura manual. A confirmação cria a instrução de pagamento e retorna o intent empending. O dinheiro ainda não foi recebido.
Apresente next_action ao comprador e espere um evento terminal:
Não transforme um
pending ou processing em sucesso no seu sistema. Também
não dependa de uma página aberta: o comprador pode pagar fora do navegador e a
confirmação chegar depois.
Escolha o fluxo certo
- Use captura automática para cobranças de cartão que podem ser concluídas imediatamente.
- Use captura manual quando autorização e captura precisam acontecer em momentos diferentes.
- Para PIX e boleto, trate o pagamento como assíncrono e reaja por webhook;
não tente chamar
/capture.
Capturar um pagamento
Contrato do endpoint de captura manual.
Atualizações do status
Como acompanhar transições e eventos terminais.