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).

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).

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.

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 null

Detailed breakdown of the payment amount.

capture_amountinteger or null

The amount of funds actually captured.

customer_business_idstring or null

The business id of the customer.

emailstring or null

The email of the user who executed the payment.

metadatastring or null

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

namestring or null

The name of the user who executed the payment.

stripe_payment_idstring or null

The Stripe payment id.

truemed_feedouble or string or null

The fee that Truemed received from the payment session. Will return 0 until the session has been captured.

Errors

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).

1	import requests
2
3	url = "https://dev-api.truemed.com/payments/v1/payment_session/business_id"
4
5	headers = {"x-truemed-api-key": "<apiKey>"}
6
7	response = requests.get(url, headers=headers)
8
9	print(response.json())

1	{
2	"authorize_amount": 25000,
3	"created_at": "2024-01-15T09:30:00Z",
4	"disputes": [
5	{
6	"description": "Customer claimed product was not received",
7	"dispute_id": "dp_01F8XYZ1234567890",
8	"disputed_on": "2024-01-20T14:45:00Z",
9	"reason": "product_not_received",
10	"status": "Lost",
11	"resolved_on": "2024-02-05T10:00:00Z",
12	"withdrawn_amount": 25000
13	}
14	],
15	"is_testing": false,
16	"kind": "one_time_payment",
17	"order_items": [
18	{
19	"amount": 25000,
20	"amount_details": {
21	"additional_charges_details": [
22	{
23	"amount": 500,
24	"name": "Shipping Fee"
25	}
26	],
27	"discounts_details": [
28	{
29	"amount": 1000,
30	"name": "Spring Sale Discount"
31	}
32	],
33	"total_additional_charges": 500,
34	"total_discounts": 1000
35	},
36	"item_id": "item-001",
37	"name": "Wireless Headphones",
38	"price": 25000,
39	"quantity": 1,
40	"quantity_capturable": 0,
41	"quantity_refundable": 1,
42	"sku": "WH-1234",
43	"total_capturable": 0,
44	"total_refundable": 25000
45	}
46	],
47	"payment_session_id": "psess_1234567890abcdef",
48	"refunds": [
49	{
50	"amount": 25000,
51	"id": "refund_9876543210abcdef",
52	"refunded_on": "2024-02-10T11:30:00Z",
53	"truemed_fee_returned": 300
54	}
55	],
56	"status": "captured",
57	"status_summary": "Refunded",
58	"total_amount": 25000,
59	"amount_details": {
60	"additional_charges_details": [
61	{
62	"amount": 500,
63	"name": "Shipping Fee"
64	}
65	],
66	"discounts_details": [
67	{
68	"amount": 1000,
69	"name": "Spring Sale Discount"
70	}
71	],
72	"total_additional_charges": 500,
73	"total_discounts": 1000
74	},
75	"capture_amount": 25000,
76	"customer_business_id": "cust-987654321",
77	"email": "jane.doe@example.com",
78	"metadata": "order_12345",
79	"name": "Jane Doe",
80	"stripe_payment_id": "pi_1F8XYZ1234567890abcdef",
81	"truemed_fee": 350.75
82	}