Pagamentos
Atualizar um pagamento
Atualiza campos editáveis de um Payment Intent antes do processamento e retorna o objeto completo; o webhook payment.intent.updated traz o diff.
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.
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.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.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.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.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").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, retorna409 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
Envieaffiliates 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.

