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.

Por padrão, atualizações são aplicadas quer o pagamento da nova fatura aconteça, quer não. Se o pagamento falhar, a aplicação das atualizações ocorre manualmente. É preciso criar uma nova fatura, fazer cobrança proporcional dos itens e iniciar o pagamento novamente. No entanto, com o recurso de atualizações pendentes, só é possível fazer alterações a assinaturas se um pagamento for bem-sucedido na nova fatura.

Cuidado

Atualizações pendentes não são aceitas quando o collection_method da assinatura é send_invoice ou débitos bancários são usados como forma de pagamento da assinatura.

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 a atualização, verifique o hash pending_update na assinatura. Para receber uma notificação automática, crie um webhook que escute o evento customer.subscription.updated. Se o hash pending_update for preenchido, o pagamento malsucedido e a assinatura continuarão o ciclo como se não houvesse solicitação de assinatura.

É comum que os pagamentos falhem por recusa da forma de pagamento ou porque exigem autenticação do cliente. Programe o gerenciamento das duas situações.

Use as instruções para falhas no pagamento para gerenciar recusas de cartão. É preciso vincular uma nova forma de pagamento ao cliente e usar o endpoint pagar para pagar a fatura gerada pela atualização.

Use as instruções ação do cliente para gerenciar a autenticação do cliente. Isso leva o cliente pelo processo de autenticação e, em seguida, paga a fatura.

Um pagamento bem-sucedido:

Aplica imediatamente as alterações no hash pending_update.
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

Veja também

Detalhes sobre o ciclo de vida, webhooks e atributos aceitos ao usar atualizações pendentes:

Referência de atualizações pendentes