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`](/api-reference/payment-sessions/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.