Skip to Content
개발자REST APIPortal Sessions

Portal Sessions

구매자 포털 세션은 구매자가 구독을 관리하도록 잠시 사용할 URL을 발급해요.

포털 세션 생성

구독 식별자 또는 구매자 이메일로 제한된 구매자 포털 세션을 만들어요.
Idempotency-Key는 24시간 보관해요.

권한 subscriptions:write·Idempotency-Key 헤더 필수

알아둘 점

  • subscriptionId 또는 buyerEmail을 보내고, 둘 다 보내면 이메일이 구독 구매자와 일치해야 하며 returnUrl은 등록한 리디렉트 호스트만 사용할 수 있어요.
  • 세션은 60분 유효하고 API 키의 mode·상품 범위를 따르며, 범위 설정은 IP · 상품 제한에서 확인해요.
  • 가격 인상 동의, 구독 환불 요청 철회, 즉시 과금 변경(업그레이드·월간→연간 전환)은 구매자가 이메일 인증번호를 확인한 뒤에만 할 수 있어요. 포털이 인증 단계를 자동으로 띄워요.
  • 포털에서 구매자는 해지(기간말·즉시), 해지 예약 취소, 플랜·결제 주기 변경, 가격 인상 동의를 해요. 플랜 변경은 포털에서만 할 수 있어요.
  • 업그레이드와 월간→연간 전환은 바로 적용되고 차액을 청구해요. 다운그레이드와 연간→월간 전환은 기간말에 적용돼요.

헤더

Idempotency-Keystring필수

POST 요청의 중복 실행을 막는 키예요. 24시간 보관하며 본문이 다른 요청에는 같은 키를 쓸 수 없어요.

제약 1~255자

요청 본문

buyerEmailstring

구매자 이메일로 활성 구독을 찾아요.

제약 이메일·예 buyer@example.com
returnUrlstring

포털에서 돌아갈 때 사용할 URL이에요.

예 https://shop.example.com/account
subscriptionIdstring

포털 세션을 만들 구독 식별자예요.

예 sub_123

응답

성공하면 HTTP 201과 아래 필드를 돌려줘요.

expiresAtstring

토큰 만료 시각이에요.

modestring

test 또는 live 포털 환경을 알려줘요.

허용 값 live, test
tokenstring

포털 인증 토큰이에요.

urlstring

구매자 포털에 접속할 URL이에요.

오류

코드HTTP의미
SUBSCRIPTION_NOT_FOUND404구독이 없거나 키의 상품 범위 밖이에요.
CHECKOUT_URL_INVALID400Checkout 또는 포털 복귀 URL 형식이 올바르지 않아요.
RETURN_URL_NOT_ALLOWED400복귀 URL 도메인이 결제 모드별 허용 목록에 없어요.

표에 없는 공통 오류(인증·권한, 호출 한도, 입력 검증, 경로 없음, 멱등 키, 서버 오류)는 에러 코드에서 확인해요.

Last updated on
SubscriptionsLicenses