Stripe : Callbacks Cheatsheet (Copied for reference)


Simple One-off Purchases with Charges

1. Customer successfully purchases a single one-off item

The simplest possible starting point. A single one-off purchase.

2. Customer’s card is declined

This event also describes other failure modes, like an invalid expiration date or a failed CVC check if you have the option turned on to decline on a failed check.

3. Customer successfully purchases and then requests a refund

Typically you’ll hit the refund button in Stripe’s management interface to generate a refunded event.

4. Create a charge without capturing it, capture later

Normally charges are authorized (check with the bank for available funds) andcaptured (actually request a fund transfer) at the same time. Stripe allows you to separate the two events. For example, if you’re shipping goods that have a few days of lead time you’d want to authorize the charge up front but only capture it when you actually ship.

5. Charge then modify description

After making a charge you can update the `description` and `metadata` fields to add or alter application-specific information.


6. Customer disputes a charge, you upload evidence

Disputes happen. It’s just a fact when you’re charging people money. Stripe will of course send your application a series of webhooks as the dispute process plays out.


7. Create customer and charge them immediately

This is the same flow as a simple charge with the added benefit of being able to charge the customer again later.

8. Create a customer with a plan without a trial

Customer and subscriptions are where Stripe’s webhook system really starts to shine. All of these events happen more or less simultaneously when you create a customer object and include the plan_id and card attributes.

9. Create a customer with a plan with a trial

Trials let you give a customer a taste of your application before charging them. Stripe will create a $0 invoice and “pay” it when you create the subscription, and then later will send you a customer.subscription.trial_will_end three days before creating the first real invoice.

10. Create a customer with a plan with a discount, no trial

Discounted subscriptions are essentially the same as a normal subscription with one more event, ``.

11. Invoice charge attempt succeeds

The normal course of events with a subscription is that the invoice is paid properly and on time. Stripe will send an `invoice.created` event one hour before attempting to pay the invoice, which gives you time to add items to the invoice for balance billing or utility-style billing purposes.

12. Invoice charge attempt fails

When you run a subscription service eventually you’ll have customers who cancel their card without telling you. When that happens Stripe will send you a series of events. The key event is invoice.payment_failed, the rest just update various attributes on the corresponding Subscription and Customer. Stripe will attempt payment three times. After the third failed attempt thecustomer.subscription.updated event will be replaced with acustomer.subscription.deleted event.

13. Existing customer, adding invoice items

Adding invoice items for a customer without specifying an invoice will automatically add them to the next month’s invoice. Pretty handy for doing usage billing, since you can just roll up the customer’s daily usage and build an invoice item for every day.

14. Customer modifies existing card

Stripe’s Card API lets you update some details about a card without fully adding a new one. For example, a customer’s address changes or they get a new expiration date.

  • customer.card.updated (Card )

15. Customer changes to a different card

Of course if a customer wants to change their card entirely they have that option. This is the set of events that happens when you assign to the customer’s `card` attribute. The sequence of events is essentially the same if you add a card and change their default card manually, just without the delete event.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s