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

# PaymentRequest

> 커스텀 버튼, 익스프레스 체크아웃, 배송 콜백을 위한 저수준 Apple Pay, Google Pay 또는 PayPal 시트입니다. 지갑 타일은 `payments.createConfirmationToken`을 통해 이 흐름을 자동화합니다. `canMakePayment()`를 await하여 사용 가능 여부를 확인하고 지갑을 준비한 다음, 사용자 상호작용 핸들러에서 `show(type)`를 동기적으로 호출하세요. 반환되는 `ctok`는 `ctok_` 접두사가 붙은 확인 토큰입니다. 엘리먼트가 생성한 토큰과 마찬가지로 서버 측에서 확인하세요. PayPal 토큰은 PayPal이 구매자에게 표시한 합계를 초과하여 청구하지 않습니다.

> [!NOTE]
>
> 이 페이지는 `@whop/elements@1.10.0` 및 `@whop/elements-react@1.10.0`을 다룹니다.

*`v1.0.0`부터 지원.*

엘리먼트를 마운트하지 않고 이 [`Payments`](https://docs.whop.com/ko/elements/latest/payments/overview) 리소스를 생성합니다. 바닐라에서는 `whop.payments.paymentRequest.create({ … })`, React에서는 `useWhop().payments.paymentRequest.create({ … })`를 사용합니다.

## 옵션

이 값들을 `whop.payments.paymentRequest.create({ … })`에 전달하세요.

**accountId** `string` *required*

모든 클라이언트 측 호출의 범위를 지정하는 `biz_` 접두사가 붙은 계정 ID입니다.

**currency** `string` *required*

세 글자 ISO 4217 결제 통화 코드입니다.

**amount** `number` *required*

최소 화폐 단위의 결제 금액입니다. 나중에 `update()`로 변경할 수 있습니다.

**setupFutureUsage** `"off_session" | "on_session"`

저장 동의를 표시한 후에만 설정하세요. 토큰을 `off_session` 또는 `on_session` 용도로 표시합니다.

**paymentMethodConfiguration** `PaymentMethodConfigurationShape`

API의 `enabled`, `disabled`, `include_platform_defaults` 형식으로 된 결제 수단 필터입니다. `canMakePayment()`가 보고하는 지갑을 좁힙니다. `disabled`는 유형을 제거하고, `enabled`는 제공되는 유형을 복원하며, `include_platform_defaults: false`는 활성화된 유형만 남깁니다. 계정이 제공하지 않는 결제 수단을 추가하지는 않습니다. PayPal은 `paypal` 유형을 따릅니다. `v1.9.0`부터 지원.

**속성**

**enabled** `string[]`

**disabled** `string[]`

**include\_platform\_defaults** `boolean`

**requestPayerEmail** `boolean`

시트에 결제자의 이메일을 요청합니다. 확인 토큰에는 이메일이 필요합니다. 기본값은 `true`입니다.

**requestPayerPhone** `boolean`

시트에 결제자의 전화번호를 요청하며, 결과의 `payer.phone`으로 전달됩니다. 이 번호를 제공한 연락처의 국가 기준으로 파싱되면 E.164 형식이고, 그렇지 않으면 지갑이 제공한 그대로입니다. `payer.country`는 청구지 국가입니다. Google Pay는 시트가 이미 요청하는 청구지 주소를 통해 이를 수집합니다. PayPal은 연락처 섹션을 통해 수집하며 전화번호가 없는 계정은 거부합니다. 기본값은 `false`입니다.

**requestShipping** `boolean`

시트에 배송 주소를 요청합니다(제공된 경우 `shippingOptions`도 표시). PayPal은 세금이 계산되는 기준 주소이므로 항상 주소를 요청하며, 이 옵션이 설정된 경우에만 이를 `shipping`으로 반환합니다. 기본값은 `false`입니다.

**requestPromoCode** `boolean`

시트 자체의 프로모션 코드 필드를 제공하고 `onPromoCodeChange`에 응답합니다. Apple Pay는 Apple Pay 버전 12를 지원하는 기기(iOS 15 및 macOS 12)에서 필드를 표시하고, Google Pay는 계정의 Google Pay 설정이 오퍼를 허용하는 곳에서 표시합니다. 다른 기기에서는 필드 없이 시트가 열립니다. 기본값은 `false`입니다. `v1.5.0`부터 지원.

**appliedPromoCode** `string`

청구에 이미 적용된 프로모션 코드로, 구매자가 확인하거나 교체하거나 제거할 수 있도록 시트에 미리 채워집니다. `v1.5.0`부터 지원.

**appliedPromoDescription** `string`

`appliedPromoCode`의 효과를 설명하는 문구로, Google Pay에서 코드 옆에 표시됩니다. Apple Pay의 쿠폰 필드에는 설명 문구가 없습니다. `v1.5.0`부터 지원.

**countryCode** `string`

Apple Pay 시트에 사용할 계정의 ISO 3166-1 alpha-2 국가 코드입니다. 생략하면 계정에 게시된 등록 국가를 사용합니다. 둘 다 없으면 시트는 기본적으로 `US`를 사용합니다.

**lineItems** `PaymentRequestLineItem[]`

시트가 합계 아래에 나열하는 항목입니다. 나중에 `update()`로 변경할 수 있습니다.

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

`requestShipping`이 설정된 경우 시트가 제공하는 배송 옵션입니다. 표시 전용이므로 변경 핸들러에서 `amount`를 업데이트하세요. 시트는 첫 번째 옵션이 선택된 상태로 열리며 이에 대해 `onShippingOptionChange`를 실행하지 않으므로, `amount`에 이미 해당 가격이 포함되어 있어야 합니다. 나중에 `update()`로 변경할 수 있습니다.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

## 메서드

리소스에서 호출합니다.

> [!WARNING]
>
> `show`는 사용자 활성화 중에 동기적으로 호출하세요. 선행 작업은 먼저 await하세요.

### `canMakePayment`

계정이 지갑을 제공하고, 기기가 지원하며, 이 페이지의 오리진이 계정에 대해 승인된 경우 각 지갑의 사용 가능 여부를 반환합니다(자사 whop.com 페이지는 사전 승인되어 있습니다. 판매자 페이지는 [Domains API](https://docs.whop.com/ko/api-reference/beta/domains/domain)를 통해 해당 도메인에 Apple Pay가 준비되어 있어야 하며, 그곳에서 Google Pay를 제공하는 것은 [Google Pay API 서비스 약관](https://payments.developers.google.com/terms/sellertos)의 적용을 받습니다). 페이지 자체가 iframe 안에 있는 경우, 브라우저가 노출하면 Apple Pay는 대신 최상위 페이지의 도메인을 확인합니다. WebKit이 아닌 브라우저의 Apple Pay는 데스크톱 iPhone 핸드오프 흐름이므로 해당 브라우저의 모바일 기기에서는 사용할 수 없다고 보고됩니다. iOS 브라우저의 네이티브 Apple Pay는 영향을 받지 않습니다. `order`는 브라우저에서 어떤 시트가 네이티브인지에 따라 지갑의 순위를 매기므로(Safari에서는 Apple Pay가 먼저, 그 외에는 Google Pay가 먼저, PayPal은 마지막) 익스프레스 버튼을 가장 적합한 순서로 쌓을 수 있습니다. `payPal`은 계정이 이 통화로 PayPal을 제공하고, 금액이 PayPal 한도 내이며, 요청이 결제자의 전화번호를 요구하지 않고(`off_session` 요청은 \$0일 수 있으며, 이 경우 청구 없이 PayPal을 저장합니다), PayPal의 스크립트가 이 페이지에서 로드되며, 이 페이지의 오리진이 다른 지갑과 마찬가지로 계정에 대해 승인된 경우 PayPal을 보고합니다. Content Security Policy가 있는 페이지는 PayPal의 호스트를 허용해야 하며, `contentSecurityPolicy()`에 포함되어 있습니다. 이미 PayPal 자체의 v5 JavaScript SDK를 로드하는 페이지는 `payPal: false`를 보고합니다. 나열한 지갑만 확인하려면 `types`를 전달하세요. `show(type)`에는 해당 지갑이 확인되어 있어야 합니다. `wallets`는 사용 가능한 각 지갑의 공식 버튼 이미지(`light` 및 `dark` 색상과 이미지)를 담고 있습니다. 이 메서드는 `show()`를 준비합니다. 항상 먼저 await하세요.

**매개변수**

**filter** `object`

**속성**

**types** `("apple_pay" | "google_pay" | "paypal_express")[]`

**반환값** `Promise<WalletAvailability>`

**applePay** `boolean` *required*

**googlePay** `boolean` *required*

**payPal** `boolean`

**order** `("apple_pay" | "google_pay" | "paypal_express")[]`

이 브라우저에서 어떤 시트가 네이티브인지에 따라 순위가 매겨진 지갑 목록입니다. WebKit에서는 Apple Pay가 먼저, 그 외에는 Google Pay가 먼저, PayPal은 마지막이므로 익스프레스 버튼을 가장 적합한 순서로 쌓을 수 있습니다. 사용자가 지정한 사용 가능 여부(미리보기)와 이 기능 이전의 통신에서는 없습니다. payment-request의 WalletSheetType이 아닌 인라인 유니온입니다. 해당 모듈이 이미 이 모듈을 가져오기 때문입니다.

**wallets** `object`

사용 가능한 각 지갑의 세부 정보이며, 지갑 유형을 키로 합니다. 사용자가 지정한 사용 가능 여부(미리보기)에서는 없습니다.

**속성**

**apple\_pay** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 이미지입니다. 게시된 이미지가 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

**google\_pay** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 이미지입니다. 게시된 이미지가 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

**paypal\_express** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 이미지입니다. 게시된 이미지가 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용.

**속성**

**color** `string` *required*

**image** `string` *required*

### `show`

`canMakePayment()`를 await한 후, 누르는 동작 안에서 동기적으로 선택한 지갑을 엽니다. Apple은 제스처 스택 안에서 세션을 생성하도록 요구하며, PayPal은 그곳에서 창을 엽니다. 데스크톱에서는 팝업이며, 팝업이 차단되거나 모바일인 경우 PayPal의 페이지 내 창입니다. 페이지에서 이미 이메일을 수집했다면 `email`을 전달하세요. 지갑은 이를 사용하고 다시 묻지 않습니다. `requestPayerEmail: false`인 경우 이메일 전달이 필수이며, 확인 토큰에는 이메일이 필요하므로 이메일이 없으면 지갑이 열리지 않습니다. 시트가 열려 있는 동안 `update()`는 예외를 발생시키므로, 변경하려면 변경 이벤트에 응답하세요. 사용자 활성화 중에 동기적으로 호출하세요. 브라우저는 비동기 단계를 거치면 활성화를 취소하므로 선행 작업은 먼저 await하세요.

**매개변수**

**type** `"apple_pay" | "google_pay" | "paypal_express"` *required*

**provided** `object`

**속성**

**email** `string`

**반환값** `Promise<PaymentRequestResult>`

**ctok** `string` *required*

`ctok_` 접두사가 붙은 확인 토큰 ID입니다. 시크릿 키를 사용해 서버 측에서 확인하세요.

**type** `"apple_pay" | "google_pay" | "paypal_express"` *required*

**payer** `object` *required*

`phone`은 연락처의 국가 기준으로 파싱되면 E.164 형식이고, 그렇지 않으면 제공된 그대로입니다. PayPal은 `requestPayerPhone`인 경우에만 전화번호를 제공하며, 전화번호가 없는 계정은 거부합니다. `country`는 모든 시트가 수집하는 청구지 국가입니다.

**속성**

**email** `string`

**name** `string`

**phone** `string`

**country** `string`

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

변경 이벤트가 전달하는 일부 가려진 주소와 달리 확인 토큰이 담는 전체 청구지 주소이며, 지갑이 제공하지 않은 경우 `null`입니다. Apple Pay와 Google Pay는 카드의 청구지 주소를 제공합니다. PayPal에서는 구매자가 PayPal에서 선택한 주소, 즉 합계에 세금이 부과된 주소입니다.

**속성**

**address** `PaymentRequestAddress` *required*

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**shipping** `object | null` *required*

`requestShipping`이 설정되지 않은 경우 `null`입니다. `option`은 선택된 배송 옵션입니다. 구매자가 다른 옵션을 선택하기 전까지는 첫 번째 옵션이며, 응답이 선택된 `id` 없이 옵션을 교체하면 다시 첫 번째 옵션이 됩니다. Apple Pay와 Google Pay는 옵션이 제공될 때마다 이를 설정하며, PayPal은 설정하지 않습니다.

**속성**

**address** `PaymentRequestAddress`

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**option** `PaymentRequestShippingOption`

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

### `update`

이 인스턴스의 `amount`, `lineItems`, `shippingOptions`를 변경합니다. 다른 모든 옵션은 `create()` 시점에 고정되므로, 변경하려면 새 인스턴스를 생성하세요.

**매개변수**

**patch** `object` *required*

**속성**

**amount** `number`

**lineItems** `PaymentRequestLineItem[]`

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

## 이벤트

아래 이벤트를 구독합니다. 각 메서드는 구독 해제 함수를 반환합니다.

> [!WARNING]
>
> 각 이벤트 핸들러는 문서화된 응답 메서드를 정확히 한 번 호출해야 합니다. 응답하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다.

### `onShippingAddressChange`

구매자가 배송 주소를 선택했습니다(승인 전에는 일부가 가려져 도시, 주, 우편번호, 국가만 포함됩니다. Apple Pay는 미국 ZIP 코드를 다섯 자리로 줄이고 캐나다 또는 영국 우편번호의 마지막 세 글자를 제거합니다). 해당 주소와 선택된 배송 옵션(구매자가 다른 옵션을 선택하기 전까지는 첫 번째 옵션)에 대한 합계로 응답하세요. `shippingOptions`는 옵션을 교체합니다(빈 목록은 아무것도 변경하지 않습니다). 선택된 옵션은 응답이 그 `id`를 유지하는 동안 선택된 상태로 남습니다. 응답이 이를 제외하면 `onShippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 그 옵션의 가격을 책정하세요. 응답의 모든 오류는 이후 해당 주소에 대한 응답이 이를 해제할 때까지 주소에 남습니다. `field`(`city`, `state`, `postal_code`, `country`)를 지정한 오류는 Apple Pay에서 해당 필드를 표시하며, Google Pay는 메시지만 표시합니다. 주소에 오류가 남아 있는 동안에는 결제가 거부됩니다. 배송할 수 없는 주소는 `field` 없이 `shipping_address_unserviceable` 오류로 거부하세요. Apple Pay, Google Pay, PayPal에서 25초 이내에 응답하지 않은 핸들러는 예외를 발생시킨 핸들러와 마찬가지로 주소를 실패시키며, 이후의 응답은 무시됩니다. PayPal은 구매자가 선택한 주소로 이를 실행하며, `field`를 지정한 오류는 PayPal 내에서 주소의 해당 부분을 거부합니다. 이벤트마다 `updateWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `ShippingAddressChangeEvent`

**속성**

**address** `PaymentRequestAddress` *required*

공급업체별로 정규화된 승인 전 주소입니다. 도시, 주, 우편번호, 국가만 포함합니다. Apple Pay는 우편번호를 줄입니다. 미국 ZIP 코드는 처음 다섯 자리로, 캐나다 또는 영국 우편번호는 마지막 세 글자를 제외합니다.

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**updateWith** `(update: PaymentRequestUpdate) =\> void` *required*

25초 이내에 정확히 한 번 호출하세요. Apple Pay, Google Pay, PayPal에서 그때까지 응답하지 않은 핸들러는 예외를 발생시킨 핸들러와 마찬가지로 주소를 실패시키며, 이후의 응답은 무시됩니다.

**매개변수**

**update** `PaymentRequestUpdate` *required*

**속성**

**amount** `number`

**lineItems** `PaymentRequestLineItem[]`

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

시트의 배송 옵션을 교체합니다. 선택된 옵션은 그 `id`가 목록에 남아 있는 동안 선택된 상태로 유지됩니다. 그렇지 않으면 `shippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 같은 응답에서 그 가격을 책정하세요. 빈 목록은 아무것도 변경하지 않습니다. 배송할 수 없는 주소는 대신 `shipping_address_unserviceable` 오류로 거부하세요.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**errors** `PaymentRequestError[]`

**속성**

**code** `string`

배송 응답이 거부하는 대상입니다. `billingAddressChange` 또는 `paymentMethodChange` 응답의 오류는 코드와 관계없이 해당 이벤트가 묻는 카드나 결제 수단을 거부합니다.

`"other"`, `"shipping_address_invalid"`, `"shipping_address_unserviceable"`, `"shipping_option_invalid"` 중 하나입니다.

**message** `string` *required*

**field** `"state" | "country" | "city" | "postal_code"`

오류와 관련된 주소 필드로, 일부 가려진 주소에 포함된 필드 중 하나입니다. Apple Pay는 `code`와 관계없이 해당 필드에 메시지를 표시하고, Google Pay는 메시지만 표시합니다. 주소 전체에 대한 오류라면 생략하세요.

### `onShippingOptionChange`

구매자가 배송 옵션을 선택했거나 Apple Pay가 선택된 옵션을 다시 알렸습니다. 주소 변경에 모두 응답하고 대기 중인 것이 없으면 Apple Pay는 여전히 선택된 옵션에 대해 이를 실행합니다. 선택된 옵션을 제외한 응답 후에는 실행되지 않으며, 이 경우 이벤트 없이 첫 번째 옵션이 선택되므로, 응답하는 모든 합계는 선택된 옵션의 가격을 반영해야 합니다. 즉 구매자가 다른 옵션을 선택하기 전까지는 첫 번째 옵션, 응답이 그 `id`를 유지하는 동안은 선택한 옵션, 응답이 이를 제외하면 다시 첫 번째 옵션입니다. 금액 전용 계약입니다. `updateWith`는 amount/lineItems/shippingOptions/errors를 전달합니다. `errors`가 포함된 응답은 구매자가 핸들러가 허용하는 옵션을 선택할 때까지 해당 옵션을 거부합니다. Apple Pay에는 배송 옵션용 오류 슬롯이 없으므로 응답에 무엇이 포함되든 마지막으로 허용된 합계를 유지하며, 구매자가 결제를 탭하면 첫 번째 오류의 메시지가 표시됩니다. Google Pay는 옵션을 선택할 때 메시지를 표시합니다. Apple Pay, Google Pay, PayPal에서 25초 이내에 응답하지 않은 핸들러는 예외를 발생시킨 핸들러와 마찬가지로 옵션을 거부하며, 이후의 응답은 무시됩니다. 이벤트마다 `updateWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `ShippingOptionChangeEvent`

**속성**

**option** `object & Partial\<PaymentRequestShippingOption\>` *required*

항상 선택된 `id`를 포함합니다. 제공한 옵션 중 하나와 일치하면 전체 옵션을 포함합니다.

**속성**

**id** `string` *required*

**label** `string`

**detail** `string`

**amount** `number`

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**updateWith** `(update: PaymentRequestUpdate) =\> void` *required*

25초 이내에 정확히 한 번 호출하세요. Apple Pay, Google Pay, PayPal에서 그때까지 응답하지 않은 핸들러는 판매자의 거부와 마찬가지로 옵션을 거부하며, 이후의 응답은 무시됩니다.

**매개변수**

**update** `PaymentRequestUpdate` *required*

**속성**

**amount** `number`

**lineItems** `PaymentRequestLineItem[]`

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

시트의 배송 옵션을 교체합니다. 선택된 옵션은 그 `id`가 목록에 남아 있는 동안 선택된 상태로 유지됩니다. 그렇지 않으면 `shippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 같은 응답에서 그 가격을 책정하세요. 빈 목록은 아무것도 변경하지 않습니다. 배송할 수 없는 주소는 대신 `shipping_address_unserviceable` 오류로 거부하세요.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**errors** `PaymentRequestError[]`

**속성**

**code** `string`

배송 응답이 거부하는 대상입니다. `billingAddressChange` 또는 `paymentMethodChange` 응답의 오류는 코드와 관계없이 해당 이벤트가 묻는 카드나 결제 수단을 거부합니다.

`"other"`, `"shipping_address_invalid"`, `"shipping_address_unserviceable"`, `"shipping_option_invalid"` 중 하나입니다.

**message** `string` *required*

**field** `"state" | "country" | "city" | "postal_code"`

오류와 관련된 주소 필드로, 일부 가려진 주소에 포함된 필드 중 하나입니다. Apple Pay는 `code`와 관계없이 해당 필드에 메시지를 표시하고, Google Pay는 메시지만 표시합니다. 주소 전체에 대한 오류라면 생략하세요.

### `onBillingAddressChange`

구매자가 일부가 가려진 청구지 주소(도시, 주, 우편번호, 국가만)와 함께 카드를 선택했습니다. 청구에 세금이 부과되는 주소를 기준으로 합계를 다시 책정하세요. Apple Pay는 구매자가 카드를 선택할 때, Google Pay는 시트가 열릴 때와 구매자가 카드를 바꿀 때마다 이를 실행합니다. 최소 화폐 단위로 `updateWith({ amount })`, 현재 합계를 유지하려면 `updateWith({})`, 카드를 거부하려면 `updateWith({ errors })`로 응답하세요. 모든 이벤트에는 정확히 한 번 응답해야 합니다. 예외를 발생시키거나, 거부되거나, 10초 이내에 응답하지 않는 핸들러는 카드를 거부하므로 구매자는 다른 카드를 선택하게 됩니다. Apple Pay와 Google Pay에서는 같은 선택이 이어서 `paymentMethodChange`를 실행하며, 둘 다 응답되면 시트가 한 번 업데이트됩니다. PayPal은 구매자가 PayPal에서 선택하는 각 배송 주소로 이를 실행하며, 이 주소가 토큰의 청구 및 세금 부과 기준이 되고, 여기서의 거부는 PayPal 내에서 해당 주소를 거부합니다. 이벤트마다 `updateWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `BillingAddressChangeEvent`

**속성**

**address** `PaymentRequestAddress` *required*

공급업체별로 정규화된 승인 전 청구지 주소입니다. 도시, 주, 우편번호, 국가만 포함합니다.

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**updateWith** `(update: PaymentRequestUpdate) =\> void` *required*

정확히 한 번 호출하세요. 10초 동안 응답하지 않은 이벤트는 카드를 거부하며, 구매자는 다른 카드를 선택합니다.

**매개변수**

**update** `PaymentRequestUpdate` *required*

**속성**

**amount** `number`

**lineItems** `PaymentRequestLineItem[]`

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

시트의 배송 옵션을 교체합니다. 선택된 옵션은 그 `id`가 목록에 남아 있는 동안 선택된 상태로 유지됩니다. 그렇지 않으면 `shippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 같은 응답에서 그 가격을 책정하세요. 빈 목록은 아무것도 변경하지 않습니다. 배송할 수 없는 주소는 대신 `shipping_address_unserviceable` 오류로 거부하세요.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**errors** `PaymentRequestError[]`

**속성**

**code** `string`

배송 응답이 거부하는 대상입니다. `billingAddressChange` 또는 `paymentMethodChange` 응답의 오류는 코드와 관계없이 해당 이벤트가 묻는 카드나 결제 수단을 거부합니다.

`"other"`, `"shipping_address_invalid"`, `"shipping_address_unserviceable"`, `"shipping_option_invalid"` 중 하나입니다.

**message** `string` *required*

**field** `"state" | "country" | "city" | "postal_code"`

오류와 관련된 주소 필드로, 일부 가려진 주소에 포함된 필드 중 하나입니다. Apple Pay는 `code`와 관계없이 해당 필드에 메시지를 표시하고, Google Pay는 메시지만 표시합니다. 주소 전체에 대한 오류라면 생략하세요.

### `onPaymentMethodChange`

구매자가 결제 수단을 선택했습니다. 신용카드 추가 요금처럼 해당 결제 수단에 맞게 합계를 다시 책정하세요. Apple Pay는 구매자가 카드를 선택할 때, Google Pay는 시트가 열릴 때와 구매자가 카드를 바꿀 때마다 이를 실행하며, 각각 해당 카드의 `billingAddressChange` 직후에 실행됩니다. `paymentMethod.type`은 `card`입니다. `paymentMethod.card`는 구매자가 승인하기 전에 지갑이 카드에 대해 알려 주는 정보를 담습니다. Apple Pay는 `funding`을 보고하고(Apple은 보통 그때까지 네트워크를 공개하지 않습니다), Google Pay는 `network`를 보고합니다. `paymentMethod.billingAddress`는 카드의 일부가 가려진 청구지 주소입니다. 다시 책정하려면 `updateWith({ amount, lineItems })`, 현재 합계를 유지하려면 `updateWith({})`, 결제 수단을 거부하려면 `updateWith({ errors })`로 응답하세요. `shippingOptions`는 무시됩니다. Apple Pay는 카드의 청구 연락처(지정된 경우 해당 `field`)에 거부를 표시하고 구매자가 다른 결제 수단을 선택할 때까지 결제 버튼을 보류합니다. Google Pay는 카드에 메시지를 표시하고 구매자가 허용되는 카드를 선택할 때까지 해당 카드에서의 결제 탭을 거부합니다. 거부된 카드는 이 응답이나 그 `billingAddressChange` 응답이 어떤 가격을 책정했든 합계를 그대로 둡니다. 모든 이벤트에는 정확히 한 번 응답해야 합니다. 예외를 발생시키거나, 거부되거나, 10초 이내에 응답하지 않는 핸들러는 결제 수단을 거부합니다. 각 시트는 구매자가 결제하기 전에 응답을 기다립니다. PayPal은 이를 실행하지 않습니다. 이벤트마다 `updateWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `PaymentMethodChangeEvent`

**속성**

**paymentMethod** `PaymentRequestPaymentMethod` *required*

승인 전에 지갑이 설명하는, 구매자가 선택한 결제 수단입니다.

**속성**

**type** `string` *required*

카드만 보고하는 Apple Pay와 Google Pay에서는 `card`, PayPal에서는 `paypal`입니다.

**card** `object`

지갑이 카드에 대해 알려 주는 정보입니다. 구매자가 승인하기 전 `paymentMethodChange`에서 Apple Pay는 보통 네트워크 없이 자금 유형을, Google Pay는 네트워크를 보고합니다. 승인 시에는 Apple Pay와 Google Pay 모두 둘 다 보고합니다.

**속성**

**network** `string`

**funding** `"credit" | "debit" | "prepaid" | "store"`

**billingAddress** `PaymentRequestAddress`

Apple Pay와 Google Pay가 카드와 함께 전달하는, 카드의 일부가 가려진 청구지 주소(도시, 주, 우편번호, 국가만)입니다.

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**displayName** `string`

`Visa 1234` 같은 결제 수단에 대한 지갑 자체의 레이블입니다. Apple Pay와 Google Pay는 구매자가 승인한 후에만 이를 설정하므로 `paymentAuthorization`만 이를 담습니다. 표시만 하고 파싱하지 마세요. 지갑은 형식을 보장하지 않습니다.

**updateWith** `(update: PaymentRequestUpdate) =\> void` *required*

정확히 한 번 호출하세요. `amount`와 `lineItems`는 결제 수단에 맞게 시트의 가격을 다시 책정하고, `updateWith({})`는 합계를 유지하며, `errors`는 결제 수단을 거부합니다. 10초 동안 응답하지 않은 이벤트는 결제 수단을 거부합니다.

**매개변수**

**update** `PaymentRequestUpdate` *required*

**속성**

**amount** `number`

**lineItems** `PaymentRequestLineItem[]`

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

시트의 배송 옵션을 교체합니다. 선택된 옵션은 그 `id`가 목록에 남아 있는 동안 선택된 상태로 유지됩니다. 그렇지 않으면 `shippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 같은 응답에서 그 가격을 책정하세요. 빈 목록은 아무것도 변경하지 않습니다. 배송할 수 없는 주소는 대신 `shipping_address_unserviceable` 오류로 거부하세요.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**errors** `PaymentRequestError[]`

**속성**

**code** `string`

배송 응답이 거부하는 대상입니다. `billingAddressChange` 또는 `paymentMethodChange` 응답의 오류는 코드와 관계없이 해당 이벤트가 묻는 카드나 결제 수단을 거부합니다.

`"other"`, `"shipping_address_invalid"`, `"shipping_address_unserviceable"`, `"shipping_option_invalid"` 중 하나입니다.

**message** `string` *required*

**field** `"state" | "country" | "city" | "postal_code"`

오류와 관련된 주소 필드로, 일부 가려진 주소에 포함된 필드 중 하나입니다. Apple Pay는 `code`와 관계없이 해당 필드에 메시지를 표시하고, Google Pay는 메시지만 표시합니다. 주소 전체에 대한 오류라면 생략하세요.

### `onPromoCodeChange`

구매자가 시트의 프로모션 필드(`requestPromoCode`)에 코드를 입력하거나, 변경하거나, 제거했습니다. 새 합계로 코드를 적용하려면 `updateWith({ amount })`, 현재 합계로 적용하려면 `updateWith({})`, 그 자리에서 거부하려면 `updateWith({ error })`로 응답하세요. 제거는 `code`가 null인 상태로 도착하며 같은 방식으로 응답합니다. 적용된 코드를 교체하면 제거가 먼저 오지 않고 새 코드와 함께 하나의 이벤트로 도착하며, 거부된 새 코드는 적용된 코드를 그대로 둡니다. `shippingOptions`가 선택된 옵션을 제외하면 `onShippingOptionChange` 없이 첫 번째 옵션이 선택되므로, 그 옵션의 가격을 책정하세요. `appliedDescription`은 Google Pay에서 코드의 설명 문구를 표시합니다. Apple Pay의 쿠폰 필드에는 설명 문구가 없으므로 구매자가 반드시 봐야 하는 내용은 항목 레이블에 넣으세요. 예외를 발생시키거나, 거부되거나, 10초 이내에 응답하지 않는 핸들러는 코드를 거부합니다. 이벤트마다 `updateWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `PromoCodeChangeEvent`

**속성**

**code** `string | null` *required*

현재 시트의 프로모션 필드에 있는 코드이며, 구매자가 제거한 경우 null입니다. 적용된 코드를 교체하면 제거가 먼저 오지 않고 새 코드와 함께 하나의 이벤트로 처리됩니다.

**updateWith** `(update: PromoCodeUpdate) =\> void` *required*

정확히 한 번 응답하세요. `error`는 코드를 거부하고 합계를 유지하며, 그 외의 응답은 코드를 적용합니다. `amount`와 `lineItems`는 코드 적용 시의 시트 가격을 다시 책정하고, `shippingOptions`는 배송 옵션을 교체하며(무료 배송 코드), `appliedDescription`은 시트가 표시하는 곳(Google Pay)에서 적용된 코드의 설명 문구를 표시합니다. `updateWith({})`는 현재 합계로 코드를 적용합니다.

**매개변수**

**update** `PromoCodeUpdate` *required*

**속성**

**amount** `number`

코드 적용 시의 합계로, 최소 화폐 단위입니다.

**lineItems** `PaymentRequestLineItem[]`

할인 및 그로 인해 변경되는 세금 등 코드 적용 시 시트의 항목입니다.

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**shippingOptions** `PaymentRequestShippingOption[]`

요금을 0으로 낮추는 무료 배송 코드처럼, 코드 적용 시 시트의 배송 옵션을 교체합니다. 옵션은 그 `id`가 목록에 남아 있는 동안 선택된 상태로 유지됩니다. 그렇지 않으면 `shippingOptionChange` 없이 첫 번째 옵션이 선택됩니다. 합계는 자동으로 따라가지 않으므로 선택된 옵션의 가격이 변경되면 `amount`도 함께 보내세요. 빈 목록은 아무것도 변경하지 않습니다.

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**appliedDescription** `string`

Google Pay에서 적용된 코드 옆에 표시되는 설명 문구입니다. Apple Pay의 쿠폰 필드에는 설명 문구가 없으므로 구매자가 반드시 봐야 하는 내용은 항목 레이블에 넣으세요.

**error** `object`

코드를 거부합니다. 시트는 프로모션 필드 옆에 `message`를 표시합니다.

**속성**

**message** `string` *required*

### `onPaymentAuthorization`

구매자가 결제를 승인했으며, 아직 확인 토큰은 존재하지 않습니다. 먼저 승인하거나 거부하려면 구독하세요. 시트는 응답을 기다리며, 핸들러가 없으면 토큰이 즉시 생성됩니다. 이벤트는 결제자, 결제 수단(일부가 가려진 청구지 주소와 `displayName`의 `Visa 1234` 같은 지갑 자체 레이블 포함), 배송 주소와 옵션, 구매자가 승인한 합계와 항목을 담고 있습니다. 토큰을 생성하려면 `respondWith({ approved: true })`로 응답하세요. 그러면 `show()`와 `onConfirmationToken`이 평소처럼 토큰을 전달합니다. 거부하려면 `respondWith({ approved: false, message })`로 응답하세요. 토큰은 생성되지 않으며, Apple Pay와 Google Pay는 시트에 `message`를 표시하고, 구매자는 무언가를 변경하여 다시 결제하거나 시트를 닫을 수 있습니다. PayPal은 메시지를 표시할 수 없으므로 거부하면 시도가 종료됩니다. `show()`는 `payment_request_refused`로 거부되며, 구매자는 PayPal을 다시 누를 수 있습니다. 모든 이벤트에는 정확히 한 번 응답해야 하며, `approved: true`만 토큰을 생성합니다. 예외를 발생시키거나, 거부되거나, 25초 이내에 응답하지 않는 핸들러는 결제를 거부하며, 이는 Apple Pay와 Google Pay가 자체 30초 제한 전에 거부를 표시할 수 있을 만큼 이른 시점입니다. 이벤트마다 `respondWith(…)`를 정확히 한 번 호출하세요. 호출하기 전에 예외를 발생시키거나 거부되는 핸들러는 해당 업데이트를 즉시 실패시킵니다. 구독 해제 함수를 반환합니다.

**ev** `PaymentAuthorizationEvent`

**속성**

**type** `"apple_pay" | "google_pay" | "paypal_express"` *required*

구매자가 승인한 지갑입니다.

**payer** `object` *required*

결과에 담길 결제자입니다.

**속성**

**email** `string`

**name** `string`

**phone** `string`

**country** `string`

**paymentMethod** `PaymentRequestPaymentMethod` *required*

구매자가 승인한 결제 수단입니다. 청구지 주소는 `paymentMethodChange`가 전달하는 것처럼 도시, 주, 우편번호, 국가로 가려집니다.

**속성**

**type** `string` *required*

카드만 보고하는 Apple Pay와 Google Pay에서는 `card`, PayPal에서는 `paypal`입니다.

**card** `object`

지갑이 카드에 대해 알려 주는 정보입니다. 구매자가 승인하기 전 `paymentMethodChange`에서 Apple Pay는 보통 네트워크 없이 자금 유형을, Google Pay는 네트워크를 보고합니다. 승인 시에는 Apple Pay와 Google Pay 모두 둘 다 보고합니다.

**속성**

**network** `string`

**funding** `"credit" | "debit" | "prepaid" | "store"`

**billingAddress** `PaymentRequestAddress`

Apple Pay와 Google Pay가 카드와 함께 전달하는, 카드의 일부가 가려진 청구지 주소(도시, 주, 우편번호, 국가만)입니다.

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**displayName** `string`

`Visa 1234` 같은 결제 수단에 대한 지갑 자체의 레이블입니다. Apple Pay와 Google Pay는 구매자가 승인한 후에만 이를 설정하므로 `paymentAuthorization`만 이를 담습니다. 표시만 하고 파싱하지 마세요. 지갑은 형식을 보장하지 않습니다.

**shipping** `object | null` *required*

`requestShipping`이 설정되지 않은 경우 `null`입니다. 그렇지 않으면 결과에 담길 주소와 옵션입니다.

**속성**

**address** `PaymentRequestAddress`

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**option** `PaymentRequestShippingOption`

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

**amount** `number` *required*

구매자가 승인한 합계로, 최소 화폐 단위입니다.

**lineItems** `PaymentRequestLineItem[]` *required*

시트가 해당 합계 아래에 표시한 항목입니다.

**속성**

**label** `string` *required*

**amount** `number` *required*

`amount`와 같은 최소 화폐 단위입니다.

**respondWith** `(response: PaymentAuthorizationResponse) =\> void` *required*

정확히 한 번 호출하세요. `{ approved: true }`는 확인 토큰을 생성합니다. 그 외에는 결제를 거부하며 토큰이 생성되지 않습니다.

**매개변수**

**response** `PaymentAuthorizationResponse` *required*

**속성**

**approved** `boolean` *required*

`true`는 확인 토큰을 생성합니다. `false`는 결제를 거부합니다.

**message** `string`

거부할 때 승인을 받은 시트에서 구매자에게 표시됩니다.

### `onConfirmationToken`

시트가 확인 토큰을 생성했으며, 시트가 닫힌 후에 수신됩니다. `show()`가 반환하는 결과와 같습니다. 구독 해제 함수를 반환합니다.

**ev** `PaymentRequestResult`

**속성**

**ctok** `string` *required*

`ctok_` 접두사가 붙은 확인 토큰 ID입니다. 시크릿 키를 사용해 서버 측에서 확인하세요.

**type** `"apple_pay" | "google_pay" | "paypal_express"` *required*

**payer** `object` *required*

`phone`은 연락처의 국가 기준으로 파싱되면 E.164 형식이고, 그렇지 않으면 제공된 그대로입니다. PayPal은 `requestPayerPhone`인 경우에만 전화번호를 제공하며, 전화번호가 없는 계정은 거부합니다. `country`는 모든 시트가 수집하는 청구지 국가입니다.

**속성**

**email** `string`

**name** `string`

**phone** `string`

**country** `string`

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

변경 이벤트가 전달하는 일부 가려진 주소와 달리 확인 토큰이 담는 전체 청구지 주소이며, 지갑이 제공하지 않은 경우 `null`입니다. Apple Pay와 Google Pay는 카드의 청구지 주소를 제공합니다. PayPal에서는 구매자가 PayPal에서 선택한 주소, 즉 합계에 세금이 부과된 주소입니다.

**속성**

**address** `PaymentRequestAddress` *required*

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**shipping** `object | null` *required*

`requestShipping`이 설정되지 않은 경우 `null`입니다. `option`은 선택된 배송 옵션입니다. 구매자가 다른 옵션을 선택하기 전까지는 첫 번째 옵션이며, 응답이 선택된 `id` 없이 옵션을 교체하면 다시 첫 번째 옵션이 됩니다. Apple Pay와 Google Pay는 옵션이 제공될 때마다 이를 설정하며, PayPal은 설정하지 않습니다.

**속성**

**address** `PaymentRequestAddress`

**속성**

**name** `string`

주소상의 이름입니다.

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**recipient** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `name`을 사용하세요.

`name`과 같은 값입니다.

**phone** `string`

**option** `PaymentRequestShippingOption`

**속성**

**id** `string` *required*

**label** `string` *required*

**detail** `string`

**amount** `number` *required*

최소 화폐 단위의 표시 값입니다. 리소스는 배송비를 계산하지 않습니다. 핸들러에서 `amount`를 업데이트하세요.

### `onCancel`

구매자가 시트를 닫았거나 PayPal을 닫았습니다. 구독 해제 함수를 반환합니다.

## Content Security Policy

이 리소스는 프레임이 아닌 페이지에서 실행됩니다. Content Security Policy가 있는 페이지에는 다음 소스가 필요합니다. `@whop/elements`의 `contentSecurityPolicy()`는 이 표의 모든 소스를 반환합니다. 샌드박스 소스는 `environment: "sandbox"`일 때 적용됩니다.

| 요구 사항 | 지시어 | 프로덕션 소스 | 샌드박스 소스 |
| - | - | - | - |
| Google Pay의 스크립트 | `script-src` | `https://pay.google.com` | 동일 |
| ↳ pay.js가 호출하는 Google Pay의 API | `connect-src` | `https://pay.google.com` | 동일 |
| ↳ Google이 pay.js용으로 나열한 호스트 | `connect-src` | `https://google.com` | 동일 |
| ↳ Google이 pay.js용으로 나열한 호스트 | `connect-src` | `https://account.google.com` | 동일 |
| ↳ Google이 pay.js용으로 나열한 호스트 | `connect-src` | `https://www.google.com` | 동일 |
| Apple Pay의 스크립트 | `script-src` | `https://applepay.cdn-apple.com` | 동일 |
| 지갑의 결제 데이터를 토큰화하는 Basis Theory의 API | `connect-src` | `https://api.basistheory.com` | 동일 |
| Braintree의 PayPal 스크립트 | `script-src` | `https://js.braintreegateway.com` | 동일 |
| ↳ Braintree의 스크립트가 호출하는 Braintree의 GraphQL API | `connect-src` | `https://payments.braintree-api.com` | `https://payments.sandbox.braintree-api.com` |
| ↳ Braintree의 스크립트가 호출하는 Braintree의 클라이언트 API | `connect-src` | `https://api.braintreegateway.com` | `https://api.sandbox.braintreegateway.com` |
| ↳ Braintree의 스크립트가 여는 PayPal의 랜딩 프레임 | `frame-src` | `https://checkout.paypal.com` | 동일 |
| ↳ Braintree의 스크립트가 여는 Braintree 프레임 | `frame-src` | `https://assets.braintreegateway.com` | 동일 |
| Braintree의 PayPal 스크립트가 로드하는 Braintree의 클라이언트 스크립트 | `script-src` | `https://assets.braintreegateway.com` | 동일 |
| Braintree의 스크립트가 로드하는 PayPal의 SDK | `script-src` | `https://www.paypal.com` | `https://www.sandbox.paypal.com` |
| ↳ PayPal의 SDK가 로드하는 PayPal의 FraudNet 스크립트 | `script-src` | `https://c.paypal.com` | 동일 |
| ↳ PayPal의 SDK가 호출하는 PayPal의 API | `connect-src` | `https://api-m.paypal.com` | `https://api-m.sandbox.paypal.com` |
| ↳ PayPal의 SDK가 호출하는 PayPal의 로거 | `connect-src` | `https://www.paypal.com` | `https://www.sandbox.paypal.com` |
| ↳ PayPal의 SDK가 여는 PayPal의 페이지 내 창 | `frame-src` | `https://www.paypal.com` | `https://www.sandbox.paypal.com` |
| ↳ PayPal의 SDK가 표시하는 PayPal의 로고 | `img-src` | `https://www.paypalobjects.com` | 동일 |

iOS에서는 Apple Pay 전용입니다. Google Pay는 Swift 대응 항목이 없는 웹 `show(type)` 경로입니다. 엘리먼트도 컨트롤러도 없으며, 양식 위의 익스프레스 체크아웃 버튼을 위해 직접 제어하는 객체입니다. `canMakePayment()`가 시트를 준비하고, `show()`는 엘리먼트가 생성하는 것과 같은 `ctok_`로 완료됩니다. 고객이 승인하는 즉시 시트는 성공 체크 표시와 함께 닫힙니다. 서버에서 토큰을 확인하고 앱에서 결과를 표시하세요.

## 사용법

```swift theme={null}
import Elements
import SwiftUI

struct ExpressCheckout: View {
    @State private var request = WhopPaymentRequest(
        accountID: "biz_xxxx",
        charge: .plan(id: "plan_xxxx")
    )
    @State private var isAvailable = false

    var body: some View {
        VStack {
            if isAvailable {
                WhopApplePayButton {
                    Task { await pay() }
                }
                .frame(height: 48)
            }
        }
        .task { isAvailable = await request.canMakePayment() }
    }

    private func pay() async {
        do {
            let token = try await request.show()
            try await myBackend.confirm(token.id)
        } catch {
            // show the error in your app; the sheet has already closed
        }
    }
}
```

## 매개변수

**accountID** `String` *required*

`biz_` 접두사가 붙은, 청구가 속한 계정입니다.

**configuration** `WhopElementsConfiguration`

`environment`, `returnURL`, `locale`은 다른 모든 곳에서와 같이 동작합니다. 기본값은 `WhopElementsConfiguration()`입니다.

**charge** `WhopCharge` *required*

`.plan(id:)` 또는 `.amount(minorUnits:currency:)`입니다. 나중에 설정할 수 있으며, 다음 `canMakePayment()`가 이를 다시 해석합니다.

**setupFutureUsage** `WhopSetupFutureUsage?`

`.offSession` 또는 `.onSession`입니다. 저장 동의를 표시한 후에만 설정하세요.

**options** `WhopPaymentRequest.Options`

`requestPayerEmail`과 `requestBillingAddress`는 제공하지 않은 항목을 시트에 요청하며(둘 다 기본값은 `true`), `label`은 합계 위에 표시되는 항목을 재정의합니다.

## `WhopConfirmationToken`

선택 시 반환되는 값:

* `id: String`: 서버 측에서 확인할 `ctok_`
* `paymentMethodType: WhopPaymentMethodType`: 이 경로에서는 `apple_pay`

## 상태

기기가 결제할 수 없거나, 계정에 등록된 Apple Pay 판매자가 없거나, 청구를 해석하지 못하면 `canMakePayment()`는 false를 반환하며, `lastError`가 그 이유를 알려 줍니다. `isPresenting`은 `show()`부터 반환되거나 예외가 발생할 때까지(시트가 닫힌 후의 토큰 생성 포함) true입니다. 진행 중에 두 번째 `show()`를 호출하면 `confirmationInFlight` 예외가 발생합니다. `show()`는 조용히 실패하지 않고 `walletUnavailable` 예외를 발생시키며, 그 메시지는 구매자가 시트를 닫은 경우와 시트가 아예 열리지 못한 경우를 구분합니다. API가 거부한 판매자 검증은 받은 API 오류를 그대로 발생시킵니다.

## 알아두면 좋은 점

* `show()`는 일반 비동기 호출이므로 시트를 표시하기 전에 청구에 필요한 무엇이든 await할 수 있습니다.
* Apple 자체의 `PKPaymentButton`인 `WhopApplePayButton`과 함께 사용하세요. Apple의 가이드라인은 직접 그린 모방 버튼이 아닌 시스템 컨트롤을 요구합니다.
* 이메일과 청구지 주소를 제공하지 않은 경우에만 시트에 이를 요청하며, 시트의 응답은 빠진 부분만 채웁니다.
* Apple Pay 판매자는 Whop 계정에 등록된 판매자입니다. 앱에서 제공할 것이 없으며 `In-App Payments` 기능도 필요하지 않습니다.

## 설치

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/whopio/elements-swift.git", from: "0.1.0")
]
```

> [!NOTE]
>
> `WhopPaymentRequest`는 스코프나 마운트된 엘리먼트가 필요 없으므로, 화면에 `WhopBrandingElement`가 필요하지 않은 유일한 결제 영역입니다. 판매 대행자(merchant-of-record) 문구를 직접 표시하세요. 모듈은 지갑 SDK의 `WhopElements`가 아닌 `Elements`입니다. [시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md)를 참고하세요.


## Related topics

- [Payments](https://docs.whop.com/ko/elements/latest/payments/overview.md)
- [자체 버튼에서 지갑 시트 열기](https://docs.whop.com/ko/developer/guides/payment-request.md)
- [Void payment](https://docs.whop.com/ko/api-reference/legacy/payments/void-payment.md)
