Checkout Sessions

Create a hosted checkout session and redirect the customer to it. CHING renders branded checkout, collects the card if needed, runs 3DS, charges, and issues the invoice before returning them to your success_url. Hosted checkout pages live on https://secured.ching.co.il. Three modes are supported. Pass `price` alone to charge a single product or start a subscription against a price already created in CHING. Pass `line_items` alone to charge an ad-hoc cart - useful when you run your own e-commerce site and the SKUs aren't in your CHING products table. Pass `price` (recurring) together with `line_items` for a mixed checkout: a subscription plus one-time items (e.g. a monthly plan plus a setup fee) in a single payment. In mixed mode, if the plan has a trial the customer only pays the one-time items now and the plan starts billing when the trial ends.

Use cases: Outsource the entire payment UI, accept new customers with zero PCI scope, let existing customers upgrade to a higher plan, or collect payment for a cart of arbitrary line items from your own storefront.

POST/v1/checkout_sessions

Create a checkout session - against a price (single one-time or recurring product), a list of ad-hoc line items (cart), or both together (mixed: a recurring plan plus one-time items). Returns the hosted url and the expiry timestamp.

Checkout sessions expire after 30 minutes. A successful automatic-capture checkout fires `charge.succeeded` (one-time price or cart) or `subscription.created` (recurring price). A mixed checkout fires `subscription.created` for the plan plus, when an amount is due now, a single `charge.succeeded` covering the one-time items (and the plan's first period when there's no trial); with a trial only the one-time items are charged now and the plan is billed automatically when the trial ends. A successful manual-capture checkout fires `charge.authorized` instead - the merchant must call `POST /v1/charges/:id/capture` or `POST /v1/charges/:id/cancel` within the 7-day window. For cart and mixed sessions the charge payload carries `checkout_session` and a `line_items` array so you can reconcile against the original cart.

Body Parameters

Name	Type		Description
`customer`	string	required	The customer id completing checkout.
`price`	string		The price id being sold. Can be one_time or recurring. Pass alone for a single-product/subscription checkout, or together with `line_items` for a mixed checkout (in that case the price must be recurring; a one_time price plus line_items is rejected - use `line_items` alone instead).
`line_items`	array		1-50 cart items. Each item is { name, amount_agorot, quantity, description?, image_url? }. The sum of amount_agorot * quantity across all items must be >= 0 (negative line totals are allowed for discounts; the cart total can't go below zero). Pass alone for a cart checkout, or together with a recurring `price` for a mixed checkout (subscription + one-time items).
`name`	string	required	Display name shown on the hosted checkout page (1-255 chars).
`amount_agorot`	integer	required	Per-unit amount in agorot, signed. Negative values render as discount lines. The cart sum must end up non-negative.
`quantity`	integer		Defaults to 1. Range 1-1000.
`description`	string		Optional secondary text under the item name (max 500 chars).
`image_url`	string		Optional thumbnail rendered next to the item. Must be https://. Max 2048 chars.
`success_url`	string	required	URL to redirect to after a successful payment or plan change.
`cancel_url`	string	required	URL to redirect to if the customer cancels.
`create_document`	boolean		Whether CHING should issue a tax invoice receipt when the resulting charge succeeds. Defaults to true. Applies to every confirm-time charge produced by this session: cart total, single one-time price, and the initial charge of a subscription start or upgrade. Subscription renewals (issued later by the cron) are not affected by this flag.
`capture_method`	string		"automatic" (default) charges the card immediately. "manual" authorizes a hold via Grow's J5 flow and waits for an explicit POST /v1/charges/:id/capture (within 7 days). Manual is only valid for one-time prices and carts paid with a new card - the API rejects it for recurring prices and for mixed checkout, and the hosted checkout hides saved-card and express-wallet options when the session is manual. Use this for ecommerce where stock isn't confirmed at checkout time (variable-weight goods, made-to-order, etc.).

Request

curl -X POST "https://api.ching.co.il/ching/v1/checkout_sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "example_customer",
  "price": "example_price",
  "line_items": [],
  "success_url": "example_success_url",
  "cancel_url": "example_cancel_url",
  "create_document": true,
  "capture_method": "example_capture_method"
}'

Response

{
  "success": true,
  "data": {
    "id": "co_rzHlhWSDAHIZ",
    "url": "https://secured.ching.co.il/checkout/co_rzHlhWSDAHIZ",
    "expires_at": "2026-04-19T09:46:40.000Z"
  }
}