Atualizar Método de Pagamento
Atualize o método de pagamento para uma assinatura existente. Você pode adicionar um novo método de pagamento ou usar um existente dos métodos de pagamento salvos do cliente.
on_hold.
on_hold, atualizar o método de pagamento cria automaticamente uma cobrança pelos valores remanescentes, gera uma fatura e reativa a assinatura para o estado active após o pagamento ser bem-sucedido.Casos de Uso
- Assinaturas ativas: Atualize o método de pagamento quando um cartão expira ou o cliente deseja usar um método de pagamento diferente
- Assinaturas em espera: Reative assinaturas que foram colocadas em espera devido a falhas de pagamento atualizando o método de pagamento
- Gerenciamento de métodos de pagamento: Troque entre métodos de pagamento salvos ou adicione novos
type: "existing" para atualizar o método de pagamento de uma assinatura.Comportamento para Assinaturas Ativas
Ao atualizar o método de pagamento para uma assinatura ativa:- O método de pagamento é atualizado imediatamente
- Nenhuma cobrança é criada
- A assinatura permanece ativa
- As renovações futuras usarão o novo método de pagamento
Comportamento para Assinaturas em Espera
Ao atualizar o método de pagamento de uma assinatura no estadoon_hold:
- Uma cobrança é criada automaticamente pelos valores remanescentes
- Uma fatura é gerada para a cobrança
- O pagamento é processado usando o novo método de pagamento
- Após o pagamento ser bem-sucedido, a assinatura é reativada para o estado
active - Você receberá eventos de webhook:
payment.succeededseguido porsubscription.active
Eventos de Webhook
Ao atualizar um método de pagamento para uma assinaturaon_hold, você receberá os seguintes eventos de webhook:
payment.succeeded- A cobrança pelos valores remanescentes foi bem-sucedidasubscription.active- A assinatura foi reativada
Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Parâmetros de caminho
Subscription Id
Corpo
new List of payment methods allowed during checkout.
Customers will never see payment methods that are not in this list. However, adding a method here does not guarantee customers will see it. Availability still depends on other factors (e.g., customer location, merchant settings).
All supported payment method types.
Used for disabled-payment-methods filtering and validation.
ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, boleto, bca_bank_transfer, bni_va, bri_va, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eft, eps, fps, evoucher, giropay, givex, google_pay, go_pay, gcash, ideal, interac, indomaret, klarna, kakao_pay, local_bank_redirect, mandiri_va, knet, mb_way, mobile_pay, momo, momo_atm, multibanco, online_banking_thailand, online_banking_czech_republic, online_banking_finland, online_banking_fpx, online_banking_poland, online_banking_slovakia, oxxo, pago_efectivo, permata_bank_transfer, open_banking_uk, pay_bright, paypal, paze, pix, pay_safe_card, przelewy24, prompt_pay, pse, red_compra, red_pagos, samsung_pay, sepa, sepa_bank_transfer, sofort, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, vipps, viet_qr, venmo, walley, we_chat_pay, seven_eleven, lawson, mini_stop, family_mart, seicomart, pay_easy, local_bank_transfer, mifinity, open_banking_pis, direct_carrier_billing, instant_bank_transfer, billie, zip, revolut_pay, naver_pay, payco, satispay