> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Setup Intents API

> Setup Intent는 지금 금액을 청구하지 않고 나중에 사용할 수 있도록 구매자의 결제 수단을 저장합니다.

결제 요소가 설정 모드에서 수집한 확인 토큰으로 생성하거나, 이미 등록된 결제 수단을 다시 확인하기 위해 해당 결제 수단으로 생성합니다. 결제와 동일한 수집 흐름을 실행하므로 구매자에게 남은 단계가 있을 수 있습니다. 예를 들어 카드의 3D Secure, 호스팅된 등록 절차, 은행 계좌 연결 등이 있습니다.

생성 응답은 생성된 시점의 설정 인텐트이며, 그 결과가 아닙니다. `client_secret`을 요소의 `handleNextAction`에 전달하거나, [상태 조회](https://docs.whop.com/ko/api-reference/setup-intents/retrieve-setup-status.md)를 폴링하여 설정이 얼마나 진행되었는지와 무엇이 남아 있는지 확인하세요. `succeeded`에 도달하면 `payment_method_id`가 저장된 결제 수단을 가리키며, Create Payment로 해당 수단에 청구할 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [설정 인텐트 목록 조회](https://docs.whop.com/ko/api-reference/setup-intents/list-setup-intents.md) | GET `/setup_intents` |
| [설정 인텐트 조회](https://docs.whop.com/ko/api-reference/setup-intents/retrieve-setup-intent.md) | GET `/setup_intents/{id}` |
| [설정 상태 조회](https://docs.whop.com/ko/api-reference/setup-intents/retrieve-setup-status.md) | GET `/setup_intents/{setup_intent_id}/status` |
| [설정 인텐트 생성](https://docs.whop.com/ko/api-reference/setup-intents/create-setup-intent.md) | POST `/setup_intents` |
| [설정 반환 URL 업데이트](https://docs.whop.com/ko/api-reference/setup-intents/update-setup-return-url.md) | PATCH `/setup_intents/{setup_intent_id}/return_url` |

## 속성

**id** `string` *required*

`sint_` 접두사가 붙은 설정 인텐트 ID입니다.

**account\_id** `string | null` *required*

결제 수단이 저장되는 대상 계정으로, `biz_` 접두사가 붙습니다.

**checkout\_configuration\_id** `string | null` *required*

이 설정이 생성된 결제 구성으로, `ch_` 접두사가 붙습니다.
호스팅된 결제가 아닌 이 API를 통해 생성된 설정의 경우 null입니다.

**client\_secret** `string | null` *required*

구매자 측 화면이 이 설정을 폴링하고 반환 URL을 설정할 때 제시하는
자격 증명으로, 요소의 `handleNextAction`에 전달하세요. 이 API를 통해 생성된
설정에만 있으며, 목록 응답에서는 항상 null이므로 이 값을 얻으려면
설정 인텐트를 조회하세요.

**created\_at** `string` *required*

설정 인텐트가 생성된 시각으로, ISO 8601 타임스탬프입니다.

**last\_setup\_error** `object | null` *required*

설정이 해당 상태로 끝난 이유이며, 실패한 것이 없으면 `null`입니다. `canceled`일 때 존재합니다. 구매자가 중단한 경우에는 코드가 없고, 제공업체가 거절한 경우에는 코드가 있습니다. 설정이 성공하면 제거됩니다.

> [accordion] 속성
>
> **code** `string | null` *required*
>
> 기계가 읽을 수 있는 실패 분류로, 예를 들어 `enrollment_declined`입니다.
> 구매자가 단순히 설정을 중단한 경우에는 없습니다.
>
> **message** `string | null` *required*
>
> 사람이 읽을 수 있는 실패 설명입니다.

**member\_id** `string | null` *required*

계정에서 구매자의 회원 레코드로, `mber_` 접두사가 붙습니다. 호출자가 구매자가
아닌 경우 member:basic:read 권한이 없으면 null입니다.

**metadata** `object | null` *required*

설정 인텐트 생성 시 첨부한 사용자 정의 키-값 데이터입니다.

**payment\_instrument** `object | null` *required*

표시용으로 구성된 이 설정의 결제 수단입니다. 구매자용 이름, 표준 아이콘 세트, 그리고 카드인 경우 카드 브랜드, 마지막 네 자리, 발급사 식별 번호, 만료일, 네트워크 트랜잭션 ID를 포함합니다. 결제 수단이 수집되기 전까지는 null입니다.

> [accordion] 속성
>
> **card** `object | null` *required*
>
> 카드, Apple Pay, Google Pay 결제 전용입니다. 카드의 네트워크, 마지막 네 자리, 발급사 식별 번호, 만료일, 네트워크 트랜잭션 ID입니다.
>
> > [accordion] 속성
> >
> > **brand** `string | null` *required*
> >
> > 네트워크 식별자(`visa`, `amex`, …)로, `card.networks` 항목 및 저장된 카드
> > 결제 수단과 일치합니다. 볼트에 네트워크가 기록되지 않은 경우
> > null입니다.
> >
> > **exp\_month** `number | null` *required*
> >
> > 카드의 만료 월로, 1에서 12 사이입니다. 볼트에 기록되지 않은 경우 null입니다.
> >
> > **exp\_year** `number | null` *required*
> >
> > 카드의 네 자리 만료 연도입니다. 볼트에 기록되지 않은 경우 null입니다.
> >
> > **issuer\_identification\_number** `string | null` *required*
> >
> > 발급사 식별 번호로, BIN이라고도 합니다. 발급 은행을 식별하는 카드의 앞 6자리
> > 또는 8자리입니다. 결제 처리업체가 보고하지 않은 경우
> > null입니다.
> >
> > **last4** `string | null` *required*
> >
> > 수집된 경우 카드의 마지막 네 자리입니다.
> >
> > **network\_transaction\_id** `string | null` *required*
> >
> > 이 계정이 해당 카드에 사용하는 네트워크 트랜잭션 ID입니다. Whop이 보유한 경우, 이 카드에 대한 이 계정의 첫 고객 참여 청구 또는 확인에서 나온 이 계정 자체의 ID입니다. 그렇지 않으면 이 카드의 이전 네트워크 트랜잭션 ID로, 다른 계정의 트랜잭션에서 나왔거나 카드와 함께 가져온 것일 수 있습니다. 이 계정에서 이후 이 카드에 판매자 주도 청구를 할 때 이전 트랜잭션으로 참조하세요. 값이 생기기 전까지는 null입니다. 결제가 처음 기록될 때 전송되는 웹훅에는 `null`이 포함될 수 있으므로, 이 값을 읽으려면 결제를 조회하세요.
>
> **display\_name** `string` *required*
>
> 구매자용 결제 수단 이름입니다. 카드가 확인된 경우 "Visa •••• 4242"이며, 그렇지 않으면
> 결제 수단 자체의 이름("Klarna")입니다.
>
> **icons** `object` *required*
>
> 표준 아이콘 세트입니다. 정사각형과 카드 모양이 있으며, 각각 라이트 및 다크 색상 구성으로 제공됩니다.
>
> > [accordion] 속성
> >
> > **card** `object` *required*
> >
> > 신용카드 비율의 타일입니다(48x30).
> >
> > > [accordion] 속성
> > >
> > > **dark** `object` *required*
> > >
> > > 어두운 배경용 색상 구성입니다.
> > >
> > > > [accordion] 속성
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > 도형의 기본 크기로 제공되는 래스터 대체 이미지입니다.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > 2배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > 4배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > 벡터 파일입니다. SVG가 렌더링되는 모든 곳에서 이 파일을 우선 사용하세요.
> > >
> > > **light** `object` *required*
> > >
> > > 밝은 배경용 색상 구성입니다.
> > >
> > > > [accordion] 속성
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > 도형의 기본 크기로 제공되는 래스터 대체 이미지입니다.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > 2배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > 4배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > 벡터 파일입니다. SVG가 렌더링되는 모든 곳에서 이 파일을 우선 사용하세요.
> >
> > **square** `object` *required*
> >
> > 정사각형 타일입니다(32x32).
> >
> > > [accordion] 속성
> > >
> > > **dark** `object` *required*
> > >
> > > 어두운 배경용 색상 구성입니다.
> > >
> > > > [accordion] 속성
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > 도형의 기본 크기로 제공되는 래스터 대체 이미지입니다.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > 2배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > 4배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > 벡터 파일입니다. SVG가 렌더링되는 모든 곳에서 이 파일을 우선 사용하세요.
> > >
> > > **light** `object` *required*
> > >
> > > 밝은 배경용 색상 구성입니다.
> > >
> > > > [accordion] 속성
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > 도형의 기본 크기로 제공되는 래스터 대체 이미지입니다.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > 2배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > 4배 밀도의 래스터 대체 이미지입니다.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > 벡터 파일입니다. SVG가 렌더링되는 모든 곳에서 이 파일을 우선 사용하세요.
>
> **installment\_count** `number | null` *required*
>
> 할부 결제 수단 전용입니다. 청구가 나뉘는 결제 횟수입니다. 표시 문구가 아닌
> 데이터이므로, 레이블은 클라이언트 측에서 구성하고 번역하세요.
>
> **payment\_method\_type** `string` *required*
>
> 결제 수단 유형 식별자로, 예를 들어 `card`, `klarna`, `apple_pay`입니다.

**payment\_method\_id** `string | null` *required*

`payt_` 접두사가 붙은 저장된 결제 수단으로, Create Payment로 바로 청구할 수
있습니다. 설정이 `succeeded`가 되기 전까지는 null입니다.

**payment\_method\_type** `string | null` *required*

저장 중인 결제 수단의 종류로, 예를 들어 `card` 또는 `us_bank_account`입니다.

**return\_url** `string | null` *required*

구매자가 외부 단계를 완료한 후 이동하는 위치이며, 현재 위치에 그대로 두려면
`null`입니다.

**status** `string` *required*

설정의 진행 정도입니다. **201 또는 200은 응답했다는 의미일 뿐 결제 수단이 저장되었다는 의미가 아니므로, 항상 이 값으로 분기하세요.** `requires_action`: 구매자에게 남은 단계가 있습니다. `client_secret`을 요소에 전달하거나 Retrieve setup status를 폴링하세요. `processing`: 결제 처리업체가 결정 중입니다. `succeeded`: 결제 수단이 저장되었으며, 이 값만이 저장되었음을 의미합니다. `canceled`: 중단되었거나 거절되었습니다. `last_setup_error`를 참조하세요.

사용 가능한 옵션: `processing`, `succeeded`, `canceled`, `requires_action`

**three\_ds\_level** `string | null` *required*

지원되는 온세션 카드 결제에 대한 3D Secure 동작입니다. `mandate_challenge`는 결제 처리 전에 3DS 챌린지를 요구하고, `mandate_if_required`는 결제 처리업체가 요구하는 경우에만 챌린지를 의무화하며, `frictionless_if_required`는 일반적인 마찰 없는 3DS 흐름을 사용합니다. \$1,000 이상의 결제는 `mandate_challenge`를 선택하지 않는 한 `mandate_if_required`를 사용합니다. 위험 및 인증 복구 요구 사항이 이 설정보다 우선할 수 있습니다. 이 설정에 대해 요청된 값이며, 설정되지 않은 경우 `null`입니다.

사용 가능한 옵션: `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

**three\_ds\_verified** `boolean` *required*

구매자가 이 결제 수단을 저장하면서 3D Secure를 완료한 경우 true입니다.

**updated\_at** `string` *required*

설정 인텐트가 마지막으로 업데이트된 시각으로, ISO 8601 타임스탬프입니다.

**user** `object | null` *required*

결제 수단을 저장하는 사용자입니다. 구매자가 사용자가 아닌 계정인 경우 null입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> `user_` 접두사가 붙은 사용자 ID입니다.
>
> **name** `string | null` *required*
>
> 표시 이름입니다.
>
> **profile\_picture** `object` *required*
>
> 아바타 래퍼입니다. `url`은 항상 존재하며, 사용자가 사진을 설정하지 않은 경우 생성된 플레이스홀더입니다.
>
> > [accordion] 속성
> >
> > **url** `string` *required*
> >
> > 아바타 이미지 URL입니다. 항상 존재합니다. 사용자가 사진을 설정하지 않은 경우 생성된 플레이스홀더입니다.
>
> **username** `string` *required*
>
> 공개 사용자 이름입니다.

```json SetupIntent theme={null}
{
	"id": "sint_xxxxxxxxxxxxxx",
	"account_id": "biz_xxxxxxxxxxxxxx",
	"checkout_configuration_id": null,
	"client_secret": null,
	"created_at": "2026-09-22T12:00:00.000Z",
	"last_setup_error": null,
	"member_id": "mber_xxxxxxxxxxxxxx",
	"metadata": {
		"customer_id": "cus_4417"
	},
	"payment_method_id": "payt_xxxxxxxxxxxxxx",
	"payment_method_type": "card",
	"return_url": "https://shinetime.example/billing/saved",
	"status": "succeeded",
	"three_ds_verified": false,
	"three_ds_level": "mandate_challenge",
	"updated_at": "2026-09-22T12:00:00.000Z",
	"user": {
		"id": "user_xxxxxxxxxxxxxx",
		"name": "Dana Whitfield",
		"profile_picture": {
			"url": "https://ui-avatars.com/api/"
		},
		"username": "danawhitfield"
	},
	"payment_instrument": {
		"card": {
			"brand": "visa",
			"issuer_identification_number": "41111111",
			"last4": "4242",
			"exp_month": 11,
			"exp_year": 2030,
			"network_transaction_id": "016153570198200"
		},
		"display_name": "Visa •••• 4242",
		"icons": {
			"card": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			},
			"square": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			}
		},
		"installment_count": null,
		"payment_method_type": "card"
	}
}
```
