Pular para o conteúdo principal
Atualiza um payment_intent antes da confirmação. A resposta direta retorna o objeto completo atualizado; o diff sai apenas no webhook payment.intent.updated. Valores, cliente, método e taxas de afiliados só podem mudar em requires_payment_method ou requires_confirmation, sem uma tentativa ativa. metadata continua editável nos demais estados. A edição não confirma nem reabre o pagamento. Se uma confirmação ou pagamento chegar durante a edição, os campos são validados novamente no estado atual. Um 409 indica que a edição não foi aplicada: consulte o pagamento antes de decidir se deve tentar novamente. Reenviar os mesmos valores sem mudança não gera outro payment.intent.updated.
string
obrigatório
ID do payment intent (pi_*).
array
Comissões de afiliados do pagamento avulso. Cada item contém affiliation (vínculo ativo) e affiliate_fee_rate (inteiro de 1 a 10000 pontos-base; 3000 significa 30%). Todos os percentuais incidem em paralelo sobre o que sua organização recebe antes das comissões de afiliados, depois da taxa de processamento e dos juros pagos pela organização. A soma vai até 10000. São até 8 afiliados em venda direta e 7 quando há taxa de plataforma, com no máximo 10 recebedores no pagamento. Vínculos, contas e recebedores repetidos são conferidos antes de aceitar a operação. Veja Comissões de afiliados.
integer
Novo valor na menor unidade da moeda (centavos em brl). Só pode ser alterado antes do processamento.O teto depende da moeda. Em brl, o máximo é 999999999 na menor unidade. Acima do teto, a API retorna 400 amount_too_large com param e maximum_amount. Quando o valor já está associado a uma moeda, a resposta inclui currency.
string
Nova moeda. Envie também amount na nova moeda. A troca só é aceita antes do processamento e quando o Payment Intent ainda não tem fatura, Checkout Session ou cobrança vinculada.Aceita hoje: brl. Maiúsculas valem como minúsculas (BRL é lido como brl); outra moeda retorna 400 com code: "unsupported_currency". Veja Moedas.
string
Customer associado (cus_*).
string
Payment method salvo (pm_*).
array
Métodos permitidos para o intent. Aceita credit_card e pix.
boolean
Liga ou desliga o repasse de taxa antes da confirmação. Quando true, o comprador cobre a taxa da organização e o total é recalculado; exige exatamente um payment_method_types.
object
Opções por método de pagamento.
integer
Número de parcelas de cartão antes da confirmação. Quando omitido, usa 1.
string
Quem paga o juro do parcelamento: buyer (comprador, juro somado ao total) ou organization (a organização paga; o comprador parcela o valor à vista e o juro sai do líquido da organização). Quando omitido, usa a configuração da organização. has_interest foi removido: enviá-lo retorna 400 com param apontando o campo e a mensagem has_interest was removed; use interest_payer ("buyer" | "organization").
object
Metadata livre.

Resposta

200 OK com o objeto payment_intent completo — mesmo shape de GET /v1/payment-intents/:id.

Erros comuns

Objeto e campos

Shape completo, status, valores e relações.

Evento payment.intent.updated

Objeto atual completo e valores anteriores dos campos alterados.

Juros atualizados antes da confirmação

A confirmação no cartão confere os juros contra a tabela vigente. Se a tabela mudou desde a criação ou atualização do Payment Intent, retorna 409 installment_interest_changed, com param: payment_method_options, sem enviar a cobrança. Atualize o Payment Intent reenviando payment_method_options, mostre o total atualizado ao comprador e só então confirme novamente. Cobranças já criadas mantêm seus valores. Por exemplo, o comprador viu R$ 1.070,80 em 3 parcelas. Se a tabela vigente passar a cobrar R$ 1.050,40, a confirmação retorna 409; a integração atualiza o preço e apresenta R$ 1.050,40 para um novo aceite. Ao confirmar por Pix um Payment Intent que havia sido precificado para cartão parcelado, o valor passa a ser o valor à vista: principal mais o acréscimo aplicável, sem juros de parcelamento.

Alterar as comissões de afiliados

Envie affiliates enquanto o pagamento estiver em requires_payment_method ou requires_confirmation. A lista substitui o combinado inteiro; [] remove as comissões de afiliados. Após a confirmação, os termos daquela cobrança ficam fixos. O campo só é aceito em pagamentos avulsos, sem invoice.

Erros de comissões de afiliados