paymentSessions

Retrieve the current status of a payment session

Get the status of a payment session based on the payment session id.

Request Notes

To get the status of a Payment Session object, call the detail view with the ID of the payment session returned by the create_payment_session endpoint.

Response Notes

  • status - the status of the initial payment, an enum with one of the following values:
    • 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.
  • status_summary - a summary of the overall payment session. This includes refunds and disputes, and is an enum of the following values:
    • Incomplete - Customer started checkout but did not complete
    • Authorized - Auth hold placed on customer's payment method
    • Captured - Payment has been processed
    • Partially Captured - The payment has been partially processed
    • Refunded - The full amount charged in this order has been refunded to customer
    • Partially Refunded - Part of the original order has been refunded to the customer
    • Disputed - The transaction has been disputed by the customer
    • Voided - The payment was voided by the partner
    • Expired - The partner did not capture an authorized session before it expired
  • order_items - a list of order items, with the following fields per item:
    • item_id - The item_id that uniquely identifies this item. If the client specified one when creating the Payment Session, that item_id will be returned.
    • name - the name of the item
    • price - the unit price in cents charged for the item
    • quantity - the number of this item in the cart
    • sku - the partner's SKU for the 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.
  • 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).
  • capture_failed_on (Optional) - the time the capture permanently failed. Present only for the rare session whose capture could not be completed; null otherwise.
  • capture_failed_details (Optional) - a generic message indicating the capture could not be completed. Null when capture_failed_on is null.
  • capture_failed_amount_collected (Optional) - funds already collected on a partially-charged split payment before the capture failed; null otherwise.
get/payments/v1/payment_session/{business_id}

Request

  • Base URL: https://dev-api.truemed.com
  • URL: https://dev-api.truemed.com/payments/v1/payment_session/{business_id}
  • Auth: API key in header x-truemed-api-key

Path parameters

business_idstring required

The payment session ID.

Response

Successful response

authorization_expires_atstring date-time nullable

The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.

authorize_amountinteger required

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

capture_amountinteger nullable

The amount of funds actually captured.

capture_failed_amount_collectedinteger nullable

The amount of funds already collected on a capture that permanently failed. Set when part of a split payment succeeded before the capture failed; null otherwise.

capture_failed_detailsstring nullable

A generic message indicating the capture could not be completed. Null when capture_failed_on is null.

capture_failed_onstring date-time nullable

The UTC time at which capturing the authorized funds permanently failed. Null unless the capture will not be retried.

created_atstring date-time required

The date and time when the payment session was created.

customer_business_idstring nullable

The business id of the customer.

emailstring nullable

The email of the user who executed the payment.

is_testingboolean required

Whether the payment was executed in a test environment.

kind'one_time_payment' | 'authorization' required

Enum for the kind of payment

This determines how the payment will be captured

  • OneTimePayment means captured by Truemed automatically
  • Authorization means manually captured by the requesting merchant
metadatastring nullable

Optional field echoed back if present in the call to create_payment_session.

namestring nullable

The name of the user who executed the payment.

payment_session_idstring required

The id of the payment session.

status'pending' | 'canceled' | 'processing' | 'rejected' | 'authorized' | 'authorization_expired' | 'authorization_voided' | 'partially_captured' | 'captured' required
status_summary'Incomplete' | 'Canceled' | 'Rejected' | 'Processing' | 'Authorized' | 'Voided' | 'Expired' | 'Partially Captured' | 'Captured' | 'Partially Refunded' | 'Refunded' | 'PartiallyDisputed' | 'Disputed' required
stripe_payment_idstring nullable

The Stripe payment id.

total_amountinteger required

The total amount captured, in cents.

Changes

No recorded changes to this operation across all 1 revision of this API.