Stripe
Bridge supports billing integrations with Stripe. To get started, you will need to provide your Stripe account’s API key. You will also need to establish a webhook in your Stripe account, sending events back to the Bridge API.
Bridge will create payment methods using Stripe’s Setup Intent API.
Bridge will create and manage payments using Stripe’s Payment Intent
Bridge will settle final payments using Stripe’s Invoice APIs.
Refer to the Stripe documentation for more details.
How to integrate using Stripe
Collecting a Payment Method
Once a Bridge Patient has been created, use Patient.id to create a Stripe Setup Intent. Bridge will return a Stripe secret key as clientSecret.
With the Stripe clientSecret, you can use Stripe’s Web Elements UI components (or similar) to collect card information to be saved to the Patient’s Stripe profile.
Creating an Estimate Charge
After creating a Service Eligibility, use the ServiceEligibility.id and Patient.id together to create an Estimate Charge. This record will be used to drive payment actions, and inherits the same estimate amount that the Service Eligibility indicates.
Estimate Charges are attached to a Service Eligibility as the source for the estimate amount. When you create an Estimate Charge, be sure to use the same Service Eligibility to create the Service later. If you’ve already created the Service, be sure to use the Service Eligibility ID found in the Service response object.
Authorize an Estimate Charge
Once created, the Estimate Charge can optionally be Authorized, verifying that the payment method is valid and able to cover the expected amount.
Authorization is not required, but is recommended. Authorizations in Stripe can be set to expire after a set amount of time.
If the provided payment method is invalid, possesses insufficient funds, or requires additional actions on behalf of the user, the Bridge API response will forward the Stripe-specific details for additional handling. This may require extra Stripe UI components to take additional actions, or else will require the Patient to provide a different payment method. For more detail, see the Stripe payment errors documentation.
An Estimate Charge that is returned with the AUTHORIZATION_FAILED status can be re-attempted once any additional action has been taken, or if a new payment intent is created.
Capture an Estimate Charge
When ready to collect payment, the Estimate Charge can be Captured.
If the provided payment method is invalid, possesses insufficient funds, or requires additional actions on behalf of the user, the Bridge API response will forward the Stripe-specific details for additional handling. This may require extra Stripe UI components to take additional actions, or else will require the Patient to provide a different payment method. For more detail, see the Stripe payment errors documentation.
An Estimate Charge that is returned with the CAPTURE_FAILED status can be re-attempted once any additional action has been taken, or if a new payment intent is created.
Cancel an Estimate Charge
An Estimate Charge than has been authorized, but not captured, will expire after several days if no action is taken. However, you can immediately Cancel the Estimate Charge if you wish.
Refund an Estimate Charge
If a captured Estimate Charge needs to be refunded prior to final billing for a Service, you can issue Refund. This may be necessary in the case where a scheduled service is cancelled.
If the refund cannot be completed for any reason, the Bridge API response will forward the Stripe-specific details for additional handling. For more detail, see the Stripe refund errors documentation.
Invoicing
After a Service has been completed and claim adjudication has resolved, check the Bridge dashboard for the Service to enter the SETTLING status. This will indicate that a final invoice is being generated.
Any necessary payments or refunds will be handled automatically to settle the payment balance for the Service. The Service should move to COMPLETED after several minutes, and an invoice with receipt PDF will be available, linking out to Stripe from the Bridge dashboard.
Putting it together
The suggested workflow for collecting Service estimates through the Bridge API is as follows:
- Create a Policy, then a Service Eligibility, and finally a Patient in Bridge. We now have everything we need to both schedule a Service and create an Estimate Charge.
- Collect a payment method for the Patient.
- Create an Estimate Charge for the Patient and Service Eligibility.
- Schedule Service for the Patient.
- Prior to the date of service, authorize the Estimate Charge.
- If the response is not AUTHORIZED, prompt the Patient for corrective action or return to the payment method collection step to try a different method.
- On the day of service, capture the Estimate Charge.
Error handling with Stripe
Should an attempted payment authorization or capture be unsuccessful, Stripe will provide additional details that Bridge will forward to you. The Stripe error objects will indicate what next steps you can take to either resolve an incomplete payment, or redirect the Patient to payment method collection again.