Min.K | Stripe Developers | Page 1

nocturne orioleBOT Oct 31, 2023, 6:10 AM

#

Hello! We'll be with you shortly. Below are links to other discussions we've had with you in the past week in case you want to review that information. If your question is related to one of these previous discussions, please provide a comprehensive summary of the current state and what you need help with now. We help many users simultaneously, so a summary allows us to resolve your issue as soon as possible.

Min.K, 1 day ago, 17 messages

grand depot Oct 31, 2023, 6:12 AM

#

Question 1. Which events should I receive and process for completed and canceled payments?
I was wondering if I should receive and process the following 2 events. If not, please let me know which events I should use.
Payment completed - payment_intent.succeeded
Payment refunded - charge.refunded

Payment completed - payment_intent.succeeded - this one makes sense.

What do you mean by canceled payments though? Can you elaborate more on that?

small sigil Oct 31, 2023, 6:13 AM

#

What do you mean by canceled payments though? Can you elaborate more on that?

=>
A good way to think of it is if you made a purchase at the grocery store and wanted a refund.

That's what a canceled payment is.

grand depot Oct 31, 2023, 6:15 AM

#

ah, then it sounds like you want to be notified when a payment is refunded. Yes, charge.refund is what you want. In addition, you should also listen for charge.refund.updated to handle failed refunds : https://stripe.com/docs/refunds#failed-refunds

Refund and cancel payments

Learn how to cancel or refund a payment.

small sigil Oct 31, 2023, 6:17 AM

#

Thank you for your answer.

As for the question about one-time payments (Question 1), I think we've answered that.

I would like to ask you to answer questions 2 and 3.

grand depot Oct 31, 2023, 6:18 AM

#

Question 2. What events should I receive and process for subscriptions?
I'm wondering if it's correct to receive and process the following 3 events. If not, please let me know which events I should use.
Subscription paid - invoice.paid
Subscription repurchase completed - invoice.paid
Subscription payment refunded - charge.refunded
Subscription status updated - customer.subscription.updated
Subscription status canceled - customer.subscription.deleted

what's a subscription repurchase?

small sigil Oct 31, 2023, 6:19 AM

#

Because it's a subscription, it will pay for itself at regular intervals, often referred to as a renewal.

Think of it like if you have a Netflix subscription, it will automatically pay for itself every month.

#

I want to use the invoid.paid event for both the initial purchase of a subscription and subsequent automatic repurchases.

grand depot Oct 31, 2023, 6:20 AM

#

aaaah, the Subscription renewal is what we call it. Just to elaborate a bit more, you can differentiate between the different reasons using https://stripe.com/docs/api/invoices/object#invoice_object-billing_reason

Stripe API reference – The Invoice object – curl

Complete reference documentation for the Stripe API. Includes code snippets and examples for our Python, Java, PHP, Node.js, Go, Ruby, and .NET libraries.

#

The events you've listed for Subscriptions are correct

small sigil Oct 31, 2023, 6:22 AM

#

Question 3. I was wondering if payment_intent.succeeded is not fired on Subscription?

=> Would you please answer this last one?

grand depot Oct 31, 2023, 6:24 AM

#

It's possible that payment_intent.succeeded is not fired on Subscription. For example, if the invoice is $0.

small sigil Oct 31, 2023, 6:25 AM

#

It would be risky to use the payment_intent.succeeded event on a subscription, so we'll use invoice.paid.

#

If so, is it possible that payment_intent.succeeded might not be generated for zero ($0) payments, even for one-time payments?

grand depot Oct 31, 2023, 6:27 AM

#

you mean you're using one-off invoices?

small sigil Oct 31, 2023, 6:28 AM

#

This means using the Checkout Session API to use mode as payment.

grand depot Oct 31, 2023, 6:31 AM

#

hrm, i don't know off the top of my head, but I believe you won't receive payment_intent.succeeded, you'll likely only receive checkout.session.completed. I'd recommend testing it out to verify

small sigil Oct 31, 2023, 6:39 AM

#

I'd like to ask a question on a subscription basis.

If I get the checkout.session.completed event and process it, and then immediately get the invoice.paid event, I think it will be redundant. how should I handle it?

If I start paying for a subscription of 100$ via the Checkout Session API, I will get the

receive checkout.session.completed event and store it in DB as 100$ payment completed.
receive the invoice.paid event and store it in the DB as 100$ paid.

I think this is redundant, how should I handle it?

Should I distinguish them through the invoice billing reason you mentioned?

grand depot Oct 31, 2023, 6:42 AM

#

personally, i would think just going with the invoice.paid event would work.

#

and yes, you can distinguish them via the Invoice billing reason

small sigil Oct 31, 2023, 6:45 AM

#

personally, i would think just going with the invoice.paid event would work.

=> I'm curious as to why you think this.
=> First of all, using the checkout.session.completed event has the advantage that you can explicitly put the client_reference_id in. However, if you use the invoice.paid event, you don't have that space and have to put it in the metadata. Also, it's quite inconvenient to have to use the checkout.session.completed event for a one-time payment and invoice.paid for a subscription.
=> Why is it better to just use invoice.paid and not checkout.session.completed for subscriptions?

grand depot Oct 31, 2023, 6:48 AM

#

There's no real difference between processing metadata and client_reference_id on an object right? If you pass metadata into the relevant parameter on a Checkout Session (https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-subscription_data-metadata), it would also be reflected in the Subscription and Invoice (https://stripe.com/docs/api/invoices/object#invoice_object-subscription_details-metadata)

Stripe API reference – Create a Checkout Session – curl

Complete reference documentation for the Stripe API. Includes code snippets and examples for our Python, Java, PHP, Node.js, Go, Ruby, and .NET libraries.

Stripe API reference – The Invoice object – curl

Complete reference documentation for the Stripe API. Includes code snippets and examples for our Python, Java, PHP, Node.js, Go, Ruby, and .NET libraries.

small sigil Oct 31, 2023, 6:50 AM

#

Yes, but metadata can be accidentally changed by an operator in the console, so I think it's risky for developers developing APIs to rely on metadata. So I want to use a more explicit client_reference_id that is not modifiable in the console and is not configured as a key-value.

#

When the invoice.paid event is fired, is there any other way to tell if this is the first payment due to a subscription start or if it's a payment that occurred during the subscription cycle due to a renewal?

The billing_reason is a string, not an enum by the looks of it.

It seems risky to rely on this because it's a value that can change at any time.

nocturne orioleBOT Oct 31, 2023, 6:58 AM

#

grand depot Oct 31, 2023, 6:58 AM

#

I didn't take into consideration that you're using Checkout Sessions for both mode=payment, and mode=subscription. If you're using Checkout Sessions for both, then yes, you can listen for the checkout.session.completed event instead. Ultimately which event you use also depends on the information you need and what's efficient for your application

If you're using async payment methods, just keep in mind that there're other events that you'll need to listen for : https://stripe.com/docs/payments/checkout/fulfill-orders#delayed-notification

Fulfill orders with Checkout

Learn how to fulfill orders after a customer pays with Stripe Checkout or Stripe Payment Links.

#

regarding the billing_reason - we aren't going to change the values for it randomly. A lot of our users depend on the values returned there for their logic

small sigil Oct 31, 2023, 7:03 AM

#

Is it possible that the Invoice.paid event is also fired when the mode payment is selected in the checkout session API?

zenith prairie Oct 31, 2023, 7:05 AM

#

Hi @small sigil payment mode checkout session won't create an invoice, so no invoice.paid events

small sigil Oct 31, 2023, 7:06 AM

#

Here is my last question.

Is there an enum value that replaces billing_reason?

I'm wondering if there's any other way to distinguish if the payment is due to the first payment of the subscription or the cycle of the subscription.

zenith prairie Oct 31, 2023, 7:07 AM

#

Sure, the first invoices for a subscription will have billing_reason: subscription_create.

small sigil Oct 31, 2023, 7:08 AM

#

I'm not sure if I should use checkout.session.completed in subscriptions as well.

If I use checkout.session.completed, I need to also use invoice.paid to recognize the payment due to the subscription cycle.

This should eliminate duplication since the checkout.session.completed and invoice.paid events are sent at the same time for the first payment of the subscription.

To eliminate this duplication, we need to distinguish whether the invoice.paid event is issued due to the start of the subscription, such as billing_reason, or due to the cycle of the subscription.

zenith prairie Oct 31, 2023, 7:08 AM

#

Can you tell me what you want to achieve with Stripe API?

small sigil Oct 31, 2023, 7:15 AM

#

We just finalized a contract with Stripe and are working on development.

We want to API both one-time payments and subscriptions.

As such, we're looking to integrate the following events

For one-time payments

payment completed - checkout.session.completed
Payment refunded - charge.refunded

Subscriptions (First Option)

Subscription paid - checkout.session.completed
Subscription cycle re-purchase completed - invoice.paid (With billing_reason == subscription_cycle)
Subscription payment refunded - charge.refunded
Subscription status updated - customer.subscription.updated
Subscription status canceled - customer.subscription.deleted

Subscription (Second Option)

Subscription paid - invoice.paid
Subscription cycle re-purchase completed - invoice.paid
Subscription payment refunded - charge.refunded
Subscription status updated - customer.subscription.updated
Subscription status canceled - customer.subscription.deleted

For one-time payments, we've finalized how to integrate it.

But for subscriptions, I'm not sure which one to choose between option 1 and option 2.

zenith prairie Oct 31, 2023, 7:16 AM

#

I"d suggest you to take a look at https://stripe.com/docs/billing/subscriptions/webhooks you'll learn more about events related to subscriptions

Using webhooks with subscriptions

Learn to use webhooks to receive notifications of subscription activity.

small sigil Oct 31, 2023, 7:19 AM

#

I've read that documentation dozens of times already.

Is there an official way to recommend which webhooks to integrate with Stripe?

I'm looking for suggestions between the two first vs second options i mentioned above.

zenith prairie Oct 31, 2023, 7:20 AM

#

2nd option looks good to me. checkout.session.completed means the checkout session is completed, it doesn't necessary means the payment is succeeded.

small sigil Oct 31, 2023, 7:22 AM

#

Very good point!! Thanks!

If so, can you also advise on the one-time payment below?

For one-time payments
payment completed - checkout.session.completed
Payment refunded - charge.refunded

For one-time payments, is it better to use checkout.session.completed or another event?

#

I was thinking of using payment_intent.succeeded as a webhook for a one-time payment, but it seems that the payment_intent.succeeded event is not emitted when making a 0-cent payment, so I think it would be more appropriate to use another webhook event. Therefore, I would like to ask for suggestions on which webhook to use.

zenith prairie Oct 31, 2023, 7:26 AM

#

checkout.session.completed yes you can listen to this event, and check its payment_status to determine if a payment succeeds

#

No payment_intent is created for $0 checkout, so no payment_intent.succeeded event.

small sigil Oct 31, 2023, 7:28 AM

#

Thank you for your answer. In that case, I will use both one-time payments and subscriptions through the Checkout Session API and integrate the following webhooks.

For one-time payments
Payment completed - checkout.session.completed
Payment refunded - charge.refunded

For recurring payments
Subscription payment completed - invoice.paid
Subscription cycle repurchase completed - invoice.paid
Subscription payment refunded - charge.refunded
Subscription status updated - customer.subscription.updated
Subscription status canceled - customer.subscription.deleted

zenith prairie Oct 31, 2023, 7:29 AM

#

Looks good to me

small sigil Oct 31, 2023, 7:29 AM

#

Thanks have a good day

#Min.K