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.

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.

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/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",
    "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.succeeded 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/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",
    "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/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"
  }
}