# Atualizações pendentes Saiba como gerenciar falhas de pagamento ao atualizar assinaturas. A atualização de uma *assinatura* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) gera uma nova *fatura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) quando: - A assinatura exige pagamento pela primeira vez, como no final de um período de teste. - O período de faturamento muda. - Alterar a assinatura resulta em cobrança proporcional (pro-rata) e `proration_behavior=always_invoice`. Muitas atualizações de assinatura não geram novas faturas ou acionam atualizações pendentes, incluindo: - Alterações de configuração (formas de pagamento, configurações de impostos, configurações de repetição) - Atualizações de metadados em assinaturas ou itens de assinatura - Adição ou atualização de cupons ou códigos promocionais que se aplicam a faturas futuras - Ajustes de limiar de faturamento - Ambiente `cancel_at_period_end` para`true` - Adicionar cobranças únicas com `add_invoice_items` Essas atualizações se aplicam imediatamente, sem implicações de pagamento. Para uma lista completa, consulte[O que não aciona rateios](https://docs.stripe.com/billing/subscriptions/prorations.md#no-prorations). Por padrão, a Stripe aplica atualizações mesmo que o pagamento da nova fatura não seja processado. Se o pagamento falhar, a aplicação das atualizações ocorre manualmente. Você precisa criar uma nova fatura, fazer uma cobrança proporcional dos itens e iniciar o pagamento novamente. No entanto, com o recurso de atualizações pendentes, você só pode fazer alterações a assinaturas se o pagamento da nova fatura for bem-sucedido. ## Before you begin Você pode usar atualizações pendentes se o [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) da assinatura for `charge_automatically` e a forma de pagamento for uma dos seguintes: - [Cartão](https://docs.stripe.com/payments/cards.md) - [Link](https://docs.stripe.com/payments/link.md) - [Alipay](https://docs.stripe.com/payments/alipay.md) - [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md) - [Afterpay/Clearpay](https://docs.stripe.com/payments/afterpay-clearpay.md) - [Apple Pay](https://docs.stripe.com/apple-pay.md) - [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md) - [EPS](https://docs.stripe.com/payments/eps.md) - [GoPay](https://docs.stripe.com/payments/gopay.md) - [Google Pay](https://docs.stripe.com/google-pay.md) - [Kakao Pay](https://docs.stripe.com/payments/kakao-pay/accept-a-payment.md) - [Klarna](https://docs.stripe.com/payments/klarna.md) - [Cartão KR](https://docs.stripe.com/payments/kr-card/accept-a-payment.md) - [Naver Pay](https://docs.stripe.com/payments/naver-pay/accept-a-payment.md) - [Cartão NG](https://docs.stripe.com/payments/ng-card/accept-a-payment.md) - [PayPal](https://docs.stripe.com/payments/paypal.md) - [PayTo](https://docs.stripe.com/payments/payto.md) - [Pix](https://docs.stripe.com/payments/pix.md) - [PromptPay](https://docs.stripe.com/payments/promptpay.md) - [Revolut Pay](https://docs.stripe.com/payments/revolut-pay.md) - [Satispay](https://docs.stripe.com/payments/satispay.md) - [Stablecoins e cripto](https://docs.stripe.com/payments/stablecoin-payments.md) - [Swish](https://docs.stripe.com/payments/swish.md) - [TWINT](https://docs.stripe.com/payments/twint.md) - [UPI](https://docs.stripe.com/payments/upi.md) - [WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) ## Atualizar a assinatura [Lado do servidor] Você pode usar atualizações pendentes com as chamadas [atualizar assinatura](https://docs.stripe.com/api/subscriptions/update.md), [criar item de assinatura](https://docs.stripe.com/api/subscription_items/create.md) e [atualizar item de assinatura](https://docs.stripe.com/api/subscription_items/update.md). Quando fizer a atualização, defina `payment_behavior=pending_if_incomplete`. O exemplo abaixo adiciona um novo preço a uma assinatura. Como `proration_behavior=always_invoice`, uma fatura é criada e ocorre a tentativa de pagamento quando a atualização é feita. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` Se o pagamento for realizado, a assinatura é atualizada. Se falhar, o objeto `Subscription` que é retornado contém um hash `pending_update` com as alterações: ```json { "id": "sub_49ty4767H20z6a", "object": "subscription", "application_fee_percent": null, "pending_update": { "expires_at": 1571194285, "subscription_items": [ { "id": "si_09IkI4u3ZypJUk5onGUZpe8O", "price": "price_CBb6IXqvTLXp3f" } ] } } ``` ## Gerenciar pagamentos malsucedidos [Lado do cliente] Após fazer a atualização, verifique o hash `pending_update` na assinatura ou ouça o evento `customer.subscription.updated` no seu *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). Um hash `pending_update` preenchido significa que o pagamento falhou e sua atualização de assinatura não foi aplicada. Crie lógica para gerenciar falhas de pagamento causadas por recusas de cartão e solicitações de autenticação de clientes: - Para recusas de cartão, [anexe uma nova forma de pagamento](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method) ao cliente. Em seguida, use o endpoint [pagar](https://docs.stripe.com/api/invoices/pay.md) para pagar a fatura gerada pela atualização. - Para autenticação do cliente, siga o fluxo de [ação obrigatória](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). Um pagamento bem-sucedido aplica imediatamente as alterações no hash `pending_update` e atualiza a fatura para `paid`. Se o pagamento falhar novamente, o hash `pending_update` permanece na assinatura com a [data de validade](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) original e nenhuma alteração é aplicada. ## Optional: Cancelar ou alterar atualizações pendentes [Lado do servidor] Para cancelar uma atualização pendente, é preciso anular a fatura criada pela atualização. Verifique o atributo [última fatura](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-latest_invoice) na assinatura para encontrar o ID da fatura. Em seguida, use o ID para [anular](https://docs.stripe.com/api/invoices/void.md) a fatura. Você pode [atualizar uma assinatura](https://docs.stripe.com/billing/subscriptions/pending-updates.md#update-subscription) com novos valores em uma atualização pendente. Isso atualiza os valores no hash `pending_update`, anula a fatura associada à atualização pendente anterior e cria uma nova fatura para refletir os valores atualizados. O pagamento bem-sucedido dessa nova fatura aplica as atualizações mais recentes à assinatura. A falha no pagamento gera uma nova atualização pendente com uma nova[data de vencimento](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) para substituir a existente. ## Atributos aceitos para atualizações pendentes As atualizações pendentes aceitam apenas atributos que controlam o comportamento de cobranças proporcionais ou geram novas faturas. O endpoint de [atualização de assinatura](https://docs.stripe.com/api/subscriptions/update.md) aceita os seguintes atributos: - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `billing_cycle_anchor` - `items` - `price` - `quantity` - `trial_end` - `trial_from_plan` - `add_invoice_items` Os endpoints [criar item de assinatura](https://docs.stripe.com/api/subscription_items/create.md) e [atualizar item de assinatura](https://docs.stripe.com/api/subscription_items/update.md) aceitam os seguintes atributos: - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `price` - `quantity` ## Atualizações expiradas Se você não fizer nada depois que uma atualização falhar, a Stripe anulará a fatura e descartará a atualização após o vencimento. O horário `expired_at` de uma atualização pendente corresponde à primeira ocorrência do [fim da avaliação](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_end) ou do [fim do período items.current](https://docs.stripe.com/api/subscriptions/object.md##subscription_object-items-data-current_period_end) mais antigo. Isso se aplica quando um dos horários ocorre dentro de 23 horas da solicitação de atualização. Caso contrário, a expiração é de 23 horas a partir da solicitação de atualização. A Stripe também anula automaticamente a fatura e remove a atualização pendente se ocorrer uma das seguintes situações: - A assinatura atinge um limite de cobrança. - Um cronograma de assinatura vinculado à assinatura passa para uma nova fase. ## Eventos de atualizações pendentes Use [Webhooks](https://docs.stripe.com/webhooks.md) para escutar os seguintes eventos relacionados a atualizações pendentes. Os eventos são os mesmos, independentemente de você usar objetos `Customer` ou objetos `Account` configurados pelo cliente. | Evento | Objetivo | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.updated` | Receba notificações sobre assinaturas, verificando o hash `pending_updates` e [resolvendo falhas de pagamento](https://docs.stripe.com/billing/subscriptions/pending-updates.md#handling-failed-payments), se necessário. | | `customer.subscription.pending_update_applied` | Receba notificações quando atualizações pendentes forem aplicadas para que você possa realizar outras ações, como upgrade, downgrade, provisionamento ou desprovisionamento de serviços. | | `customer.subscription.pending_update_expired` | Receba notificações quando atualizações pendentes expirarem ou forem automaticamente anuladas e, se necessário, tente a solicitação de atualização novamente. | ## Atualizações pendentes e cronogramas de assinatura Você pode usar atualizações pendentes e [cronogramas de assinatura](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) para gerenciar assinaturas. Uma alteração de fase de programação elimina uma atualização pendente e anula a fatura associada. Tente novamente a solicitação de atualização após a transição de fase, se necessário. ## Itens medidos Se uma assinatura incluir itens medidos, a Stripe cobrará qualquer uso pendente na fatura de atualização pendente. No entanto, se a atualização pendente expirar antes do pagamento, a Stripe descarta esse uso, o que impede a cobrança disso nas faturas subsequentes. Se a atualização pendente remover um preço por consumo, Stripe desconsidera qualquer uso relatado entre a criação da atualização pendente e o pagamento da fatura resultante. Não é possível cobrar por esse uso. No entanto, se `billing_mode=flexible` estiver na assinatura, a Stripe cobrará pelo uso ao remover um preço por consumo.