> ## 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.

# Cards API

> 카드(Card)는 계정 또는 사용자 잔액에서 결제하는 가상 결제 카드를 나타냅니다.

카드는 카드 소지자에게 할당할 수 있으며, 지출 통제를 위해 지출 한도를 설정할 수 있습니다.

Cards API를 사용하여 카드를 발급하고, 계정 또는 사용자의 카드를 조회하고, 카드 번호와 CVC 같은 활성 카드 세부 정보를 조회하고, 카드로 이루어진 거래를 조회할 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [카드 거래 목록 조회](https://docs.whop.com/ko/api-reference/cards/list-card-transactions.md) | GET `/card_transactions` |
| [카드 거래 조회](https://docs.whop.com/ko/api-reference/cards/retrieve-card-transaction.md) | GET `/card_transactions/{id}` |
| [카드 목록 조회](https://docs.whop.com/ko/api-reference/cards/list-cards.md) | GET `/cards` |
| [카드 조회](https://docs.whop.com/ko/api-reference/cards/retrieve-card.md) | GET `/cards/{id}` |
| [카드 생성](https://docs.whop.com/ko/api-reference/cards/create-card.md) | POST `/cards` |
| [카드 업데이트](https://docs.whop.com/ko/api-reference/cards/update-card.md) | PATCH `/cards/{id}` |

## 속성

**id** `string` *required*

카드 ID이며, 접두사는 `icrd_`입니다.

**billing** `object | null` *required*

청구지 주소입니다.

> [accordion] 속성
>
> **city** `string | null` *required*
>
> 청구지 도시입니다.
>
> **country\_code** `string | null` *required*
>
> 청구지 국가 코드입니다.
>
> **line1** `string | null` *required*
>
> 도로명 주소 1행입니다.
>
> **line2** `string | null` *required*
>
> 도로명 주소 2행입니다.
>
> **postal\_code** `string | null` *required*
>
> 청구지 우편번호입니다.
>
> **region** `string | null` *required*
>
> 청구지 지역 또는 주입니다.

**canceled\_at** `string | null` *required*

카드가 취소된 시점입니다.

**created\_at** `string | null` *required*

카드가 생성된 시점입니다.

**digital\_wallets** `string[] | null` *required*

카드가 추가된 디지털 지갑입니다. List Cards, Update Card 및 웹훅 페이로드는 `null`을 반환하며, 지갑 정보를 가져올 수 없는 경우 Retrieve Card도 마찬가지입니다.

사용 가능한 옵션: `apple_pay`, `google_pay`

**expiration\_month** `string | null` *required*

카드 만료 월입니다.

**expiration\_year** `string | null` *required*

카드 만료 연도입니다.

**issued** `boolean` *required*

발급사가 카드를 발급하면 `true`입니다. 카드 소지자의 온보딩이나 검토를 기다리는 초대 카드 또는 발급사가 거절한 카드는 `false`이며, 발급될 때까지 카드 번호가 없습니다.

**last4** `string | null` *required*

카드 번호의 마지막 네 자리입니다. 대기 중인 초대 카드는 `null`입니다.

**limit** `object | null` *required*

지출 한도 설정입니다.

> [accordion] 속성
>
> **amount** `number` *required*
>
> 한도 금액(달러)입니다.
>
> **frequency** `string` *required*
>
> 한도 금액이 적용되는 기간입니다. `per_transaction`은 개별 승인 건마다 한도를 적용하며, `transaction_limit`으로 설정한 한도가 이 값으로 보고됩니다.
>
> 사용 가능한 옵션: `daily`, `weekly`, `monthly`, `one_time`, `per_transaction`

**name** `string | null` *required*

카드 표시 이름입니다.

**object** `string` *required*

**secrets** `object | null`

민감한 카드 세부 정보입니다. 활성 카드에 대한 `GET /cards/:id`에서만 제공되며, 카드가 비활성 상태이거나 세부 정보를 가져올 수 없는 경우 `null`입니다.

> [accordion] 속성
>
> **card\_number** `string` *required*
>
> 전체 카드 번호입니다.
>
> **cvc** `string` *required*
>
> 카드 보안 코드입니다.
>
> **name\_on\_card** `string | null` *required*
>
> 카드에 인쇄된 카드 소지자 이름입니다.
>
> **pin** `string | null` *required*
>
> 카드 PIN입니다. 카드가 할당된 사용자로 인증된 요청에서만 반환되며, 계정 API 키를 포함한 다른 모든 호출자에게는 `null`입니다.

**spent\_last\_month** `integer | null` *required*

최근 30일간의 총 지출액(센트)입니다.

**status** `string | null` *required*

카드 상태입니다. `denied`는 발급사가 카드 소지자를 거절했다는 의미로, 카드는 발급되지 않습니다.

사용 가능한 옵션: `active`, `frozen`, `canceled`, `invited`, `denied`

**type** `string | null` *required*

카드 유형입니다.

사용 가능한 옵션: `virtual`, `physical`

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

할당된 경우 카드 소지자 사용자 ID이며, 접두사는 `user_`입니다.

```json Card theme={null}
{
	"id": "icrd_xxxxxxxxxxxxx",
	"billing": {
		"city": "New York",
		"country_code": "US",
		"line1": "123 Spring Street",
		"line2": "Suite 4",
		"postal_code": "10012",
		"region": "NY"
	},
	"canceled_at": null,
	"created_at": "2026-06-01T12:00:00Z",
	"digital_wallets": ["apple_pay"],
	"expiration_month": "12",
	"expiration_year": "2029",
	"issued": true,
	"last4": "4242",
	"limit": {
		"amount": 500,
		"frequency": "daily"
	},
	"name": "Operations Card",
	"object": "card",
	"secrets": {
		"card_number": "4242424242424242",
		"cvc": "123",
		"name_on_card": "Pickaxe Operations",
		"pin": "1234"
	},
	"spent_last_month": 12500,
	"status": "active",
	"type": "virtual",
	"user_id": "user_xxxxxxxxxxxxx"
}
```


## Related topics

- [Card canceled](https://docs.whop.com/ko/api-reference/cards/card-canceled.md)
- [Card created](https://docs.whop.com/ko/api-reference/cards/card-created.md)
- [Card frozen](https://docs.whop.com/ko/api-reference/cards/card-frozen.md)
