Get Checkout Session Details

Quick Reference

• API Endpoint: GET v1/checkout-sessions/{checkoutSessionId}
• API Scope: user
• Purpose: Retrieve detailed information about a checkout session, including status, payment method, child session, and appearance configuration.
• Key Fields: checkoutSessionId, checkoutSessionStatus, paymentMethod, childSession, appearance, hcpToken
• Usage: Use this endpoint to poll for session status and details. Supports appearance config with init=true.
• See Also: Poll Get Sessions
• Error Codes: Session Error Codes

Handling Get Checkout Session Details

• Use this API to retrieve the status and details of a checkout session.
• Optional Parameters: Add init=true to include appearance and cardCategories in the response. These fields are omitted by default to reduce response size.
• hcpToken is used to initiate the all nginix calls

Sample Request

Sample Request

GET v1/checkout-sessions/{checkoutSessionId}
X-Merchant-Id: {merchantId}

Sample Response

Sample Success Response (HTTP 200 OK)

{
  "data": {
    "checkoutSession": {
      "id": "checkout-session-uuid",
      "checkoutSessionStatus": "INITIATED|COMPLETED|FAILED|CANCELED",
      "createdAt": "2023-01-01T12:00:00Z",
      "expiresAt": "2023-01-01T13:00:00Z",
      "paymentMethod": {
        // Payment method details if available
      },
      "childSession": {
        // Child session information if available
      },
      "appearance": {
        // Only included if init=true
      }
    },
    "hcpToken": "token-value"
  }
}

Error Handling

Both endpoints use a consistent error handling approach:

1. Session Not Found - Returns 404 with clear error details
2. Session Expiration - Returns 401 if the session has expired
3. Access Control - Returns 403 if the merchant is not authorized
4. Session Cancellation - Returns 410 if the session has been canceled
5. Validation Errors - Returns 400 with specific error information for business rule violations

Session States

State	Description
INITIATED	Session has been created but not yet completed
COMPLETED	Session has been successfully completed
FAILED	Session processing has failed
CANCELED	Session has been canceled
EXPIRED	Session has exceeded its time limit (represented as INITIATED with isExpired() = true)

Child Sessions

When a parent session has a child session:

1. The parent session contains the child session ID and child session details
2. Child session expiration is managed in conjunction with the parent
3. Status changes in the child can affect the parent session

Refer Child Session Documentation for more details