# 토스페이먼츠 앱 설치하기

> 하이퍼클래스 플랫폼에서 **원화(KRW)** 결제를 받기 위한 토스페이먼츠 연동 앱입니다. 이 문서는 **서브계정(Sub-account)에 앱을 설치**하고, **상품을 만들어 테스트 모드로 결제까지 확인**하는 전 과정을 안내해요.

***

## 시작하기 전에

설치 전에 아래 사항을 확인하세요.

* **설치 권한** — 앱은 에이전시(Agency)와 서브계정(Sub-account) 양쪽에서 설치할 수 있어요. 이 문서는 **서브계정 직접 설치**를 기준으로 설명합니다.
* **로그인 상태** — 설치를 시작하기 전에 하이퍼클래스에 로그인되어 있어야 해요. 탭은 **하나만** 열어두는 걸 권장합니다. (여러 탭을 열어두면 로그인 토큰이 꼬여서 `The token in Authorization header is not valid!` 오류가 날 수 있어요 — 아래 [문제 해결](#문제-해결) 참고)
* **토스페이먼츠 키** — 테스트는 키 입력 없이 바로 가능합니다. 실제 결제(운영)로 전환할 때만 토스페이먼츠에서 발급받은 라이브 키가 필요해요.

***

## 1부. 서브계정에 앱 설치하기

### 1단계 — 앱 페이지 열기

1. 설치할 **서브계정에 로그인**하세요.
2. 왼쪽 메뉴에서 **App Marketplace**(앱 마켓플레이스)로 이동합니다.
3. 검색창에 **`TossPayments`** 또는 \*\*`토스페이먼츠`\*\*를 입력해 앱을 찾으세요.
4. **HyperClass - TossPayments(토스페이먼츠)** 앱을 클릭합니다.

> 앱 페이지 상단에서 카테고리는 **Payment Provider**, Pricing은 **Free**, "Who can install?"에 **Agency / Sub-Account**가 모두 체크되어 있는 것을 볼 수 있어요.

### 2단계 — 설치(Install) 클릭

1. 오른쪽 위 **Install** 버튼을 클릭합니다.
2. 권한 동의 화면이 뜨면 내용을 확인하고 동의하세요. (결제·연락처·상품 관련 권한이 필요합니다.)
3. **설치할 위치(Location)를 선택**하는 화면이 나오면, 결제를 받을 **서브계정을 선택**하고 진행합니다.

### 3단계 — 설치 완료 확인

설치가 정상적으로 끝나면 **"✅ 토스페이먼츠 결제 연동 설치 완료"** 화면이 나타나요. 이 창은 닫아도 됩니다.

이때 앱이 자동으로 처리하는 일은 다음과 같아요.

* 토스페이먼츠를 **결제 수단(Custom Payment Provider)으로 등록**
* 정기구독(Subscription) 지원 활성화
* **테스트 모드 설정 자동 적용** — 별도로 키를 입력하지 않아도 바로 테스트 결제를 해볼 수 있는 상태가 됩니다.

> 💡 즉, 설치만 하면 **테스트 모드는 곧바로 사용 가능한 상태**입니다. 라이브 키는 운영 전환 시에만 입력하면 돼요.

***

## 2부. 토스페이먼츠를 결제 수단으로 켜기

설치 후, 결제 화면에 토스페이먼츠가 나타나도록 활성화해 주세요.

1. 서브계정 왼쪽 메뉴에서 **Payments(결제)** → \*\*Integrations(연동)\*\*으로 이동합니다.
2. 목록에서 **토스페이먼츠**를 찾아 **연결/활성화** 상태인지 확인하세요.
3. (선택) 설정 키를 확인하려면 앱의 **설정 페이지**를 열어보세요.
   * **테스트(Test) 탭** — 테스트용 클라이언트 키 / 시크릿 키가 자동으로 채워져 있습니다.
   * **운영(Live) 탭** — 운영 전환 시 라이브 키를 입력하는 곳입니다. (지금은 비워둬도 됩니다.)

***

## 3부. 테스트 모드란?

테스트 모드는 **실제로 돈이 빠져나가지 않는** 가상 결제 환경이에요. 상품 등록부터 결제, 구독, 환불까지 **실제 운영과 똑같은 흐름**을 안전하게 연습할 수 있습니다.

* 결제창은 뜨지만 **실제 카드 승인은 일어나지 않습니다.**
* 테스트 결제 내역은 **토스페이먼츠 테스트 환경**과 하이퍼클래스의 **Payments → Transactions**에서 확인할 수 있어요.
* 운영 전환 전에 **반드시 테스트 모드에서 모든 결제 유형을 한 번씩** 확인하는 것을 권장합니다.

***

## 4부. 다양한 상품 만들어 보기

결제를 테스트하려면 먼저 \*\*상품(Product)\*\*이 필요해요. 하이퍼클래스에서는 크게 세 가지 유형을 만들 수 있습니다.

이동 경로: **Payments(결제) → Products(상품) → + Create Product / Add Product**

### 4-1. 일회성 상품 (One-time)

한 번만 결제되는 상품이에요. (예: 전자책, 1회 컨설팅, 디지털 다운로드)

1. **Add Product** 클릭
2. 상품명 입력 (예: `테스트 전자책`)
3. **가격(Price)** 추가 → 유형을 \*\*One-time(일회성)\*\*으로 선택
4. 금액 입력 → **통화(Currency)를 `KRW`로 지정** ✅ *중요*
5. 저장

> ⚠️ 금액은 **원 단위 정수**로 입력하세요. (예: `1,000원`은 `1000`)

### 4-2. 정기구독 상품 (Recurring / Subscription)

매달·매년 자동으로 갱신 결제되는 상품이에요. (예: 멤버십, 월간 코칭)

1. **Add Product** 클릭
2. 상품명 입력 (예: `프리미엄 멤버십`)
3. **가격(Price)** 추가 → 유형을 \*\*Recurring(정기결제)\*\*으로 선택
4. **결제 주기** 설정 (예: 매월 / Monthly)
5. 금액 입력 → 통화 **`KRW`**
6. (선택) **무료 체험(Trial)** 기간 설정 가능
7. 저장

> 정기구독은 결제 시 **카드 등록(빌링키 발급)** 과정을 거친 뒤 자동 갱신됩니다.

### 4-3. 결제 링크 / 인보이스용 상품

위에서 만든 상품을 **결제 링크**나 **인보이스**에 그대로 붙여 판매할 수 있어요. 별도 상품을 또 만들 필요는 없습니다.

> 💡 **테스트 팁** — 일회성 1개, 정기구독 1개, 이렇게 **최소 2개**의 상품을 만들어 두면 아래의 모든 결제 유형을 한 번에 점검할 수 있어요.

***

## 5부. 테스트 모드로 결제해 보기

상품을 다 만들었다면, 이제 실제로 결제 흐름을 확인해 봅니다. 테스트 모드에서는 돈이 빠져나가지 않으니 마음 편히 진행하세요.

### 5-1. 결제 링크로 일회성 결제 테스트

1. **Payments → Payment Links**에서 **결제 링크 생성**
2. 4-1에서 만든 **일회성 상품**을 선택
3. 생성된 링크를 **새 탭(또는 시크릿 창)에서 열기**
4. 체크아웃 화면에서 결제 수단으로 **토스페이먼츠**가 보이는지 확인
5. 결제 진행 → 토스 결제창에서 테스트 결제 완료
6. 완료 후 **Payments → Transactions**에서 거래가 \*\*결제 완료(Paid)\*\*로 기록됐는지 확인 ✅

### 5-2. 퍼널/주문서로 결제 테스트

1. **Sites → Funnels(퍼널)** 또는 웹사이트에 **Order Form(주문서)** 요소가 있는 페이지를 만들거나 엽니다.
2. 주문서에 만든 상품을 연결합니다.
3. 페이지를 **미리보기/실제 URL**로 열어 체크아웃까지 진행
4. 토스 결제창에서 테스트 결제 완료 → Transactions에서 확인 ✅

### 5-3. 인보이스로 결제 테스트

1. **Payments → Invoices**에서 **새 인보이스 생성**
2. 연락처(고객)와 상품을 추가
3. 인보이스를 **발송하거나 미리보기 링크**로 열어 결제 진행
4. 토스 결제창에서 테스트 결제 완료 → Transactions에서 확인 ✅

### 5-4. 정기구독 결제 테스트

정기구독은 결제 시 **카드 등록(빌링키 발급)** 단계를 거쳐요.

1. 4-2의 **정기구독 상품**을 결제 링크·퍼널·인보이스 중 하나에 연결
2. 체크아웃에서 결제 진행 → **카드 등록창**이 뜹니다
3. 카드 정보 입력 → **본인인증 단계에서 인증번호 `000000` 입력** (아래 안내 참고)
4. 카드 등록 완료 → **Payments → Subscriptions**에서 구독이 **활성(Active)** 상태로 생성됐는지 확인 ✅
5. (무료 체험을 설정했다면) 상태가 **Trialing**으로 표시되고, 체험 종료일이 올바른지 확인

> ⚠️ **테스트 모드에서는 인증번호(SMS)가 발송되지 않아요 — 정상입니다.** 토스페이먼츠 정책상 **테스트 환경에서는 본인인증 문자가 실제로 오지 않습니다.** 문자를 기다리지 마시고, 본인인증창이 뜨면 인증번호 칸에 **`000000`** 을 입력하세요.
>
> * 카드번호는 **앞 6자리만 실제 카드 BIN**이면 되고, 나머지 번호·유효기간·생년월일은 임의로 입력해도 됩니다.
> * 실제 SMS 인증 흐름은 **운영(Live) 모드에서만** 동작합니다. 테스트로는 확인할 수 없어요.

### 5-5. SaaS 모드 지갑(Wallet) 충전 → 통화 주의 ⚠️

SaaS 모드에서 에이전시가 서브계정의 **지갑(Wallet)에 충전**하거나 사용량 기반으로 **리빌링(Rebilling)** 할 때는, 일반 상품 결제와 **통화 기준이 다릅니다.**

* 일반 상품 결제(체크아웃·퍼널·인보이스·구독)는 **원화(KRW)** 기준이에요.
* 반면 **지갑 충전·리빌링 금액은 플랫폼이 항상 미국 달러(USD)로 전달**합니다. 예를 들어 `$10` 충전이면 `10 USD`로 보내요.
* 따라서 지갑 결제는 **USD 금액을 그 시점 환율로 원화로 환산해서** 토스페이먼츠에 청구됩니다.
  * 예) `$10` 충전 시 → 환율 약 1,506원 적용 → 약 **₩15,000**가 실제 결제 금액이 됩니다.
  * 환율 변동에 대비해 여유분을 사전에 안내해 두면 혼란이 없어요.

> 💡 **꼭 기억하세요** — 지갑/리빌링 금액을 볼 때 숫자(예: `10`)는 **달러 기준**입니다. 원화로 그대로 청구되는 게 아니라 **환산된 원화 금액**이 빠져나갑니다. 충전 전에 미리 원화 금액을 계산해 두면 혼란이 없어요.

**테스트 방법**

1. 에이전시 관점에서 특정 서브계정 지갑에 **소액(예: $1)** 충전 시도
2. 토스 테스트 결제창에서 결제 진행
3. **Payments → Transactions**에서 거래 금액이 **환산된 원화**로 기록됐는지 확인 ✅

***

## 6부. 환불 테스트

테스트 결제도 환불 흐름을 확인할 수 있어요.

1. **Payments → Transactions**에서 환불할 거래를 클릭
2. **Refund(환불)** 선택 → 전체 또는 부분 금액 입력
3. 환불 처리 후 거래 상태가 \*\*환불됨(Refunded)\*\*으로 바뀌는지 확인 ✅

***

## 7부. 운영(Live) 전환

테스트가 모두 정상 확인되면 실제 결제로 전환합니다.

1. 토스페이먼츠에서 **가맹점 계약 완료** 및 **라이브 키 발급** (별도 진행)
2. 앱 **설정 페이지 → 운영(Live) 탭**에 라이브 클라이언트 키 / 시크릿 키 입력 후 저장
3. **소액(예: 1,000원) 실결제 + 환불**로 운영 환경을 최종 점검
4. 이상 없으면 실제 판매 시작 🎉

> ⚠️ 라이브 모드는 **실제 카드에서 돈이 빠져나갑니다.** 점검용 결제는 반드시 소액으로 하고, 바로 환불해 확인하세요.

***

## 문제 해결

### "The token in Authorization header is not valid!" 오류가 떠요

이건 앱 문제가 아니라 **하이퍼클래스 로그인 세션이 만료되었거나 꼬인 경우**에 나타나는 메시지예요. 보통 마켓플레이스 탭을 여러 개 열어두었을 때 발생합니다.

**해결 순서**

1. 열려 있는 하이퍼클래스 탭을 **모두 닫기**
2. **로그아웃** 후, 브라우저에서 하이퍼클래스 플랫폼 관련 쿠키/캐시 삭제
3. **새 탭 하나만** 열어 다시 로그인
4. 설치(또는 설정)를 다시 시도

### 구독 결제 중 인증번호(문자)가 안 와요

테스트 모드에서는 **정상입니다.** 토스페이먼츠는 **테스트 환경에서 본인인증 문자(SMS)를 보내지 않습니다.** 문자를 기다리지 마시고, 본인인증창의 인증번호 칸에 **`000000`** 을 입력하세요.

* 카드번호는 앞 6자리만 실제 카드 BIN이면 되고, 나머지·유효기간·생년월일은 임의 값이어도 됩니다.
* 실제 SMS 본인인증은 **운영(Live) 모드에서만** 동작합니다.
* `000000`을 넣어도 등록이 안 되면 그건 결제창 자체 문제일 수 있으니 지원팀에 문의하세요.

### 체크아웃에 토스페이먼츠가 안 보여요

* **Payments → Integrations**에서 토스페이먼츠가 활성화되어 있는지 확인하세요.
* 앱이 정상 설치되었는지(설치 완료 화면을 봤는지) 확인하세요.

### 결제는 됐는데 주문이 "완료"로 안 바뀌어요

* 잠시 후 **Transactions**를 새로고침해 보세요. 토스 결제 후 검증(verify)까지 약간의 시간이 걸릴 수 있어요.
* 통화가 **KRW**로 설정됐는지 다시 확인하세요.

***

## 도움이 필요하신가요?

오른쪽 하단 채팅 위젯으로 문의하시거나, [hyperclass.ai](https://hyperclass.ai)에서 상담을 예약하세요.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyperclass.gitbook.io/hyperclass-docs/undefined/tosspayments-installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.