Skip to main content
Cobranças positivas precisam satisfazer o mínimo do plano efetivo e do método. Um valor insuficiente retorna amount_too_small antes do processamento e não autoriza repetição automática. Veja mínimos e tratamento do erro.
Confirma um payment_intent e inicia a cobrança. A confirmação cria uma charge, que representa a tentativa de pagamento dentro do intent. Para cartão, use um payment_method salvo. Para Pix, informe payment_method_type: "pix" ou crie o intent apenas com payment_method_types: ["pix"]; a resposta traz o QR code em next_action.pix_display_qr_code e o status fica requires_action até a confirmação assíncrona. O código tem validade curta (next_action.pix_display_qr_code.expires_at); sem pagamento nesse prazo, o intent volta a requires_payment_method — use /regenerate_pix para emitir um código novo no mesmo intent.
O endpoint de confirmação direta aceita cartão e Pix. Payment intents de boleto são criados e processados pelos fluxos de checkout hospedado ou invoice; não envie payment_method_type: "boleto" aqui.
Confirme um intent pelo próprio ID pi_*. Quando o intent foi criado por outro fluxo, esse fluxo é só a origem — não use ele como chave da tentativa de pagamento. O estado financeiro mora no payment_intent e nos webhooks de payment.intent.*. Não crie charges diretamente: para cobrar alguém, crie e confirme um payment_intent. Quando capture_method é manual, a confirmação de cartão autoriza o valor e retorna o intent em requires_capture com amount_capturable preenchido. Use POST /v1/payment-intents/:id/capture para capturar.
Se a resposta do provider se perder, o endpoint pode retornar erro enquanto o Payment Intent permanece processing. Consulte o mesmo intent e espere o webhook: não chame /confirm de novo e não crie outra cobrança. A Chargefy reconcilia a tentativa já enviada e publica o resultado quando ele for conhecido.

​
Evento emitido na confirmação do Pix

Quando a confirmação muda o intent de requires_confirmation para requires_action, ela sempre emite payment.intent.updated. O evento contém o Payment Intent completo em data.object, inclusive latest_charge e next_action, e informa o status anterior em data.previous_attributes.status. Se a confirmação terminar em succeeded, é emitido payment.intent.succeeded em vez de um payment.intent.updated adicional. Uma recusa não encerra o intent: ele volta a requires_payment_method com o motivo em last_payment_error, o detalhe da tentativa sai em charge.failed e a transição chega por payment.intent.updated.
​
string
obrigatório
ID do payment intent (pi_*).
​
string
Customer associado. Obrigatório se o intent foi criado sem customer.
​
string
Payment method salvo para cartão. Obrigatório para cobrança de cartão se o intent ainda não tem método.
​
string
Método a confirmar quando o intent permite mais de um método.
cURL
200

​
Confirmar Pix

​
Erros comuns

Uma recusa é erro HTTP. A resposta é 402 com type: "card_error", o code estável da recusa (o mesmo gravado em last_payment_error.code), advice_code, a evidência bruta da rede em network_*, a charge da tentativa e o intent completo em error.payment_intent, já em requires_payment_method: não é preciso consultar o intent de novo para tratar a recusa. Falha técnica na tentativa usa o mesmo shape com 502 e type: "api_error"; estado incompatível, 409. Os códigos estão em Códigos de falha.

​
Depois da confirmação

A resposta é útil para atualizar a tela imediatamente, mas o backend deve processar também os webhooks:
  • payment.intent.succeeded para confirmar o pagamento;
  • charge.failed para registrar o detalhe de uma tentativa recusada;
  • payment.intent.canceled quando o intent for cancelado de forma deliberada (cancelamento direto ou expiração do checkout);
  • payment.intent.updated quando a confirmação do Pix mudar o intent para requires_action, quando uma recusa ou um código vencido devolver o intent a requires_payment_method, ou em outra transição intermediária.

Objeto Payment Intent

Todos os estados, campos e transições possíveis.

Implementar Payment Intents

Fluxo seguro para Pix, cartão, webhook e atualização do estado local.