PaperTiger.Resources.CheckoutSession (PaperTiger v0.9.21)

View Source

Handles Checkout Session resource endpoints.

Endpoints

  • POST /v1/checkout/sessions - Create checkout session
  • GET /v1/checkout/sessions/:id - Retrieve checkout session
  • GET /v1/checkout/sessions - List checkout sessions
  • POST /v1/checkout/sessions/:id/expire - Expire checkout session (Stripe API)

Test Endpoints

  • POST /_test/checkout/sessions/:id/complete - Complete checkout session (test helper)

Note: Checkout sessions are immutable after creation (no update or delete). The complete endpoint is a PaperTiger test helper - real Stripe completes sessions automatically when payment succeeds.

Checkout Session Object

%{
  id: "cs_...",
  object: "checkout.session",
  created: 1234567890,
  customer: "cus_...",
  mode: "payment",
  payment_status: "unpaid",
  status: "open",
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  line_items: [],
  metadata: %{},
  # ... other fields
}

Summary

Functions

browser_complete(conn, id)

Browser-accessible checkout completion endpoint.

complete(conn, id)

Completes a checkout session (test helper).

create(conn)

Creates a new checkout session.

expire(conn, id)

Expires an open checkout session.

list(conn)

Lists all checkout sessions with pagination.

retrieve(conn, id)

Retrieves a checkout session by ID.

Functions

browser_complete(conn, id)

@spec browser_complete(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Browser-accessible checkout completion endpoint.

GET /checkout/:id/complete

This is called when a user is redirected to the checkout URL. Unlike the /_test/checkout/sessions/:id/complete POST endpoint (for programmatic use), this handles the browser redirect flow:

  1. Completes the checkout session (creates subscription/payment/setup intent)
  2. Redirects the browser to the session's success_url

This makes checkout flows work transparently in tests - the application just redirects to the checkout URL and the user ends up at success_url with the session completed.

complete(conn, id)

@spec complete(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Completes a checkout session (test helper).

POST /_test/checkout/sessions/:id/complete

This is a PaperTiger test helper endpoint - real Stripe completes sessions automatically when payment succeeds. Use this to simulate successful checkout completion in tests.

Based on the session mode, this will:

  • payment: Creates a succeeded PaymentIntent
  • subscription: Creates an active Subscription with items
  • setup: Creates a succeeded SetupIntent

Fires the checkout.session.completed webhook event.

create(conn)

@spec create(Plug.Conn.t()) :: Plug.Conn.t()

Creates a new checkout session.

Required Parameters

  • success_url - URL to redirect to after successful payment
  • cancel_url - URL to redirect to if customer cancels payment
  • mode - One of "payment", "setup", or "subscription"

Optional Parameters

  • customer - Customer ID
  • line_items - Array of line items
  • metadata - Key-value metadata
  • payment_status - One of "paid", "unpaid", "no_payment_required"
  • status - One of "open", "complete", "expired"

expire(conn, id)

@spec expire(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Expires an open checkout session.

POST /v1/checkout/sessions/:id/expire

A Checkout Session can only be expired when its status is "open". After expiration, customers cannot complete the session.

list(conn)

@spec list(Plug.Conn.t()) :: Plug.Conn.t()

Lists all checkout sessions with pagination.

Parameters

  • limit - Number of items (default: 10, max: 100)
  • starting_after - Cursor for pagination
  • ending_before - Reverse cursor
  • customer - Filter by customer ID

retrieve(conn, id)

@spec retrieve(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Retrieves a checkout session by ID.