Skip to main content
이 페이지는 @whop/elements@1.10.0 및 @whop/elements-react@1.10.0을 다룹니다.
v1.0.0부터 지원.

Playground

예시 데이터로 엘리먼트를 조합해 보세요. 컨트롤을 조작하고, 엘리먼트를 추가 및 배치하며, 이벤트가 실시간으로 발생하는 것을 확인할 수 있습니다.

옵션

whop.payments.create({ … })에 전달하거나, React에서는 <Payments>의 props로 전달합니다.
다음 조합 중 정확히 하나를 전달하세요.
  • accountId 및 plan
  • accountId, currency, amount
  • accountId, mode: "setup", currency
  • plan, currency, amount, mode 모두 없음
string
biz_ 접두사가 붙은 계정 ID입니다. 계정 화면 없이 정적 메서드를 호출할 때만 생략하세요.
"payment" | "setup"
마운트 모드이며 기본값은 payment입니다. setup은 결제 수단을 저장하며 지금이나 나중에나 아무것도 청구하지 않습니다. 저장할 수 있는 결제 수단만 제공되며 금액 한도는 적용되지 않습니다. createConfirmationToken()으로 확인한 다음 서버 측에서 setup intent를 생성하세요.
string
plan_ 접두사가 붙은 플랜 ID입니다. 클라이언트 측에서 통화, 금액, 결제 수단 구성으로 확인됩니다. 플랜 또는 인라인 통화와 금액 중 하나만 전달하고, 둘 다 전달하지 마세요.
object
체크아웃이 BNPL 같은 수수료 없는 결제 수단에 맞춰 amount를 다시 책정할 때 결제 수단을 제한하는 데 사용되는 최소 단위 feeInclusive 및 feeFree 총액입니다. 각 결제 수단은 해당하는 총액과 비교되므로, 선택한 수수료 없는 결제 수단이 사라지지 않습니다. 생략하면 amount가 모든 결제 수단을 제한합니다.
string
외부 은행 또는 3DS 단계를 위한 반환 URL입니다. 기본값은 마운트한 페이지입니다. 결과와 관계없이 구매자는 payment(또는 setup), status(succeeded, failed, canceled 또는 processing 같은 대기 중 상태), client_secret이 추가된 이 URL로 이동하므로, 성공 페이지를 표시하기 전에 status에 따라 분기하세요.
"off_session" | "on_session"
setup은 off_session 사용을 위해 결제 수단을 저장하며, 이는 setup이 허용하는 유일한 사용 방식입니다.
WalletAvailability
결정적인 미리보기를 위한 지갑 사용 가능 여부 재정의입니다. 실제 체크아웃에서는 호스트를 검사합니다.
string
소문자 세 글자 ISO 4217 통화 코드입니다. 결제 수단 매트릭스를 필터링합니다.
number
최소 단위로 표시한 결제 금액입니다. 한도에서 이 금액을 제외하는 결제 수단은 제공되지 않습니다.
object
API의 enabled, disabled, include_platform_defaults 형식으로 된 계정 결제 수단 필터입니다. disabled는 유형을 제거하고, enabled는 제공되는 유형을 복원하며, include_platform_defaults: false는 활성화된 유형만 남깁니다. 플랜은 자체 구성을 제공합니다.
Appearance
이 그룹 엘리먼트의 시각적 사용자 지정입니다. 전역 WhopElements({ appearance })를 재정의합니다. update({ appearance })로 실시간으로 변경할 수 있습니다.
WhopElementsLocale
이 그룹 엘리먼트 UI 텍스트의 로캘입니다. 전역 구성을 재정의하려면 앱에 빌드된 로캘 중 하나로 설정하세요. 그 외의 값은 기본 로캘로 대체됩니다.

이벤트

생성 옵션 또는 React props로 콜백을 전달합니다.

onLoadingChange

그룹 로딩 상태가 변경될 때 실행됩니다. 마운트된 엘리먼트 중 하나라도 아직 로딩 중이면 값은 true입니다.
boolean

메서드

whop.payments.create({ … }) 또는 usePayments()에서 얻은 Payments 핸들에서 호출합니다.

createConfirmationToken

결제 버튼에서 선택한 결제 수단의 확인 토큰을 생성합니다. 체크아웃의 청구 정보를 전달하세요. email이 반드시 포함되어야 합니다. 청구 정보 수집이 비활성화된 경우 phone이 필요한 결제 수단에는 이를 제공하세요. 카드는 name과 line1 및 country가 포함된 주소도 필요합니다. 지갑을 선택하면 결제 버튼 상호작용 중에 시트가 열립니다. 계정이 페이지 내 은행 연결(은행 계좌 결제 수단 유형의 bank_debit.bank_connection)을 제공하는 경우, 은행 계좌를 선택하면 이 과정에서 Plaid Link도 열리며, 구매자가 계좌를 연결하면 호출이 완료됩니다. 이를 위해서는 whop.com 페이지 또는 Domains API를 통해 Apple Pay가 준비된 도메인과, contentSecurityPolicy()가 반환하는 Plaid 호스트를 허용하는 콘텐츠 보안 정책이 필요합니다. 그렇지 않으면 구매자는 제출 후에 계좌를 연결합니다. 구매자가 시트나 Link를 닫으면 호출은 payment_request_cancelled로 거부됩니다. 이를 결제 오류가 아닌 취소로 처리하고 구매자가 다시 결제할 수 있게 하세요. 반환된 confirmationToken을 서버 측에서 확인한 다음 WhopElements.payments.handleNextAction(…)을 호출하세요. 컨트롤러 iframe이 아닌 사용자 페이지(호스트 측)에서 실행됩니다. 매개변수
object
필수
반환값 Promise<object>
string
필수
string
필수

update

마운트된 모든 엘리먼트에 새 핸들 옵션을 병합합니다. React에서는 대신 네임스페이스 props를 변경하세요. 매개변수
Partial<PaymentsOptions>
필수

destroy

이 핸들이 생성한 모든 엘리먼트와 하위 컨트롤러를 제거하고, 컨트롤러 프레임을 삭제하며, 구독을 해제합니다. 여러 번 호출해도 되지만, 제거된 핸들은 다른 모든 호출을 거부하므로 다시 시작하려면 새 핸들을 생성하세요. 프로바이더가 언마운트되면 React가 그룹을 자동으로 제거합니다.

정적 메서드

마운트 없이 호출합니다. 바닐라에서는 whop.payments.<method>(…), React에서는 useWhop().payments.<method>(…)를 사용합니다.

handleNextAction

엘리먼트를 마운트하지 않고 확인된 결제의 대기 중인 단계를 완료합니다. clientSecret이 결제를 식별하므로 결제 ID는 필요하지 않습니다. 인라인 단계는 대화 상자에서 열리며 redirected: false로 완료됩니다. 대화 상자를 닫으면 결제의 현재 상태가 반환되며, 이 상태는 대기 중으로 남아 있을 수 있습니다. 전체 페이지 단계는 redirected: true와 함께 return_url로, 결제에 반환 URL이 없으면 호스팅 영수증으로 리디렉션됩니다. iframe 안에서는 최상위 탭을 이동시킵니다. 임베딩 페이지가 이 이동을 거부하면 TAB_NAVIGATION_BLOCKED 코드로 거부되며, 결제는 대기 상태로 유지됩니다. 표시 전에 목적지를 업데이트하려면 returnUrl을 설정하세요. 업데이트에 실패하면 어떤 단계도 실행되기 전에 거부됩니다. 인라인 단계는 해당 URL로 이동하지 않습니다. 청구 결과가 아직 결정 중인 결제는 단계가 나타나거나 확정될 때까지 폴링되며, 단계 없이 결정된 결제는 즉시 완료됩니다. 매개변수
object
필수
반환값 Promise<object>
string
필수
boolean
필수
object | null
필수

리소스

엘리먼트를 마운트하지 않고 다음 SDK 객체를 생성합니다. 각각 별도의 페이지가 있습니다.

PaymentRequest

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

Content security policy

이 그룹의 일부 작업은 프레임이 아닌 사용자 페이지에서 실행됩니다. 콘텐츠 보안 정책이 있는 페이지에는 다음 소스가 필요합니다. @whop/elements의 contentSecurityPolicy()는 이 표의 모든 소스를 반환합니다. 샌드박스 소스는 environment: "sandbox"일 때 적용됩니다.

엘리먼트

이 그룹이 마운트하는 엘리먼트입니다. 각각 별도의 페이지가 있습니다.

AddressElement

청구지 또는 배송 주소를 수집합니다. 필드, 순서, 유효성 검사는 선택한 국가를 따릅니다. 거리 주소 자동 완성(휴대폰에서는 전체 화면)과 주소를 읽거나 검증하는 메서드를 포함합니다.

EmailElement

구매자의 이메일을 수집하고, 마운트되어 있는 동안 payments.createConfirmationToken()에 전달합니다. 명시적으로 지정한 billingDetails.email이 우선합니다. 일치하는 Whop 계정이 있으면 코드 인증 또는 계정에 패스키가 있는 경우 패스키를 사용한 선택적 로그인이 표시됩니다. 로그인에 성공하면 payment 엘리먼트에서 저장된 결제 수단을 사용할 수 있습니다. 구매자는 게스트로 계속 진행할 수 있습니다.

TaxIdElement

API에서 허용하는 사업자 세금 등록 정보를 수집합니다. 레이블은 구매자에게 친숙한 이름을 사용합니다. 플레이스홀더는 선택한 형식과 일치합니다. country는 유형을 미리 선택합니다. onChange는 확정된 쌍을 전달합니다. API 유효성 검사 오류는 호스트가 제공합니다.

BrandingElement

필수 — AddressElement, EmailElement, TaxIdElement를 제외한 다른 엘리먼트는 이 엘리먼트를 기다립니다. Whop의 판매 대행자(merchant of record) 고지입니다. Whop 구매자 서비스 약관 및 개인정보 처리방침에 대한 구매자의 동의를 Whop 워드마크와 함께 표시합니다. 필수 항목입니다. 이 엘리먼트가 마운트될 때까지 payment, card, card fields 엘리먼트는 로딩 상태로 유지되며, 이 엘리먼트 없이는 결제를 확인할 수 없습니다.
대안. 한 번에 하나만 마운트하세요. 다른 엘리먼트를 마운트하기 전에 제거하세요.

PaymentElement

사용 가능한 결제 수단을 표시하고 선택한 결제 수단에 필요한 필드와 고지 사항을 수집합니다. change를 사용해 결제 버튼을 활성화하세요. 활성화 핸들러에서 payments.createConfirmationToken()을 호출하세요. 서버 측에서 토큰을 확인한 다음, 대기 중인 단계가 있으면 payments.handleNextAction(…)에 전달하세요. 주소에 따른 업데이트에는 addressChange를 사용하세요.

CardElement

카드 번호, 만료일, 보안 코드 필드가 미리 배치된 엘리먼트입니다. payments.create("card")로 생성하고, onChange에서 결제 버튼을 활성화한 뒤 payments.createConfirmationToken()으로 확인합니다. 카드 번호는 PCI로 격리된 호스팅 필드에 유지됩니다. layout은 stacked(기본값)와 compact를 지원합니다.

CardFields

사용자 지정 레이아웃을 위해 별도로 마운트할 수 있는 세 개의 PCI 격리 카드 필드(번호, 만료일, 보안 코드)입니다. payments.create("cardFields")로 생성하고, 각 필드를 배치한 뒤, onChange에서 결제 버튼을 활성화하고 payments.createConfirmationToken()으로 확인합니다. 카드 번호는 호스팅 필드에 유지됩니다. (하위 컨트롤러, 엘리먼트 3개)