Atualizações pendentes

Saiba como gerenciar falhas de pagamento ao atualizar assinaturas.

A atualização de uma assinatura gera uma nova fatura 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
Pedidos de desconto (aplicados a faturas futuras)
Ajustes de limiar de faturamento
Ambiente cancel_at_period_end paratrue
Adicionar cobranças únicas com add_invoice_items

Essas atualizações se aplicam imediatamente, sem implicações de pagamento. Para uma lista completa, consulteO que não aciona rateios.

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.

Antes de começar

Você poderá usar atualizações pendentes se o collection_method da assinatura for charge_automatically e se a forma de pagamento da assinatura for cartão ou Link.

Atualizar a assinatura
Lado do servidor

Você pode usar atualizações pendentes com as chamadas atualizar assinatura, criar item de assinatura e atualizar item de assinatura. 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.

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:

{
  "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. 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 ao cliente. Em seguida, use o endpoint pagar para pagar a fatura gerada pela atualização.
Para autenticação do cliente, siga o fluxo de ação obrigatória.

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 original e nenhuma alteração é aplicada.

OpcionalCancelar 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 na assinatura para encontrar o ID da fatura. Em seguida, use o ID para anular a fatura.

Você pode atualizar uma assinatura 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 novadata de vencimento 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 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 e atualizar item de assinatura 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 ou do fim do período items.current 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 para escutar os seguintes eventos relacionados a atualizações pendentes:

Evento	Objetivo
`customer.subscription.updated`	Receba notificações sobre assinaturas, verificando o hash `pending_updates` e resolvendo falhas de pagamento, 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 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.