Skip to main content
이 페이지는 @whop/elements@1.10.0 및 @whop/elements-react@1.10.0을 다룹니다.
v1.0.0부터 지원.
Payments 안에 마운트됩니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다. select()를 호출하려면 생성된 핸들 또는 React ref를 보관하세요.
배타적. PaymentElement는 이 Payments 핸들에서 CardElement 또는 CardFields의 대안입니다. 한 번에 하나만 마운트하세요. 다른 것을 마운트하기 전에 제거하세요.
BrandingElement를 기다립니다. 이 엘리먼트는 같은 Payments 핸들에 BrandingElement가 마운트될 때까지 로딩 상태로 유지됩니다.
WhopPayments 스코프 안에 마운트됩니다. 청구에서 제공하는 결제 수단 타일을 렌더링한 다음, 선택한 결제 수단이 수집하는 항목(카드 필드, 결제 수단이 선언한 필드 또는 Apple Pay 버튼)을 렌더링합니다.
청구와 확인 토큰을 소유하는 <Payments> 안에 마운트합니다. <Payments> 자체는 <WhopElements> 안에 마운트됩니다. 청구에 대한 결제 수단 타일을 렌더링하고 선택한 결제 수단이 선언하는 항목을 수집하므로, 카드, 지갑 시트, 은행 리디렉션 모두 같은 한 줄로 처리됩니다.

예시 데이터입니다. Playground 열기.

Props

string[]
두 레이아웃 모두에서 표시 순서를 제어합니다. 나열된 유형이 순서대로 먼저 표시됩니다. 나열되지 않은 유형은 상대적 순서를 유지합니다. 사용 가능 여부에는 영향을 주지 않습니다. 기본값은 []입니다.
object
엘리먼트가 제공하는 지갑을 제어합니다. 각 키의 기본값은 'auto'이며, 계정, 구매자의 기기, 청구가 지원하는 곳이면 어디서든 지갑을 제공합니다. 'never'는 해당 지갑을 결제 수단 목록에서 제거합니다. 페이지에서 paymentRequest로 자체 Apple Pay, Google Pay 또는 PayPal 버튼을 그리는 경우 이를 사용하면 구매자에게 각 지갑이 한 번씩만 표시됩니다. payPal: 'never'는 PayPal 결제 수단을 제거합니다. 저장된 결제 수단에는 영향을 주지 않습니다. 기본값은 {}입니다. v1.8.0부터 지원.
object
청구 정보 수집을 제어합니다. billingDetails: 'minimal'(기본값)은 각 결제 수단의 매트릭스를 따릅니다. 결제 수단은 기본적으로 이름과 국가별 전체 형식을 수집합니다. 재정의를 통해 선언된 최소 항목만 수집하거나 아무것도 수집하지 않을 수 있습니다. 카드의 경우 최소 항목은 카드상의 이름, 국가, 우편번호입니다. 'full'은 모든 새 결제 수단에 이름과 국가별 전체 형식을 요구합니다. 'never'는 블록을 숨깁니다. address: 'minimal'은 각 결제 수단이 선언한 최소 항목과 함께, 그 최소 항목에 국가가 없으면 국가를 수집합니다(billingDetails: 'full'이 체크아웃에 세금이 부과된다고 나타내면 우편번호도 수집). 단, 지갑, 암호화폐, 은행 직불, 은행 송금, 카드 현장 결제, 인앱 구매는 주소를 전혀 수집하지 않으며, 제공업체가 전체 청구지 주소를 요구하는 결제 수단(requires_full_billing_address)은 해당 타일이 플래그가 없는 체크아웃과 같은 규칙을 따릅니다. 그 외에는 billingDetails: 'full'보다 우선합니다. 판매자가 전체 청구지 주소를 수집하지 않을 때 사용하세요. phone: 'never'는 양식에서 이미 전화번호를 수집하는 경우 청구지 전화번호 입력만 숨깁니다. 전화번호가 필요한 결제 수단에는 billingDetails.phone을 createConfirmationToken에 전달하세요. 대신 주소를 createConfirmationToken에 전달하세요. 국가 선택기에는 결제 수단과 결제 통화가 지원하는 국가만 포함됩니다. 할부 플랜이 선택된 경우 플랜이 제공되는 국가로 좁혀집니다. 청구지 국가는 청구가 처리되는 거래 국가입니다. 하나만 사용 가능하면 고정됩니다. 기본값은 {"billingDetails":"minimal"}입니다.
object
각 결제 수단의 청구 블록이 처음 렌더링될 때 청구 정보를 미리 채웁니다. 구매자는 미리 채워진 모든 필드를 편집할 수 있습니다. address.country는 ISO 3166-1 alpha-2 코드이며 선택한 결제 수단이 허용하는 경우에만 적용됩니다. phone은 전화번호를 수집하는 결제 수단의 청구지 전화번호 입력을 +14155552671 같은 E.164 형식으로 채웁니다. 결제 수단이 지원하는 전화 국가 외의 번호는 무시됩니다. 블록이 렌더링하는 필드만 미리 채워지고 전송됩니다. 그 외의 항목은 billingDetails에 담아 createConfirmationToken에 전달하세요. v1.1.0부터 지원.
"accordion" | "horizontal"
선택기 레이아웃입니다. accordion(기본값)은 결제 수단을 세로로 쌓고 세부 정보를 인라인으로 펼칩니다. horizontal은 너비가 같고 스크롤되지 않는 타일을 표시하며 선택한 세부 정보를 아래에 표시합니다. 결제 수단이 네 개를 넘으면 More 타일이 네이티브 선택기를 엽니다. 거기서 선택한 결제 수단은 다음 선택 전까지 마지막 타일을 차지합니다. 선택과 확인은 동일하게 동작합니다. 기본값은 "accordion"입니다.
boolean
accordion 전용입니다. 결제 수단 사이에 간격과 별도의 카드 스타일을 추가합니다. layout이 horizontal이면 무시됩니다. 기본값은 false입니다.
boolean
해석 후 첫 번째로 제공되는 결제 수단을 선택할지 여부입니다. 기본값 true는 order를 따르며 구매자 상호작용처럼 selected와 change를 전달합니다. 구매자 상호작용 전에 한 번 실행되며, 제공되는 결제 수단이 없으면 아무 작업도 하지 않습니다. 선택되지 않은 상태로 마운트하려면 false로 설정하세요. 이와 별개로, 업데이트로 선택된 결제 수단이 제거되면 선택은 첫 번째로 제공되는 결제 수단으로 대체됩니다. 이미 선택되지 않은 엘리먼트는 선택되지 않은 상태로 유지됩니다. 기본값은 true입니다.

이벤트

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

onChange

선택이 변경될 때 실행됩니다. complete: true는 구매자가 결제 수단을 선택하고 카드 필드 또는 필수 입력을 완료했음을 의미합니다. 이를 사용해 확인을 활성화하세요. paymentMethod는 저장된 결제 수단이든 새 결제 수단이든 선택된 결제 수단이며, 아무것도 선택되지 않은 동안에는 null입니다. displayName과 icons는 엘리먼트가 표시하는 방식대로 선택 항목의 이름을 나타내고(balance.imageUrl은 잔액 소유자의 이미지), card는 카드의 네트워크, 마지막 네 자리, 자금 유형을 담고, requiresBillingPhone은 결제 수단이 청구 정보에 전화번호를 필요로 하는지 나타내며, countries는 청구 통화로 해당 결제 수단을 사용해 결제할 수 있는 국가를 나열합니다. 최상위 수준의 type, requiresBillingPhone, method는 더 이상 사용되지 않으므로 paymentMethod에서 읽으세요. 최상위 수준의 supportsBuyerFee도 대체 항목 없이 더 이상 사용되지 않습니다. Whop이 구매자 서비스 수수료를 직접 책정합니다.
PaymentElementChangeEvent

onAddressChange

내부 청구지 주소가 변경되고 약 300ms 후에 실행됩니다. 세금, 배송 또는 기타 주소에 따른 업데이트에 사용하세요. country는 ISO 3166-1 alpha-2 코드입니다. 페이로드는 비어 있거나 해당 국가에서 사용되지 않는 다른 주소 키를 생략합니다. complete: true는 청구 블록이 유효하고 완료되었음을 의미합니다. 이 이벤트는 결제 엘리먼트가 주소 수집을 담당하는 동안에만 실행됩니다. fields.billingDetails: 'never'인 경우 자체 주소 소스를 사용하세요. AddressElement가 마운트된 경우 해당 엘리먼트의 change 이벤트를 사용하세요.
object

onLoaderStart

로딩 스켈레톤이 처음 그려진 후, onReady 전에 실행됩니다.

onReady

엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.

onError

엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 code를 사용하세요. sourceKey는 실패한 호스트 상태 소스를 식별합니다.
object

메서드

create가 반환한 핸들에서, 또는 React ref를 통해 호출합니다.

select

구매자 상호작용과 같은 경로로 결제 수단을 선택합니다. 예를 들어 select('cashapp')은 타일을 펼치고 selected와 change를 전달합니다. 카드는 필드가 완료될 때까지 complete: false로 유지됩니다. 알 수 없거나, 사용할 수 없거나, 금액으로 제한된 결제 수단은 METHOD_NOT_OFFERED 코드로 거부됩니다. select(null)은 선택을 해제하고 complete: false와 함께 change를 전달합니다. 외부에서 완전히 제어하려면 autoSelect={false}와 함께 사용하세요.매개변수
string | null
필수
반환값 Promise<void>

mount

target에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.매개변수
string | HTMLElement
필수

destroy

엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.

update

마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.매개변수
Partial<PaymentElementProps>
필수

스타일링

appearance.classes를 통해 다음 부분의 스타일을 지정합니다. 속성 이름은 카멜 케이스 또는 케밥 케이스를 사용하고 단위를 포함하세요. 페이지 스타일시트는 엘리먼트의 프레임에 적용되지 않습니다. 프레임워크는 각 선언을 삽입하기 전에 유효성을 검사합니다.
React에서는 appearance를 <Payments>에 전달합니다. 전역으로 설정하려면 WhopElements({ appearance })를 사용하세요.

매개변수

[WhopPaymentMethodType]
이 마운트의 타일 순서로, 컨트롤러의 methodOrder를 재정의합니다. 나열된 유형은 목록의 위치를 따르고, 나머지는 그 뒤에서 들어온 순서를 유지합니다.
Binding<WhopPaymentSelection>?
현재 선택과 완료 여부를 다시 읽어 옵니다. 컨트롤러는 어느 쪽이든 둘 다 추적합니다.

WhopPaymentSelection

선택 시 반환되는 값:
  • isComplete: Bool: 선택한 결제 수단에 필요한 모든 항목이 있음
  • type: WhopPaymentMethodType?: 선택한 결제 수단
  • displayName: String?: 매트릭스에 표기된 레이블
  • category: String?: card, wallet, bank_debit, …

상태

결제 수단 매트릭스가 로드되는 동안 스켈레톤 타일을 표시하고, 읽기에 실패하면 실패 메시지를 표시합니다. 이 빌드에서 실행할 수 없는 카테고리의 결제 수단은 깨진 타일로 렌더링하지 않고 건너뜁니다. 지갑을 선택하면 확인 영역이 Apple Pay로 바뀝니다.

알아두면 좋은 점

  • Apple Pay는 앱에서 아무것도 필요로 하지 않습니다. 판매자 식별자나 In-App Payments 기능이 필요 없습니다. 판매자는 Whop 계정에 등록된 판매자이며, 기기가 결제할 수 있으면 언제든 타일이 렌더링됩니다.
  • secure 필드를 선언하는 결제 수단은 이를 호스팅 입력으로 렌더링합니다. 해당 값은 앱 프로세스에 절대 들어오지 않습니다.
  • 로그인한 구매자의 저장된 결제 수단은 새 결제 수단 위에 표시됩니다. 자격 증명을 생성하는 로그인을 제공하려면 WhopEmailElement를 마운트하세요. 저장된 행을 선택하면 아무것도 수집하지 않고 참조를 생성합니다.
  • 할부 단계를 게시하는 카드 청구는 카드 패널 안에 플랜 선택기를 표시합니다. 구매자의 카드로 이용할 수 없는 플랜은 흐리게 표시되지 않고 접히며, 지역이 청구지 국가와 맞지 않는 플랜은 토크나이저가 실행되기 전에 거부됩니다.
  • 신분 문서가 필요한 시장(현재는 ars 청구)은 패널 안에 유형 선택기와 번호 필드를 렌더링합니다. 이 번호는 카드와 달리 토크나이저로 가는 도중 앱을 거치지만, 여전히 Whop에는 도달하지 않습니다.
  • 카드 및 보안 필드 값은 토큰 생성 전에 토큰화되므로, 앱을 거치는 것은 확인 토큰뿐입니다.
  • 결제 수단에 청구지 국가가 필요한 경우 WhopAddressElement를 옆에 마운트하세요. 타일 목록이 해당 국가에서 허용하는 결제 수단으로 좁혀집니다.

설치

컨트롤러를 생성하여 콘텐츠에 전달하는 WhopPayments(accountID:charge:) 스코프 안에 마운트하세요. 이메일 로그인으로 구매자가 확인되면 payments.buyer는 로그인한 구매자입니다. Whop은 이러한 판매의 판매 대행자이며 createConfirmationToken은 WhopBrandingElement 없이는 거부되므로, 이 엘리먼트도 화면에 있어야 합니다. 스타일은 .whopElementsAppearance(_:)로 지정합니다. 모듈은 지갑 SDK의 WhopElements가 아니라 Elements입니다. 시작하기 및 Appearance를 참고하세요.

Props

string[]
Stripe의 paymentMethodOrder와 같은 의미의 결제 수단 표시 순서입니다. 나열되지 않은 유형은 나열된 유형 뒤에서 들어온 상대적 순서를 유지합니다. <Payments>에서 한 번 설정할 수도 있습니다.
(payload: PaymentChangePayload) => void
선택과 완료 여부가 변경될 때마다 실행됩니다. 제출 버튼은 complete로 제어하세요.
StyleProp<ViewStyle>
엘리먼트의 외부 View에 적용됩니다. 테마 지정에는 이 화면의 모든 엘리먼트에 적용되는 프로바이더의 appearance.parts를 사용하는 것이 좋습니다. 현재 React Native 파트 이름은 웹의 whop-* 클래스 이름과 별개의 체계이므로, 웹 appearance 객체를 그대로 옮겨 쓸 수 없습니다.
ReactNode
엘리먼트가 로드되는 동안 기본 스켈레톤 대신 렌더링됩니다.
() => void
엘리먼트가 상호작용 가능해지면 한 번 실행됩니다. <Payments>가 이를 그룹화하므로 보통은 <Payments> 자체의 onLoadingChange를 사용하는 것이 좋습니다.
(error: { message: string; code?: string }) => void
이 엘리먼트의 로드 또는 구성 실패입니다. 어떤 경우든 엘리먼트는 자체 오류 화면을 렌더링합니다.

PaymentChangePayload

onChange가 반환하는 값:
  • complete: boolean: 선택한 결제 수단에 필요한 모든 항목이 있음
  • type?: string: 선택한 결제 수단 유형(예: card)
  • method?: { type, category, template, display_name }: 선택한 결제 수단의 매트릭스 항목

상태

결제 수단 매트릭스가 도착할 때까지 세 개의 스켈레톤 행이 표시된 후 타일이 표시됩니다. 타일을 선택하면 그 아래에 세부 영역이 펼쳐집니다. 선택한 결제 수단에 필요한 모든 항목이 있으면 onChange가 complete를 보고하며, 이것이 제출 버튼을 제어합니다. 사용 가능한 결제 수단이 없는 청구는 아무것도 렌더링하지 않는 대신 설명이 담긴 빈 상태를 렌더링합니다.

알아두면 좋은 점

  • 카드 번호는 절대 코드를 거치지 않습니다. 필드는 PCI 격리된 네이티브 입력이고 SDK는 Whop에 토큰을 전달하므로, 앱은 PCI 범위 밖에 머뭅니다.
  • Apple Pay와 Google Pay는 모두 플랫폼 자체의 시트를 표시합니다. 둘 다 아무것도 필요로 하지 않습니다. Apple Pay는 Whop 계정에 등록된 판매자를 사용하므로 전달할 판매자 식별자나 Xcode에서 추가할 기능이 없으며, googlePayMerchantName은 시트에 표시되는 이름만 설정하고 기본값은 Whop입니다.
  • 리디렉션 결제 수단과 3D Secure는 iOS에서는 ASWebAuthenticationSession을, Android에서는 Custom Tabs를 엽니다. WebView가 아닌 시스템 브라우저를 사용하므로 발급사의 페이지는 앱의 신뢰 경계 밖에 머뭅니다.
  • <Payments>의 returnUrl을 직접 호스팅하는 https URL로 설정하세요. API는 https 또는 루프백 외에는 모두 거부하므로(PaymentsApi::ValidateReturnUrl) 커스텀 앱 스킴은 사용할 수 없습니다. 딥 링크를 등록할 필요는 없습니다. 발급사가 리디렉션한 후 handleNextAction이 결제가 확정될 때까지 폴링하고 브라우저를 직접 닫습니다.
앱을 <WhopElements getToken={…}>로 한 번 감싼 다음, 엘리먼트를 <Payments>로 감싸 마운트하세요. 시작하기 및 Appearance를 참고하세요.