This guide explains how to place a hold on a customer’s payment method, which is particularly useful when you need to verify something (like a prescription approval) before charging the customer.

​
What is a Payment Hold?

A payment hold:

  1. Ensures that the customer has enough funds to cover the cost of the order.
  2. Holds the funds for a certain period of time, to ensure they’re available to complete the payment.
  3. Allows you to verify necessary information before actually charging the customer.

​
Important Limitations

You will need to manually release the hold on the user’s card at a later date to complete the payment.

This is not handled by Embeddables, since it happens at a later stage when the user is no longer interacting with the Embeddable.

Stripe only supports placing a hold on one-time payments, not recurring payments.

To achieve the effect of a hold on a recurring payment, you’ll need to use a combination of a one-time payment and a delayed subscription, as explained below.

​
Common Use Case: Prescription Approval

A common use case for payment holds is when you need to verify a prescription before charging the customer. Here’s how this typically works:

  1. At checkout, place a hold on a one-time payment for the first month’s cost.
  2. When the prescription is approved, release the hold to charge the customer.
  3. At the same time, set up a subscription that’s delayed by 30 days.

This approach ensures that:

  • The customer isn’t charged until their prescription is approved.
  • The subscription doesn’t start charging until 30 days after the prescription is approved.
  • The one-time payment effectively replaces the first month of the subscription.

​
Implementation Steps

1

Set up the one-time payment hold

This part is handled by Embeddables.
  • In your Stripe component, select “Payment” as the Checkout mode.
  • Enable the “Place a hold on the customer’s card” option.
  • Use a one-time payment price ID (not a subscription price ID).
2

Handle the prescription approval

This part is handled by your own backend systems (not Embeddables).
  • When the prescription is approved, release the hold on the payment.
  • Create a new subscription for the customer with a 30-day delay.
  • The subscription should hopefully use the same payment method that was used for the hold, but you will need to verify this as it’s outside of Embeddables’ control.

When you place a hold on a payment, Stripe automatically creates a customer record and stores the payment method. This means you can later attach a subscription to this customer without requiring them to re-enter their payment details.

​
Best Practices

  1. Clear Communication:

    • Clearly communicate to customers that their payment method is being held but not charged.
    • Explain when they can expect to be charged.
    • Provide information about the subscription that will start after the first payment.

  2. Error Handling:

    • Have a process in place for handling declined payments when releasing the hold.
    • Consider what happens if the prescription is not approved.

  3. Subscription Management:

    • Ensure your backend system can handle the creation of delayed subscriptions.
    • Consider how you’ll manage the transition from the one-time payment to the subscription.

For more information on how placing a hold works in Stripe, see the Stripe documentation.

​
Frequently Asked Questions