저장 흐름 선택
사용자가 지금 결제도 하는지에 따라 두 가지 경로가 있습니다.
이 페이지의 나머지 부분에서는 설정 모드를 처음부터 끝까지 다룬 다음, 나중에 저장된 수단으로 청구하는 방법을 보여줍니다.
결제 엘리먼트로 결제 수단 저장
결제 엘리먼트를mode: "setup"으로 사용해 저장 양식을 만드세요. 엘리먼트는 저장할 수 있는 수단만 제공하고, 저장에 필요한 향후 사용 동의를 구매자에게 표시하며, 확인 토큰을 전달합니다. 서버에서 이 토큰을 설정 인텐트로 변환하고, 설정 인텐트의 client_secret으로 구매자가 아직 완료해야 하는 단계를 마무리합니다.
1
설정 모드로 양식 마운트
mode="setup"과 저장된 수단을 사용할 통화를 전달하세요. 금액이 없으므로 금액 한도는 적용되지 않습니다. returnUrl을 https로 호스팅하는 페이지로 설정하세요. 은행 등록 및 일부 3D Secure 흐름은 구매자를 그곳으로 다시 보냅니다.mode="setup"으로 마운트하세요.2
서버에서 설정 인텐트 생성
확인 토큰으로 설정 인텐트를 생성하세요. Whop은 토큰의 이메일로 구매자를 식별하고 설정 인텐트와 함께
201 Created로 응답합니다. 설정 인텐트에는 status, 구매자가 아직 완료해야 하는 단계를 위한 client_secret, 그리고 succeeded가 된 후에는 저장된 수단인 payment_method_id가 포함됩니다. 저장된 수단을 시스템의 고객과 연결하려면 metadata를 첨부하세요. 이 값은 웹훅으로 다시 전달됩니다. 재시도된 요청이 수단을 두 번 저장하지 않도록 Idempotency-Key를 보내세요.3
대기 중인 단계 완료
succeeded로 반환된 설정 인텐트는 수단이 등록된 상태입니다. requires_action은 구매자가 3D Secure나 은행 등록 같은 단계를 아직 완료해야 함을 의미합니다. client_secret을 결제 흐름에서 사용하는 것과 동일한 호출인 handleNextAction에 전달하세요. 이 호출은 대화상자에서 인라인 단계를 실행하거나 구매자를 returnUrl로 보냅니다. 반환되는 status에 따라 분기하세요: succeeded는 수단이 저장되었음을, processing은 아직 결정 중임을 의미하며, 그 외에는 다시 시도해야 합니다. 대화상자를 닫으면 오류 없이 설정이 requires_action 상태로 남고, 시도가 실패하면 lastPaymentError에 이유가 담깁니다. processing은 프로세서가 아직 결정 중이라는 뜻이므로 대기 상태를 표시하고 아래 웹훅으로 저장을 확인하세요. canceled는 구매자가 단계를 포기했거나 제공업체가 수단을 거부했음을 의미합니다: last_setup_error에 제공업체의 이유가 담기며, 구매자가 떠난 경우에는 null로 유지됩니다. 대신 서버에서 상태를 읽으려면 설정 인텐트를 조회하여 동일한 status로 분기하거나, 단계가 대기 중인 동안 더 가벼운 설정 상태 조회를 폴링하세요.4
완료 처리
setup_intent.succeeded 웹훅을 수신하여 결제 수단 ID와 metadata를 다시 받으세요. 이는 탭이 닫혀도 유지되는 유일한 신호이며, 아래의 호스팅 흐름에도 동일한 핸들러가 사용됩니다. 설정 인텐트에는 표시용 payment_instrument도 포함됩니다: 이름, 표준 아이콘 세트, 그리고 카드의 경우 브랜드, 마지막 네 자리, 만료일입니다. 추가 요청 없이 저장된 수단을 표시할 수 있습니다. API 버전 2026-09-22-1 이전으로 고정된 웹훅은 저장된 수단을 대신 payment_method.id로 전달합니다.호스팅 체크아웃으로 결제 수단 저장
1
설정 모드로 체크아웃 구성 생성
청구 없이 결제 정보를 수집하려면 변형 없이 체크아웃 구성을 생성하세요. 멤버와 결제 수단을 시스템의 고객과 연결할 수 있도록 메타데이터를 추가하세요.
2
사용자를 체크아웃으로 안내
Checkout 엘리먼트를 마운트하거나 사용자를 리디렉션하여 결제 수단을 저장하게 하세요.설정 모드 구성은 동일한 엘리먼트를 결제 수단 저장용으로
마운트합니다: 아무것도 청구되지 않으며, 완료된 체크아웃은
쿼리 문자열에
- 임베디드
- 리디렉션
setup_intent_id를 포함하여 returnUrl로 리디렉션합니다.
리디렉션이 아닌 setup_intent.succeeded 웹훅으로 저장을 확인하세요.3
완료 처리
setup_intent.succeeded 웹훅을 수신하여 결제 수단 ID를 받으세요. 설정 인텐트에는 checkout_configuration_id와 구성의 metadata가 포함되며, 이를 사용해 멤버와 결제 수단을 시스템의 고객과 연결할 수 있습니다.구매자가
redirect_url에 도착하는 것이 아니라 웹훅으로 저장을 확인하세요. 이는 탭이 닫혀도 유지되는 유일한 신호입니다.저장된 결제 수단으로 청구
1
결제 수단 가져오기
멤버의 저장된 결제 수단 목록을 조회하거나, 이전 단계의 설정 인텐트에서 받은
payment_method_id를 사용하세요.2
세션 외부 결제 생성
고객의 개입 없이 결제 수단으로 청구하세요. 결제 생성 엔드포인트는 결제 객체를 즉시 반환하고 청구를 비동기적으로 처리합니다.
3
결제 이벤트 처리
결제 웹훅을 수신하여 성공 또는 실패를 추적하세요.
체크아웃 중 저장
구매자에게 청구하면서 결제 수단을 저장하려면 결제 엘리먼트로 체크아웃을 만들고Payments 핸들에 setupFutureUsage: "off_session"을 전달하세요. 엘리먼트는 구매자에게 저장 동의를 표시하고 이를 확인 토큰에 기록하며, 결제는 해당 동의가 증명된 경우에만 수단을 보관합니다.
변형을 선택하는 Elements 속성은 호환성을 위해 plan이라는 이름을 유지합니다.
1
저장 동의와 함께 양식 마운트
createConfirmationToken, handleNextAction을 안내합니다.2
확인 토큰으로 결제 생성
생성 응답은 결제 결과가 아니라 시작된 상태의 결제입니다. 저장된 수단의
payment_method_id는 청구가 완료되면 payment.succeeded 웹훅으로 전달됩니다.3
나중에 청구
payment_method_id는 저장된 결제 수단으로 청구에서 사용할 payt_ 수단입니다. 아무것도 저장되지 않은 경우 null로 유지됩니다. payment.succeeded 웹훅에도 동일한 필드가 포함되며, 이는 탭이 닫혀도 유지되는 경로입니다.다음 단계
결제 받기
저장 흐름과 함께 사용할 일회성 및 구독 체크아웃입니다.
Checkout 엘리먼트
Whop Elements로 자체 사이트에 Whop 체크아웃을 마운트하세요.
웹훅 수신
setup_intent.succeeded, payment.succeeded, payment.failed를 추적하세요.청구 포털
고객이 저장된 결제 수단을 관리하고 삭제할 수 있도록 하세요.

