Payment Session Complete Webhook

The partner is required to implement an endpoint that Truemed can send requests to inform of the checkout status.

We’ll call the payment_session_complete webhook once each time the status of the payment_session changes, including sessions that have been canceled, voided, and captured. For delayed capture, we’ll issue the webhook call for authorization (when the customer first successfully enters card information), and again after the partner has manually captured funds via the capture api.

In successful payment cases, we’ll first issue a webhook indicating that the payment_session has transition from pending to processing, after which you can expect a webhook transitioning from processing to captured (in the default / immediate capture cases), and to authorized in the case of Manual/Delayed Capture.

Important

Orders should not be fulfilled until a webhook is received with a status of captured.

Authentication: Partners should verify the request comes from Truemed by checking that the API key is present in the x-truemed-api-key HTTP header.

Request Notes

Headers:

x-truemed-api-key - The partner’s API key.

Notable fields:

status - the status of the payment from Truemed’s perspective
- captured - payment has completed
- canceled - payment was canceled before the user entered payment information via a call to our cancel API.
- pending - payment has not been successfully completed yet.
- processing - the customer has entered their payment information, but it is under review by Truemed
  - Any customer facing communication should indicate successful payment at this point, such as on the success_url.
  - The merchant should not fulfill the order until the Payment Session Webhook indicates that the payment has been captured.
- rejected - While in the processing state, Truemed reviewed and rejected the payment session.
  - The merchant should not fulfill these orders, and should communicate failure to the user via email.
- authorized - an auth hold has been placed on the customer’s card.
- authorization_voided - the auth hold has been voided via a call to our Void Session api.
- authorization_expired - the auth hold has expired and we were not able to re-auth the transaction. This state is only possible after a call to our Manual Capture api, and is only set after we attempt a re-auth hold on the existing payment method.
capture_amount (Optional) - the amount of funds actually captured.
- For payment sessions of kind=one_time_payment this field will always be present and will be the same as authorize_amount.
- For payment sessions of kind=authorization this field will not be present until the funds have been captured (via a call to Manual Capture).
order_items - a list of order items, with the following fields per item:
- total_refundable (Optional) - If the Payment Session has been captured, this value will be the remaining amount refundable for this item. Otherwise it will not be included.
- quantity_refundable (Optional) - If the Payment Session has been captured, this value will be the remaining quantity refundable for this item. Otherwise it will not be included.
- total_capturable (Optional) - If the Payment Session is an authorization and is currently authorized, this value will be the remaining amount capturable for this item. Otherwise it will not be included.
- quantity_capturable (Optional) - If the Payment Session is an authorization and is currently authorized, this value will be the remaining quantity capturable for this item. Otherwise it will not be included.
payment_token (Optional) - Optional string indicating the payment_token used for the payment session. This field will be set only if the partner provided tokenize=True or a payment_token in the create_payment_session request, as outlined in our Subscriptions Flow

Response Body Documentation

Success Case

HTTP Status: 204

The partner does not need to include any content in the body

Failure Case

Truemed will retry the requests to your backend with backoff for up to 7 days

The partner is required to implement an endpoint that Truemed can send requests to inform of the checkout status. We'll call the `payment_session_complete` webhook once each time the `status` of the `payment_session` changes, including sessions that have been canceled, voided, and captured. For delayed capture, we'll issue the webhook call for authorization (when the customer first successfully enters card information), and again after the partner has manually captured funds via the capture api. In successful payment cases, we'll first issue a webhook indicating that the `payment_session` has transition from `pending` to `processing`, after which you can expect a webhook transitioning from `processing` to `captured` (in the default / immediate capture cases), and to `authorized` in the case of [Manual/Delayed Capture](/guides/payment-sessions/manual-delayed-capture). <Warning title="Important"> Orders should not be fulfilled until a webhook is received with a status of `captured`. </Warning> **Authentication**: Partners should verify the request comes from Truemed by checking that the API key is present in the `x-truemed-api-key` HTTP header. ## Request Notes Headers: - `x-truemed-api-key` - The partner's API key. Notable fields: - `status` - the status of the payment from Truemed's perspective - `captured` - payment has completed - `canceled` - payment was canceled before the user entered payment information via a call to our cancel API. - `pending` - payment has not been successfully completed yet. - `processing` - the customer has entered their payment information, but it is under review by Truemed - Any customer facing communication should indicate successful payment at this point, such as on the `success_url`. - The merchant should not fulfill the order until the Payment Session Webhook indicates that the payment has been captured. - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment session. - The merchant should not fulfill these orders, and should communicate failure to the user via email. - `authorized` - an auth hold has been placed on the customer's card. - `authorization_voided` - the auth hold has been voided via a call to our Void Session api. - `authorization_expired` - the auth hold has expired and we were not able to re-auth the transaction. This state is only possible after a call to our Manual Capture api, and is only set after we attempt a re-auth hold on the existing payment method. - `capture_amount` **(Optional)** - the amount of funds actually captured. - For payment sessions of `kind=one_time_payment` this field will always be present and will be the same as `authorize_amount`. - For payment sessions of `kind=authorization` this field will not be present until the funds have been captured (via a call to Manual Capture). - `order_items` - a list of order items, with the following fields per item: - `total_refundable` **(Optional)** - If the Payment Session has been captured, this value will be the remaining amount refundable for this item. Otherwise it will not be included. - `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this value will be the remaining quantity refundable for this item. Otherwise it will not be included. - `total_capturable` **(Optional)** - If the Payment Session is an authorization and is currently authorized, this value will be the remaining amount capturable for this item. Otherwise it will not be included. - `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is currently authorized, this value will be the remaining quantity capturable for this item. Otherwise it will not be included. - `payment_token` **(Optional)** - Optional string indicating the `payment_token` used for the payment session. This field will be set only if the partner provided `tokenize=True` or a `payment_token` in the `create_payment_session` request, as outlined in our Subscriptions Flow ## Response Body Documentation ### Success Case HTTP Status: `204` The partner does not need to include any content in the body ### Failure Case Truemed will retry the requests to your backend with backoff for up to 7 days

Payload

The payload of this webhook request is an object.

authorize_amountintegerRequired

The amount the user’s card will be authorized for. In the case of kind=one_time_payment, this will always be the same as capture_amount

captureslist of objectsRequired

List of capture details for the payment session

created_atstringRequired

ISO-8601 timestamp of when the payment session was created

order_itemslist of objectsRequired

A list of order items with fields: item_id, name, price, quantity, sku, total_refundable (optional), quantity_refundable (optional), total_capturable (optional), quantity_capturable (optional)

payment_idstringRequired

The id returned to the partner by Truemed in response to a create_payment_session request

statusenumRequired

The status of the payment from Truemed’s perspective. Can be: captured, canceled, pending, processing, rejected, authorized, authorization_voided, authorization_expired

capture_amountinteger or nullOptional

The amount of funds actually captured. For payment sessions of kind=one_time_payment this field will always be present and will be the same as authorize_amount. For payment sessions of kind=authorization this field will not be present until the funds have been captured

metadatastring or nullOptional

Optional field echoed back if present in the call to create_payment_session

payment_tokenstring or nullOptional

Optional string indicating the payment_token used for the payment session. This field will be set only if the partner provided tokenize=True or a payment_token in the create_payment_session request

Response

204

Webhook received successfully (HTTP 204 No Content)

400

Invalid payload or authentication failure

500

Server error processing webhook