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. Discounts and line items: for a product/price-targeted discount to apply to a one-time line item (in cart or mixed mode), the line item must reference the CHING price/product it represents via its `price` (or `product`) field - ad-hoc line items carry no catalog link and are only eligible for order-level discounts. This matters when you sell CHING-catalog items; it is not needed for a pure e-commerce cart of SKUs that don't exist as CHING products. Embedded checkout: every one-time price and cart session is also embeddable as a button-only widget, so you can keep the customer on your own page instead of redirecting. The create response returns an `embed_url` (https://secured.ching.co.il/checkout/:id/embed) alongside the redirect `url`; render it in an `<iframe>` to show just the "Pay N using…" buttons (credit card and/or digital wallets - Bit, Apple Pay, Google Pay). Use `payment_methods` to choose which buttons appear and `background_color` to match your page (the embed derives readable text colors from it). Set `auto_open_wallets` to open the digital-wallet sheet automatically on load instead of showing the wallet button - the customer can dismiss it to fall back to the buttons; it requires wallets enabled for your account and `wallet` among `payment_methods`. The iframe MUST carry `allow="payment"` and be served over HTTPS, or the browser blocks Apple Pay and Google Pay (the card button still works). On completion the embed posts a `window.postMessage` to the parent: `{ type: "ching-checkout-result", status: "success" | "failed", session_id }`. Treat that message as a UX signal only - rely on the `charge.succeeded` webhook for fulfillment. Embedded checkout is for immediate-charge sessions (one-time price or cart); `payment_methods` and `background_color` are ignored by the hosted redirect checkout, and `payment_methods` is rejected for recurring and mixed sessions.

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?, price?, product? }. 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). IMPORTANT for discounts: a line item is ad-hoc by default (just a name + amount) and carries no link to a CHING product/price, so a discount that targets a specific product or price will NOT apply to it. To let product/price-targeted discounts apply to a line item, set its `price` (or `product`) to the CHING id it represents - see the per-item fields below. This is required for the mixed/cart one-time items you sell from your CHING catalog. It is NOT needed for a pure e-commerce cart whose SKUs aren't CHING products (you aren't charging for CHING-created products there); those items simply won't be eligible for product/price-targeted discounts (order-level discounts still apply).
`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.
`price`	string		Optional. The CHING price id this line item represents. When set, CHING links the line to that price AND its parent product, so discounts targeting that price OR product apply to the line. Use this for one-time items sold from your CHING catalog (e.g. the setup-fee price in a mixed checkout). Leave unset for ad-hoc e-commerce SKUs that aren't CHING products. An unknown id is rejected with 400 line_item_target_not_found.
`product`	string		Optional. The CHING product id this line item represents, when you don't have a specific price to reference. Links the line to the product so product-targeted discounts apply. `price` (which also resolves the product) takes precedence if both are sent.
`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.).
`coupon_codes`	array		Optional array of discount code strings (max 20, each ≤64 chars) to pre-apply to the session, so the hosted page shows them already attached as removable chips - the customer doesn't have to type anything. Every code is validated up front: an unknown code is rejected with 400 discount_code_not_found. Runtime states (expired, exhausted, no matching target) are not errors here - they simply produce no chip. The customer can still add or remove codes on the hosted page.
`payment_methods`	array		Embedded checkout only. Which payment buttons the embed renders: any of "card" and "wallet". Omit or pass an empty array for both (the default). Only valid for one-time price and cart sessions - rejected with 400 payment_methods_not_supported_for_recurring for recurring or mixed checkout. Ignored by the hosted (redirect) checkout.
`background_color`	string		Embedded checkout only. CSS hex color (#rgb, #rrggbb, or #rrggbbaa) for the embed's background; the embed derives readable text colors from it (a dark background gets light text). Defaults to white when omitted. Ignored by the hosted checkout.
`auto_open_wallets`	boolean		Embedded checkout only. When true, the embed opens the digital-wallet sheet (Bit, Apple Pay, Google Pay) automatically on load instead of waiting for the customer to tap the wallet button; while it loads the embed shows a short loader, and if the customer dismisses the sheet it falls back to the normal buttons. Requires wallets (express checkout) enabled for your account and that "wallet" is among payment_methods. Rejected with 400 express_checkout_disabled when wallets are off, auto_open_wallets_requires_wallet when payment_methods excludes wallet, and auto_open_wallets_not_supported_for_recurring for recurring or mixed checkout; also not supported with capture_method=manual. Ignored by the hosted checkout.

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",
  "coupon_codes": [],
  "payment_methods": [],
  "background_color": "example_background_color",
  "auto_open_wallets": true
}'

Response

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

POST/v1/checkout_sessions/:id/discount

Public (no auth - keyed by the session's unguessable id). Apply a coupon code to a pending session. The hosted page calls this when the customer enters a code; you normally don't call it from your server (use `coupon_codes` on create instead). A code may map to several discount rules (one coupon reducing different products/prices); every gate-passing rule that actually reduces a line is linked. Returns the recomputed discount summary.

Errors: invalid_code (404, no rule under the code), session_not_pending (409), expired / exhausted / inactive (every rule under the code was gated out), not_applicable (400, gate-passing rules matched nothing in the cart - currency mismatch or target not present). Idempotent: re-applying a code never double-links it.

Path Parameters

Name	Type		Description
`id`	string	required	The checkout session id.

Body Parameters

Name	Type		Description
`code`	string	required	The coupon code to apply (1-64 chars).

Request

curl -X POST "https://api.ching.co.il/ching/v1/checkout_sessions/:id/discount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example_code"
}'

Response

{
  "success": true,
  "data": {
    "discounts": [
      {
        "id": "disc_8kQ2vN1pLm4z",
        "code": "LAUNCH25",
        "name": "Launch 25%"
      }
    ],
    "discount_lines": [
      {
        "name": "Pro plan",
        "amount_agorot": -1248
      }
    ],
    "total_discount_agorot": -1248,
    "plan_discount_agorot": -1248
  }
}

DELETE/v1/checkout_sessions/:id/discount/:code

Public. Remove a previously-applied code from a pending session (unlinks every rule the code maps to). Returns the recomputed discount summary. Automatic discounts are not removable - they reappear in the summary as long as they match.

Path Parameters

Name	Type		Description
`id`	string	required	The checkout session id.
`code`	string	required	The coupon code to remove.

Request

curl -X DELETE "https://api.ching.co.il/ching/v1/checkout_sessions/:id/discount/:code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "discounts": [],
    "discount_lines": [],
    "total_discount_agorot": 0,
    "plan_discount_agorot": 0
  }
}