Skip to navigation
API ReferencePayment Sessions

Get Payment Status

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.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

business_idstringRequired
The payment session ID.

Response

Successful response
authorize_amountinteger

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.

captureslist of objects

The completed captures for this payment session, each addressable by id when issuing a refund (capture_id). Empty until the session has at least one completed capture.

created_atdatetime
The date and time when the payment session was created.
disputeslist of objects
A list of dispute objects that will be empty if the payment has no associated disputes.
is_testingboolean
Whether the payment was executed in a test environment.
kindenum
The type of payment session.
Allowed values:
order_itemslist of objects
A list of order items.
payment_session_idstring
The id of the payment session.
refundslist of objects
A list of refund objects that will be empty if the payment has no associated refunds.
statusenum
The status of the initial payment.
status_summaryenum
A summary of the overall payment session.
total_amountinteger
The total amount captured, in cents.
amount_detailsobject or nullOptional
Detailed breakdown of the payment amount.
authorization_expires_atdatetime or nullOptional

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.

capture_amountinteger or nullOptional
The amount of funds actually captured.
capture_failed_amount_collectedinteger or nullOptional

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 or nullOptional

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

capture_failed_ondatetime or nullOptional
The UTC time at which capturing the authorized funds permanently failed. Null unless the capture will not be retried.
customer_business_idstring or nullOptional
The business id of the customer.
emailstring or nullOptional
The email of the user who executed the payment.
metadatastring or nullOptional

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

namestring or nullOptional
The name of the user who executed the payment.
stripe_payment_idstring or nullOptional
The Stripe payment id.
truemed_feedouble or string or nullOptional
The fee that Truemed received from the payment session. Will return 0 until the session has been captured.

Errors

400
Bad Request Error
404
Not Found Error
405
Method Not Allowed Error
500
Internal Server Error
501
Not Implemented Error