---
# System prepended metadata

title: Stripe API Notes

---

# Stripe API Notes

## Webhook in the existing system

### in both
**"charge.succeeded"**
  - Occurs whenever a charge is successful. (charge) it will trigger when an invoice is successfully paid, but it'll also trigger for one-off payments.

**"invoice.payment_failed"**
  - Occurs whenever an invoice payment attempt fails, due either to a declined payment or to the lack of a stored payment method. (invoice)

**"customer.subscription.updated"**
  - Occurs whenever a subscription changes (e.g., switching from one plan to another, or changing the status from trial to active). (subscription)

**"customer.subscription.deleted"**
  - Occurs whenever a customer's subscription ends. (subscription)

### in new only
**"invoice.payment_succeeded"**
  - Occurs whenever an invoice payment attempt succeeds. (invoice)

**"customer.updated"**
  - Occurs whenever any property of a customer changes. (customer)

**"customer.subscription.created"**
 - Occurs whenever a customer is signed up for a new plan. (subscription)

**"payment_intent.created"**
  - Occurs when a new PaymentIntent is created. (payment intent)

### in old only
**"customer.discount.created"**
   - Occurs whenever a coupon is attached to a customer. (discount)

**"customer.card.updated" (?), "customer.source.updated", "customer.card.created" (?), "customer.source.created"**

  - Occurs whenever a source's details are changed. (e.g. card) ("customer.source.updated")
  - Occurs whenever a new source is created for a customer. (e.g. card) ("customer.source.created") - when adding a new card for the customer.

**"charge.dispute.created"**
  - Occurs whenever a customer disputes a charge with their bank. (dispute)

**"charge.refunded"**
  - Occurs whenever a charge is refunded, including partial refunds. (charge)

## Objects
  Charge
   - The Charges API is an older payments API that doesn’t handle bank requests for card authentication, and it can’t be used by merchants in India. Try our new payments APIs and integrations instead.

  Invoice
  Customer
  Customer.Subscription
  Customer.Source (card)
  PaymentIntent
  
  -------------------------------
  TESTING IN MY STRIPE ACCOUNT
  
  Created user
  customer.created
  
  
  Difference between invoice.paid and invoice.payment_succeeded
  https://stackoverflow.com/questions/64197693/stripe-subscription-events-webhooks-are-not-clear
  
"..In your case, you probably only want to listen to invoice.payment_succeeded. When you get the invoice, look at the billing_reason field: https://stripe.com/docs/api/invoices/object#invoice_object-billing_reason

If it's set to subscription_create, then send your congratulatory email. If it's subscription_cycle, then it's because the subscription entered a new billing cycle and the payment succeeded..."

========================================

## Happy path with subscription checkout:

- Wait for `checkout.session.completed` webhook. This is only sent when the checkout has been successful (when paid with a card). We will not track of any failed checkout attempts.
- Sending the customer a receipt email.?
- Create Entitlements record. Maybe add a day or two for leeway to `current_period_end`?

Notes: We don't have to look for `invoice.paid`	or `invoice.payment_failed` because the `checkout.session.completed` only happens when the purchase is successfull.

## Happy path with subscription renewal:

- wait for webhook `invoice.paid` or `invoice.payment_succeeded`
- update `current_period_end` in Entitlements table.


## Handle subscription state that needs an action
 
 - wait for webhook `invoice.payment_failed` or `customer.subscription.updated`? - `invoice.payment_failed` to check the status. set entitlements to status `past_due`?
 - send user to stripe customer portal to update the payment method.
 - after successfully updated wait for webhook `invoice.payment_succeeded` or `customer.subscription.updated` 
 set entitlements to status `active`?
## Handle 


=======================================
## checkout.session.completed

https://stripe.com/docs/payments/checkout/fulfill-orders#fulfill

To fulfil the order, you’ll need to handle the checkout.session.completed event. Depending on which payment methods you accept (for example, cards, mobile wallets), you’ll also optionally handle a few extra events after this basic step.


Stripe emits the checkout.session.completed event each time one of your users successfully goes through the checkout flow:

https://stripe.com/docs/api/events/types#event_types-checkout.session.completed

The event won't be emitted if a user's payment fails, or if they fail to provide any of the required fields. There will however be other events (e.g., payment_intent.payment_failed) that will be emitted if you wanted to track failed attempts.


==================================

## Difference between Charge Payment Intent and Stripe Checkout
https://stripe.com/docs/payments/payment-intents/migration/charges

Stripe Checkout is a prebuilt payment page that you can redirect your customer to for simple purchases and subscriptions.

The Charges and Payment Intents APIs let you build custom payment flows and experiences.