just-john_best-practices | Stripe Developers | Page 1

onyx orbitBOT Oct 4, 2024, 1:40 AM

#

👋 Welcome to your new thread!

⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.

⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.

🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1291575646811852931

📝 Have more to share? Add more details, code, screenshots, videos, etc. below.

#

restive egret Oct 4, 2024, 1:46 AM

#

The gap between the first payment and the ongoing rent is the part that's not really addressed in the docs.
Option 1 initially seems like the most straight forward use of the APIs, but it would be nice to track everything in a single subscription and separate it into multiple API calls.
Option 2 is cleaner from a outside perspective, but it looks like the subscription model isn't really designed to have gaps, and I'm a little worried about running into complications.

quasi temple Oct 4, 2024, 1:47 AM

#

When the customer reserves, do you know the length of the stay at this time? Or will the reserved period be only known later?

restive egret Oct 4, 2024, 1:48 AM

#

Yes, we do know the length of stay.

#

Oh, I saw one other thing in the docs that might be useful, but I didn't understand the behavior: I think it was creating a subscription and passing back a paymentIntent ID, which it looks like it would be paid immediately if confirmed by the front end.

#

If I could create the subscription for the future dates when it is actually active, but have the customer pay the first portion immediately (option 3?) that seems like it would be better than the 2 options I already gave.

#

But I don't know if that's what happens if I try to confirm payment for the first part on the front end, or if it will try to pay later or fail because I'm asking it to pay something that isn't due.

#

One more piece of context: We are using react elements to take the payment info

quasi temple Oct 4, 2024, 2:02 AM

#

In this case, I'd recommend:

If the customer stays less than one month, charge for one-time payment (and save the payment method in case any future charge is needed): https://docs.stripe.com/payments/save-during-payment
If the customer stays more than one month, use Subscription Schedule to manage the monthly payments: https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases#installment-plans

In both flows, a Payment Intent will be created, which you can pass its client secret to Payment Element (at front end) to collect the payment method details and complete the payment.

Save payment details during payment

Learn how to save payment details during a payment.

Subscription schedules use cases

Learn how to use subscription schedules.

#

Subscription is only recommended when you attempt to charge the customer on the monthly (regular) basis. If the duration is less than a month, one-time payment should be used

restive egret Oct 4, 2024, 2:05 AM

#

The customer will never stay less than one month. They may stay exactly one month though. And we could potentially extend do the single payment if it's just a couple days over a month.

quasi temple Oct 4, 2024, 2:06 AM

#

Ah I see! Am I right to understand following?

Customer will stay more than 1 month (or exactly one month)
You would like to charge one-time deposit in the first month

restive egret Oct 4, 2024, 2:07 AM

#

Those are both correct.

quasi temple Oct 4, 2024, 2:07 AM

#

This makes things simpler

restive egret Oct 4, 2024, 2:09 AM

#

I do need clarification on the subscription in the multi-month case. Would that be a 3 phase subscription with the "correct" (future) dates, but then if I pass back the client secret and confirm the first paymentIntent it will be charged immediately and the later phases (if any) would not be billed until their correct times?

quasi temple Oct 4, 2024, 2:11 AM

#

I'd recommend using Subscription Schedule with this. Give me some time to type out how this should be done

#

https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases#installment-plans should be used with some additional settings. In fact, only one phase is needed. In your first phase, you will include an one-time invoice item for security deposit using phases.add_invoice_item. The code for phases will look like this:

{
  ...
  phases: [
    {
      items: [
        {
          price: 'price_xxx', // For monthly fee
          quantity: 1
        }
      ],
      add_invoice_items: [
        {
          price: 'price_xxx', // One-time security deposit in the first month invoice
          quantity: 1
        }
      ],
      iterations: 2, // Duration of the stay. You can use iterations for full month stay or `end_date` for the custom date
    }
  ],
  end_behavior: 'cancel', // Cancel the subscription after the schedule ends
  expand: ['subscription'],
  start_date: 'now',
}

Subscription schedules use cases

Learn how to use subscription schedules.

#

When a subscription is created, you can then finalise the first invoice to get the latest payment intent and its client secret to collect payment method

#

I'd recommend using test clock to test this out: https://docs.stripe.com/billing/testing/test-clocks

Test your integration with test clocks

Learn how to move Billing objects through time in test mode.

restive egret Oct 4, 2024, 2:32 AM

#

Okay, the add_invoice_items is a good tip, but I'm not sure if I understand how this addresses the gap between first payment and ongoing payments, and the last payment most likely not being a full month. Let me show an example to see if we are on the same page.

quasi temple Oct 4, 2024, 2:33 AM

#

Yup! An example will be helpful for me to understand the gaps

#

last payment most likely not being a full month
In my code comment, you can use iterations for full month stay or end_date for custom date (not full month)

restive egret Oct 4, 2024, 2:34 AM

#

I book today for Jan 1 to April 10. With $1000 rent and $500 security deposit. I should pay
$1500 today
$1000 Feb 1
$1000 Mar 1
$333 Apr 1

quasi temple Oct 4, 2024, 2:35 AM

#

Yes, above code will work charge exactly the same, except that you will use end_date to set to Apr 10, instead of using iterations

restive egret Oct 4, 2024, 2:36 AM

#

Okay, so if I do start date Jan 1, end date Apr 10, do add_invoice_items for the security deposit for the first month to set it up, then return the secret and confirm the first paymentIntent, would I get the behavior in my example?

quasi temple Oct 4, 2024, 2:39 AM

#

Yes, it will get the exact same behaviour as your example.

phases: [
  {
    items: [
      {
        price: 'price_xxx', // For monthly fee
        quantity: 1
      }
    ],
    add_invoice_items: [
      {
        price: 'price_xxx', // One-time security deposit in the first month invoice
        quantity: 1
      }
    ],
    end_date: 1727740800, // Duration of the stay. You can use `iterations` for full month stay or `end_date` for the custom date
  }
],

restive egret Oct 4, 2024, 2:43 AM

#

Okay cool. This would be much better than payment plus subscription. 🙂

One clarification: end_date says duration but in the docs it looks like that is a timestamp not a duration.

#

It should be the timestamp for Apr 10, correct?

quasi temple Oct 4, 2024, 2:47 AM

#

Yes, this is the timestamp of when the subscription should be ended.

#

Sorry for the confusion by using duration

#

I tested myself with the above code, and it behaves exactly like the example you shared

#

I'd recommend using test clock to test the flow above: https://docs.stripe.com/billing/testing/test-clocks to see how the customer is charged each month

Test your integration with test clocks

Learn how to move Billing objects through time in test mode.

restive egret Oct 4, 2024, 2:51 AM

#

Awesome. I am wrapping up for the day, but I will start setting this up and hopefully give it a try with the test clock tomorrow!

#just-john_best-practices