Skip to main content
플랫폼에 하위 계정을 등록하려면 플랫폼 계정 아래에 해당 대상을 위한 Account 객체를 생성하세요. 그러면 해당 계정은 직접 청구를 받고, 이체를 수신하며, Whop 지급 흐름을 사용할 수 있습니다.

예시

하위 계정을 위한 계정을 생성하세요:
이 예시에서:
  • email은 하위 계정의 이메일 주소입니다. Whop은 이를 사용해 하위 계정을 식별하고 중요한 알림을 보냅니다.
  • Account API 키에 따라 하위 계정을 소유하는 플랫폼 계정이 결정됩니다.
  • title은 하위 계정의 필수 표시 이름입니다.
  • external_id는 이 하위 계정에 대한 플랫폼 자체의 ID입니다(예: 스토어 ID). 각 ID는 하나의 하위 계정에 매핑되며, 나중에 이 ID로 계정을 조회할 수 있습니다.
  • metadata에는 하위 계정의 분류 또는 등급 수준인 seller_tier(예: “bronze”, “silver”, “gold”)와 같은 사용자 지정 키-값 쌍이 포함됩니다.
  • 응답에는 향후 API 호출에서 이 하위 계정을 참조하는 데 사용할 수 있는 account.id가 포함됩니다
이메일 주소는 계정을 관리할 하위 계정(비즈니스 또는 개인)의 것이어야 합니다. 이 사람이 계정 설정 및 결제 알림을 받게 됩니다.

자체 ID로 하위 계정 찾기

external_id로 하위 계정 목록을 조회하여 레코드 중 하나에 해당하는 계정을 가져오세요. 값 끝에 %를 붙이면 shopline:%처럼 선택한 네임스페이스로 시작하는 ID를 가진 모든 계정을 가져옵니다. 일치는 대소문자를 구분하며, _는 문자 그대로 일치하고, %는 끝에서만 작동하므로 생성하는 ID에 이 문자를 포함할 수 없습니다.
TypeScript
Update Account는 기존 하위 계정의 external_id를 설정하거나 지웁니다. 플랫폼만 이를 변경할 수 있습니다. 하위 계정은 읽을 수 있지만 편집할 수는 없습니다.

이메일 주소 재사용

각 하위 계정에 고유한 external_id가 있는 한 여러 하위 계정이 하나의 이메일 주소를 공유할 수 있습니다. 계정 생성은 이메일과 external_id 쌍에 대해 멱등적입니다:
  • 새 external_id: 이메일이 이미 사용 중이더라도 Whop이 새 하위 계정을 생성합니다.
  • 동일한 이메일과 external_id: Whop이 중복을 생성하는 대신 기존 하위 계정을 반환하므로 재시도가 안전합니다.
  • 다른 이메일에 이미 사용된 external_id: Whop은 해당 ID로 두 번째 계정을 생성하는 대신 409를 반환합니다. 같은 요청에서 ID를 새 계정으로 옮기려면 ID에 연결된 계정 교체를 참고하세요.
  • external_id 없음: 해당 이메일에 대해 external_id가 없는 기존 하위 계정이 있으면 Whop이 이를 반환합니다.
이메일을 공유하는 계정은 해당 받은편지함을 받는 사람인 동일한 Whop 사용자가 관리합니다.
이 가이드의 이전 버전에서는 external_id를 metadata 안에 넣었습니다. Whop은 모든 API 버전에서 여전히 이를 허용하며, 이 값으로 external_id를 설정하고 metadata에 반환합니다. 최상위 필드와 동일한 규칙을 따르며, 다른 하위 계정이 이미 해당 값을 가지고 있으면 409를 반환하므로, 재사용하려면 reassign_external_id: true를 보내세요. 나중에 metadata.external_id를 변경해도 external_id는 변경되지 않습니다. 변경하려면 Update Account를 사용하세요. 새 통합에서는 최상위 필드를 보내야 합니다.

ID에 연결된 계정 교체

새 소유자에게 이전되는 스토어처럼 자체 시스템에서 계정을 다시 발급하는 경우, 동일한 external_id와 reassign_external_id: true로 새 하위 계정을 생성하세요. Whop은 409를 반환하는 대신 같은 요청에서 ID를 새 하위 계정으로 옮깁니다.
TypeScript
  • ID를 가지고 있던 하위 계정은 삭제되거나 다른 방식으로 변경되지 않습니다. external_id가 null로 설정된 상태로 활성 상태를 유지하고, metadata와 잔액을 유지하며, account.updated 웹훅을 보냅니다. 더 이상 필요하지 않으면 직접 삭제하세요.
  • 생성이 실패하면 ID는 원래 위치에 그대로 남습니다.
  • 기존 하위 계정을 변경하므로, 요청에는 company:create_child와 함께 플랫폼 계정에 대한 company:update 권한이 필요합니다.
  • 기존 하위 계정과 동일한 이메일과 external_id를 가진 요청은 플래그를 설정하더라도 해당 하위 계정을 반환합니다.
  • ID는 자신의 하위 계정 사이에서만 이동합니다.
이미 존재하는 두 하위 계정 사이에서 ID를 옮기려면 Update Account를 두 번 호출하세요: 이전 계정에서 external_id를 지운 다음, 다른 계정에 설정합니다. Update Account에는 reassign_external_id가 없으며, ID를 지우기 전에 설정하면 409가 반환됩니다.

온보딩 완료

수신자에게 아직 Whop 계정이 없다면, 계정을 생성한 후 계정 온보딩 링크를 보내세요. 수신자는 해당 링크를 통해 고객 확인(KYC) 인증을 완료하며, 그 후 계정은 이체 및 기타 지급 흐름을 받을 수 있습니다.
수신자가 온보딩을 완료하면 다음을 할 수 있습니다:
  • 애플리케이션 수수료가 포함된 체크아웃 흐름을 생성합니다.
  • 계정 잔액으로 자금을 이체합니다.
  • 지급 포털로 자금을 출금하도록 합니다.

시작하기

하위 계정을 등록하려면 먼저 플랫폼 계정을 설정해야 합니다:
  1. 플랫폼 계정에 가입: whop.com/dashboard에서 계정을 생성하세요
  2. Account API 키 생성: 개발자 설정 페이지로 이동하여 Account API 키를 생성하세요
  3. 인증에 API 키 사용: 이 API 키로 Current API에 인증하고 하위 계정을 제어합니다
Account API 키는 플랫폼 계정 아래에서 하위 계정을 생성하고 관리하는 데 필요한 권한을 제공합니다.

사용자 지정 메타데이터

계정을 생성할 때 사용자 지정 메타데이터를 첨부할 수 있습니다. 메타데이터를 사용하면 각 하위 계정에 대한 추가 정보를 키-값 쌍으로 저장할 수 있습니다. 다음과 같은 경우에 유용합니다:
  • 하위 계정 등급 또는 분류 추적
  • 플랫폼 데이터베이스 레코드와 연결
Whop은 메타데이터를 Account 객체에 저장하고 모든 읽기에서 반환하지만, 이를 기준으로 계정을 필터링할 수는 없습니다. 계정을 조회할 때 사용하는 식별자는 대신 external_id에 넣으세요.

API 레퍼런스

Create Account API

계정 생성 및 사용 가능한 모든 매개변수에 대한 전체 API 레퍼런스를 확인하세요

다음 단계

하위 계정을 위한 Account를 생성한 후:

결제 수금 및 분배

직접 청구와 이체 중에서 선택하기

지급 포털 렌더링

하위 계정이 자금을 출금할 수 있도록 하기