Skip to main content

Introduction

Off-session checkouts for a product requiring a Letter of Medical Necessity need two key steps to work as intended:
  1. Having the customer complete the initial (on-session) checkout session
  2. Using the customer’s off-session-verified payment method (along with their customer_id) from step 1 in subsequent off-session checkouts
Important: For any product requiring a Letter of Medical Necessity, the customer must have an approved Letter for that product. Without it, no off-session checkout sessions will work. They can receive this letter during the initial on-session checkout discussed in the next section. If they are denied a letter or don’t have one, off-session checkouts will not work with that customer for the associated product(s).

Initial (on-session) checkout session

This step is vital to ensure all future off-session payments work. During the initial on-session checkout, the customer will:
  • Go through the checkout consultation to determine if they are eligible to receive a Letter of Medical Necessity for the product(s) in the checkout.
  • Provide a valid payment method that will then be verified for future off-session payments (assuming the payment is successful).
  • Be assigned a Flex customer_id if they’re new to Flex. Returning customers already have one.
All of these components are vital to ensure future off-session payments for the customer work as expected.

Example on-session checkout creation

The key difference here compared to other checkouts is making sure you set the setup_future_use parameter to off_session. This is how Flex knows to validate the payment method used in the checkout for future off-session payments.
This will create a checkout session that the customer will then go through to receive their letter and submit their initial payment. After the customer fills out their payment information and clicks “Pay Now” and the payment successfully goes through, the customer will have:
  • A valid Letter for the product. Flex uses this letter when determining whether future off-session payments can go through
  • A customer_id
  • A verified payment_method
That is everything you’ll need for future off-session payments.

Off-session checkout creation

Now that we have access to:
  • The customer’s customer_id
  • The customer’s off-session verified payment_method
  • A validated Letter attached to the customer for the product
We can move forward with off-session payments.

Getting customer_id

The customer_id is a required field for off-session checkouts, and is also useful for programmatically finding the customer’s payment method(s). There are several ways to obtain it:
  • Grabbing it from the checkout.session.completed webhook event that is fired when the checkout session completes
  • Using the associated checkout session’s ID with the GET Checkout endpoint, and grabbing it from the returned checkout session object
  • Finding it with the List Customers endpoint
  • Finding it in the Customers tab of the Flex Dashboard

Getting payment_method ID

Now that we have the customer_id, use the List Payment Methods endpoint to find the customer’s payment method approved for off sessions. The returned payment method object shows the off_session field set to true when it’s viable.

Example off-session checkout

Now, to use all of this information to complete an off-session payment, plug it into the correct places in the Off-Session Checkout call:
A successful call will return a response with the key details:
If you get a response like the above, you have successfully set up an off-session checkout flow.

Additional information

What happens if the customer does not have a letter for the product?

If you try to submit an off-session payment in this scenario, the call will fail with an error response like this:
This indicates the customer doesn’t have a valid letter for the product. They can’t use off-session checkouts for it until that letter is acquired.

Do letters ever expire once a customer gets one?

Yes, letters remain valid for 1 year from the day the customer goes through the consultation. To use off-session payments for longer than that, customers go through the on-session flow once per year. This keeps a valid letter on file.

Will one letter cover a customer for all products?

Not necessarily. Letters are tied to specific visit_type values, so a letter only applies to products that fall under the same visit_type. For example, say a customer completed an on-session checkout for a product under the gym visit type. They’d then have a valid letter for every product in your catalog with a gym visit type. You could use an off-session payment immediately for those products without the customer needing to go through the on-session flow again. However, if they wanted to purchase a product under the skincare visit type, the gym letter would not be sufficient. The customer would need another on-session checkout consultation to receive a skincare letter. Only then would off-session payments work for those products.