The cancel API exists so that merchant partners can manage cart lifecycles. In an ideal world, the customer experience would roughly be outlined by:

<Steps> <Step title="Customer adds items to cart"> The customer browses your store and adds items to their shopping cart. </Step> <Step title="Customer initiates Truemed checkout"> The customer clicks the "Checkout with Truemed" button to begin the payment process. </Step> <Step title="Create payment session"> The partner calls `create_payment_session`, and an inventory lock is placed on the items in the cart to ensure they can be fulfilled when payment is captured. </Step> <Step title="Customer completes checkout"> The customer completes the survey and enters payment information in the Truemed interface. </Step> <Step title="Fulfill the order"> The merchant listens for the Partner webhook callback and fulfills the inventory locked above. </Step> </Steps>

Deviations from the Happy Path

In the flow above, there are a few steps the customer can take that would void the existing session.

The customer could:

• Navigate away from Truemed during the survey, and modify their cart. This dictates a new idempotency key (e.g.: a new payment_session). As part of clean up and to ensure the customer can't navigate back to the now outdated survey link, the old payment session must be canceled.
• Take too long to complete the survey and finalize payment. The merchant may wish to cancel the payment_session and release the lock on inventory as it appears the customer is no longer interested in making the purchase.

Customer Experience for Canceled Sessions

If this API is used to cancel a pending session, the customer will be shown a page indicating that the checkout session has timed out and a link will be provided to "Go back to checkout" which will return them to the failure_url provided in create_payment_session.

The page presented by the failure_url should be generic and display a relevant message asking the customer to checkout again if it has been too long.

"Too long" is defined by our merchant partners depending on their inventory management. We recommend 48-72 hours as customers will sometimes move funds into their HSA prior to completing checkout.

API Overview

The cancel_payment_session endpoint can be called after create_payment_session has been called, but before the customer has entered their payment information, for either kind=authorization or kind=one_time_payment.

The failure or success status is communicated to the partner via a webhook payment_session_complete as before.

Request Notes

There are no required fields for the request body, you simply call the endpoint with the payment_session_id in the URL. The cancel API can be called repeatedly without an idempotency key and the same result will be returned.

Important - you will only get a single callback queued on successful cancelation (albeit, invoked multiple times in the case of failures) as outlined in Partner webhook, even if you call the cancel endpoint multiple times.

Response Notes

Success Case

HTTP Status: 200

Note: order_items.sku - the partner's SKU for the item. The value of this field will be the SKU provided by the partner in the create_payment_session request. If the partner does not provide a SKU value for an item on creation of the payment, this key will not be present.

Failure Case

HTTP Status: 400

If a field is missing or the request otherwise can't be processed, we'll return a 400 with the following fields:

• error - can be one of:
  • InvalidPaymentId - the payment_session_id does not exist.
  • ServerError - There was an internal server error. Requests can be retried.
  • SessionCaptured - The session has already been captured via a call to /payment_session/{payment_session_id}/capture and can no longer be canceled. In this case, to return funds to the customer, you'll need to issue a refund.
  • SessionAuthorized - The session has already been authorized. The user has completed the survey and entered their credit card information. In this case, the session should be voided via the Void Session API, and the customer should be informed that their order has been canceled.
• message - Details on the above conditions.