Setup Sessions

A setup session walks a customer through attaching a new card. Create one, redirect the customer to the returned url, and CHING handles the PCI-sensitive card entry before sending them back to your success or cancel URL. Hosted setup pages live on https://secured.ching.co.il. Embedded setup session: the same card-attach flow is also available as a chrome-free widget you can embed on your own page instead of redirecting. The create (and get) response returns an `embed_url` (https://secured.ching.co.il/setup/:id/embed) alongside the redirect `url`; render it in an `<iframe>`. The embedded flow drops all CHING card chrome - no card wrapper, no header, no close button - so it nests cleanly inside your own card without a double-card look: the cardholder-details form is centered, and the secure card-entry step fills the iframe's full width and height, so size your outer iframe to the space you want to give it. Serve the embedding page over HTTPS. On success the embed posts a `window.postMessage` to the parent: `{ type: "ching-setup-result", status: "success", session_id }`. Treat that message as a UX signal only - rely on the `setup_session.completed` webhook to confirm the card was saved.

Use cases: Collect card details without touching them yourself, run 3DS on live mode, or offer a "Save a card for later" flow independent of checkout.

POST/v1/setup_sessions

Create a setup session for a customer. Returns the hosted url to redirect to, plus an embed_url for the chrome-free embeddable variant.

Sessions expire after 24 hours. On live mode the session starts in status requires_action and the url is a Grow-hosted payment page.

Body Parameters

Name	Type		Description
`customer`	string	required	The customer id the card will be attached to.
`success_url`	string	required	URL to send the customer back to on success.
`cancel_url`	string	required	URL to send the customer back to if they cancel.
`metadata`	object		Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/setup_sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "example_customer",
  "success_url": "example_success_url",
  "cancel_url": "example_cancel_url",
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "seti_bQdnU-G6wCOj",
    "object": "setup_session",
    "customer": "cus_V8ltq1pK_MWH",
    "status": "pending",
    "url": "https://secured.ching.co.il/setup/seti_bQdnU-G6wCOj",
    "embed_url": "https://secured.ching.co.il/setup/seti_bQdnU-G6wCOj/embed",
    "success_url": "https://example.com/billing/return",
    "cancel_url": "https://example.com/billing",
    "metadata": {},
    "livemode": false,
    "expires_at": "2026-04-20T09:12:43.000Z",
    "created": "2026-04-19T09:12:43.000Z"
  }
}

GET/v1/setup_sessions/:id

Retrieve a setup session. Poll this endpoint or listen for the setup_session.completed webhook to detect completion.

Path Parameters

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

Request

curl -X GET "https://api.ching.co.il/ching/v1/setup_sessions/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "seti_bQdnU-G6wCOj",
    "object": "setup_session",
    "customer": "cus_V8ltq1pK_MWH",
    "status": "succeeded",
    "url": "https://secured.ching.co.il/setup/seti_bQdnU-G6wCOj",
    "embed_url": "https://secured.ching.co.il/setup/seti_bQdnU-G6wCOj/embed",
    "success_url": "https://example.com/billing/return",
    "cancel_url": "https://example.com/billing",
    "metadata": {},
    "livemode": false,
    "expires_at": "2026-04-20T09:12:43.000Z",
    "created": "2026-04-19T09:12:43.000Z"
  }
}

POST/v1/setup_sessions/:id/cancel

Cancel a pending setup session. The customer will no longer be able to complete it.

Only pending sessions can be canceled.

Path Parameters

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

Request

curl -X POST "https://api.ching.co.il/ching/v1/setup_sessions/:id/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "seti_bQdnU-G6wCOj",
    "status": "canceled"
  }
}