> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-payment.md).

# 인앱 결제

앱인토스의 인앱 결제를 연동해 디지털 상품과 권한, 콘텐츠를 손쉽게 판매해 보세요. 구매 흐름을 짧게 만들면 사용자는 더 쉽게 결제하고, 매출은 빠르게 늘릴 수 있어요.

### 인앱 결제란

인앱 결제는 앱 안에서 유료 상품을 바로 구매할 수 있는 결제 방식이에요. 사용자는 앱을 떠나지 않고도 필요한 기능이나 아이템, 콘텐츠를 결제할 수 있어요. 인앱 결제 상품은 소모성 아이템과 비소모성 아이템으로 나뉘어요.

* **소모성 아이템:** 사용하면 사라지는 상품이에요. 다시 쓰려면 다시 구매해야 해요. (예: 게임 아이템, 코인, 힌트 이용권)
* **비소모성 아이템:** 한 번 구매하면 계속 쓸 수 있는 상품이에요. (예: 프리미엄 기능 해제, 광고 제거, 특정 콘텐츠 이용 권한)

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FQ8oGeiB5LAaJQsBNJloN%2Fimage.png?alt=media&#x26;token=96af789b-aebd-417f-874b-d0f38d4768cd" alt=""><figcaption></figcaption></figure>

***

### 인앱 결제의 좋은 점

* 사용자가 앱을 벗어나지 않고 바로 결제할 수 있어, 결제 중 이탈을 줄일 수 있어요.
* 앱 출시 초기부터 유료 아이템이나 구독 상품을 판매해 바로 수익을 만들 수 있어요.
* 소모성 아이템과 비소모성 아이템을 함께 구성해 다양한 결제 모델을 만들 수 있어요.
* 사용 목적에 맞는 상품을 제공해 매출을 더 크게 키울 수 있어요.

{% hint style="info" %}
**참고해 주세요**

* 인앱 결제 환불은 Apple과 Google의 정책을 따라요.
* 판매가는 공급가에 부가가치세(VAT)가 더해진 금액이에요.
* 결제가 진행되는 동안 앱 안의 기능(음악·영상 재생 등)은 잠시 멈추고, 결제가 끝나면 자동으로 다시 이어지도록 처리해 주세요.
  {% endhint %}

***

### 콘솔에서 설정하기

#### 1) 사업자 정보 등록하기

인앱 결제를 연동하려면 먼저 사업자 정보를 등록해야 해요. 사업자 정보가 등록되어 있어야 다음 단계인 약관 동의와 정산 정보 입력을 진행할 수 있어요. 등록 방법은 다음 [가이드](https://developers-apps-in-toss.toss.im/guide/operation/register-business)를 참고해 주세요.

#### 2) 정산 정보 입력하기

인앱 결제 수익을 정산받으려면 [정산 정보를 등록](https://developers-apps-in-toss.toss.im/guide/settlement)해야 해요. 워크스페이스의 '정보' 탭에서 정산 정보를 입력한 뒤 검토를 요청해 주세요. 검토에는 영업일 기준 평균 2\~3일이 걸려요.

#### 3) 인앱 상품 등록하기

상품 정보를 정확하게 입력하면 사용자가 구매 내용을 명확히 이해할 수 있고, 운영 중 분쟁이나 환불 이슈를 줄일 수 있어요.

등록할 수 있는 상품 수에는 제한이 있어요. 게임 미니앱은 최대 80개, 비게임 미니앱은 최대 30개예요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FWEVxGawwAyHNKpTtQjK6%2Fimage.png?alt=media&#x26;token=d04f46a5-d324-4cb4-9551-8eeab755b74d" alt=""><figcaption></figcaption></figure>

**상품 유형**

상품의 사용 방식에 맞게 유형을 선택해 주세요. 현금성·환가성 상품이나 토스 포인트와 결합해 제공하는 상품은 판매할 수 없어요.

* 소모품: 사용하면 소진되는 상품이에요. 다시 쓰려면 재구매해야 해요. (예: 게임 아이템, 내부 재화 충전, 1회 이용권)
* 비소모품: 한 번 구매하면 계속 쓸 수 있는 상품이에요. (예: 광고 제거, 소장형 콘텐츠)
* 자동 갱신 구독: 정해진 주기마다 자동으로 결제되고, 취소 전까지 계속 이용할 수 있어요. (예: 월간 멤버십, 정기 콘텐츠 구독)

**상품명**

* 상품명은 사용자가 받는 기능과 조건을 그대로 드러내야 해요.
* 실제 제공 내용과 일치하게 작성해 주세요.
* 과장하거나 오해를 부르는 표현은 쓸 수 없어요. 예를 들어 이용 기간이 정해져 있는데 "무제한"이라고 쓰면 안 돼요.

**상품 이미지**

* 사용자가 상품을 직관적으로 이해할 수 있게 구성해 주세요.
* "30일 이용권", "100코인"처럼 식별에 필요한 텍스트를 넣을 수 있어요.
* 이벤트성 문구를 넣는다면, 반드시 이벤트 기간을 함께 표시해 주세요.
* 해상도는 1024 × 1024px로 등록해야 해요.
* 저작권 문제가 없는 이미지만 써야 하고, 이미지는 파트너사가 직접 확보해야 해요.
* 선정적이거나 폭력적이거나 불쾌감을 줄 수 있는 이미지는 쓸 수 없어요.

**공급가**

* 공급가는 부가가치세(VAT)가 빠진 금액이에요.
* 최소 400원부터 최대 1,400,000원까지 설정할 수 있어요.
* 10원 단위로만 입력할 수 있어요.
* 공급가를 입력하면 판매가는 자동으로 계산돼요. 판매가를 먼저 입력해 공급가를 자동 계산하는 기능은 지금은 지원하지 않아요.

**판매가**

판매가는 사용자가 실제로 결제하는 최종 금액이에요. 공급가에 부가가치세가 더해진 금액으로 자동 설정돼요.

**소모품 할인**

소모품 유형의 인앱 상품에는 할인 혜택을 설정할 수 있어요. 콘솔의 인앱 상품 목록에서 노출 중인 소모품 상품에 표시되는 '+ 할인' 버튼을 눌러 할인 정보를 등록해 주세요. 할인을 설정할 때는 할인된 공급가, 할인 기간, 할인 대상을 입력해요. 할인 설정을 완료한 뒤에는 수정할 수 없어요.

할인 대상은 세 가지예요.

* 전체 사용자: 결제 이력과 관계없이 할인을 적용해요.
* 결제 이력이 없는 사용자: 한 번도 구매한 적 없는 사용자에게 할인을 적용해요.
* 결제 이력이 있는 사용자: 구매 이력이 있는 사용자에게 할인을 적용해요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FOfV0TEWiEjCUpbiqujWn%2F%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8B%E1%85%A2%E1%86%B8%E1%84%89%E1%85%A1%E1%86%BC%E1%84%91%E1%85%AE%E1%86%B7%20%E1%84%85%E1%85%B5%E1%84%89%E1%85%B3%E1%84%90%E1%85%B3%2047%20(1).png?alt=media&#x26;token=dade1730-dd18-49ff-bc40-064f62fd7f1d" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FqV00eI3NVlVy64ecTTgz%2Fimage.png?alt=media&#x26;token=662c0467-46ed-4e74-a861-59e26b7cc855" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**참고해 주세요**

* 할인된 상품을 이미 구매한 사용자는 할인 대상에 해당해도 추가 할인을 받을 수 없어요.
* 환불된 결제도 구매 이력에 포함돼요.
* 할인 상품도 기존 인앱 결제 SDK로 구매할 수 있어요. 별도 SDK 연동 변경은 필요하지 않아요.
  {% endhint %}

**자동 갱신 구독 전용 설정**

자동 갱신 구독 유형을 선택하면 아래 항목을 추가로 설정할 수 있어요.

* **자동 갱신 주기:** 결제가 반복되는 간격을 선택해요. (매주: 7일마다 / 매월: 30일마다 / 매년: 365일마다 자동 결제)
* **무료 체험:** 일정 기간 결제 없이 정기 결제 혜택을 이용할 수 있어요. 무료 체험이 끝나면 자동으로 유료 결제가 진행돼요. 기간은 3일·1주·2주·1개월 중 선택해요.
* **신규 구독 할인:** 처음 정기 결제를 시작하는 사용자에게 일정 기간 할인된 가격으로 제공해요. 할인 기간과 할인 공급가를 입력하면 할인 판매가가 자동으로 계산돼요.
* **재구독 할인:** 이전에 구독을 해지한 사용자가 재구독할 때 할인된 가격으로 제공해요. 할인 기간과 할인 공급가를 입력하면 할인 판매가가 자동으로 계산돼요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F9UxqVhINyp7xoeoQQqS6%2FColumns%2091.png?alt=media&#x26;token=f2487a89-db2c-45a1-b6ff-37f8996388f1" alt=""><figcaption></figcaption></figure>

#### 4) 결제 알림 URL 등록하기

구독 갱신·해지 등 결제 상태가 바뀔 때 알림을 받을 URL을 등록할 수 있어요. URL을 등록하면 상태가 바뀔 때 그 URL로 HTTP 요청이 전달돼요.

* 결제 알림 URL: 결제 상태 변경 알림을 받을 서버 URL을 입력해 주세요.
* Basic Auth 헤더: 선택적으로 Basic Auth 헤더 값을 입력할 수 있어요. 입력하면 알림 요청의 HTTP 헤더에 아래처럼 포함돼요.

{% code collapsedlinecount="10" %}

```
Authorization: Basic {Basic Auth 헤더 값}
```

{% endcode %}

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FamRYTT5AmyJ4ArNLDALG%2F%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8B%E1%85%A2%E1%86%B8%E1%84%89%E1%85%A1%E1%86%BC%E1%84%91%E1%85%AE%E1%86%B7%20%E1%84%85%E1%85%B5%E1%84%89%E1%85%B3%E1%84%90%E1%85%B3%2042.png?alt=media&#x26;token=7b516918-5938-4a6a-93de-c9552f0a61c4" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2Fvf2Jq5yD4z1wdVaegJDN%2F%F0%9F%9F%A3%20Desktop_Modal%2038.png?alt=media&#x26;token=99491d6f-8dc9-4970-8748-0ffe4816640d" alt=""><figcaption></figcaption></figure>

#### 5) 결제·환불 내역 확인하기

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FegO0ESdAx6p9IK58ui1G%2F%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8B%E1%85%A2%E1%86%B8%E1%84%89%E1%85%A1%E1%86%BC%E1%84%91%E1%85%AE%E1%86%B7%20%E1%84%85%E1%85%B5%E1%84%89%E1%85%B3%E1%84%90%E1%85%B3%2030.png?alt=media&#x26;token=07e12b23-0f58-433e-866c-021becf9e8cd" alt=""><figcaption></figcaption></figure>

**결제 내역**

사용자가 미니앱에서 결제한 상품 내역이에요.

* 지급완료: 사용자에게 구매 상품까지 모두 제공됐다는 뜻이에요.
* 결제 완료: 결제는 됐지만 구매 상품이 아직 지급되지 않은 상태예요.

**환불 내역**

사용자가 환불을 요청한 내역이에요. 환불 요청 사유를 확인하고 요청을 반려하거나 승인할 수 있어요. 인앱 결제로 결제한 사용자는 토스 앱에서 '환불받기' 버튼을 눌러 환불을 요청할 수 있어요.

환불 상태는 아래와 같아요.

* 환불 요청 승인: 파트너사가 환불 요청을 승인한 내역이에요. 승인하면 앱마켓에 심사가 요청돼요.
* 환불 요청 반려: 파트너사가 환불 요청을 반려하거나, 앱마켓에서 환불을 반려한 내역이에요.
* 환불 완료: 앱마켓에서 환불이 완료된 내역이에요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F4uYR0JGRfVulaRzaYxAp%2F%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8B%E1%85%A2%E1%86%B8%E1%84%89%E1%85%A1%E1%86%BC%E1%84%91%E1%85%AE%E1%86%B7%20%E1%84%85%E1%85%B5%E1%84%89%E1%85%B3%E1%84%90%E1%85%B3%2040.png?alt=media&#x26;token=1120d658-fbd9-453f-9062-881ffffe4766" alt=""><figcaption></figcaption></figure>

**마켓별 환불 정책**

인앱 결제 환불은 사용자의 운영체제(OS)와 마켓 정책에 따라 처리 방식이 달라요.

<details>

<summary>Android</summary>

* 사용자는 토스 앱에서 직접 환불을 요청해요.
* 파트너사는 앱인토스 콘솔의 '환불 내역' 메뉴에서 요청 건을 확인하고 승인이나 반려를 처리할 수 있어요.
* 단, 최종 승인·거절 여부는 Google Play가 결정해요.
* 환불 처리 결과는 사용자에게 푸시 알림으로 발송되고, 사용자는 주문 상세 화면에서도 확인할 수 있어요. 파트너사나 Google Play가 환불을 거절한 경우에도 똑같이 알림이 발송돼요.
* 파트너사는 내부 정책과 Google Play 정책을 함께 검토한 뒤 환불 요청을 처리해 주세요.

</details>

<details>

<summary>iOS</summary>

* iOS 사용자의 환불은 Apple이 전적으로 관리해요. 모든 환불을 Apple이 직접 판단하고 승인해요.
* 파트너사는 환불을 승인하거나 거절할 수 없어요. Apple이 환불 요청 기능을 외부에 제공하지 않기 때문이에요.
* 파트너사는 결제 상태 조회 API로 상태만 확인할 수 있어요.

</details>

***

### 개발 연동하기 <a href="#develop" id="develop"></a>

콘솔에서 인앱 상품을 등록한 뒤에는 미니앱에서 상품 목록 조회, 결제 요청, 상품 지급, 미결 주문 복구 흐름을 함께 연동해 주세요.&#x20;

3.x SDK 레퍼런스는 함수별로 나뉘어 있으므로, 아래 흐름을 먼저 이해한 다음 각 단계의 SDK 문서를 확인하는 것을 권장해요.

{% hint style="info" %}
**먼저 확인해 주세요**

아래 흐름은 소모품과 비소모품처럼 한 번 구매로 완료되는 일회성 인앱 상품 기준이에요. \
자동 갱신 구독은 콘솔의 결제 알림 URL과 결제 상태 변경 처리를 함께 연동해 주세요.
{% endhint %}

#### 정상 결제 흐름

1. **상품 목록을 가져와요.**

   상품 목록 화면에 진입하면 [`IAP.getProductItemList`](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/iap/iap.getproductitemlist)를 호출해 콘솔에 등록된 인앱 상품을 가져와요.\
   응답의 `sku`, 상품명, 가격, 이미지 정보를 사용해 구매 가능한 상품 목록을 보여주세요.
2. **사용자가 선택한 상품으로 결제를 요청해요.**

   구매 버튼을 누르면 선택한 상품의 `sku`로 [`IAP.createOneTimePurchaseOrder`](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/iap/iap.createonetimepurchaseorder)를 호출해요. \
   이때 `options.processProductGrant` 콜백을 반드시 함께 전달해야 해요.
3. **결제가 완료되면 상품을 지급해요.**

   결제가 완료되고 주문이 만들어지면 SDK가 `processProductGrant` 콜백을 호출해요. \
   이 콜백 안에서 `orderId`를 기준으로 파트너 서버나 앱 저장소에 구매 사실을 기록하고, 사용자에게 상품·권한·콘텐츠를 지급해 주세요. 지급 처리가 끝까지 성공했을 때만 `true`를 반환해요.

   `false`를 반환하거나 콜백이 정상적으로 끝나지 않으면 주문이 미결 상태로 남을 수 있어요. 이 경우 사용자가 결제했지만 상품을 받지 못한 상태가 되므로, 아래 복구 흐름을 반드시 함께 구현해야 해요.
4. **성공 이벤트를 처리하고 리소스를 정리해요.**

   결제와 상품 지급이 정상적으로 끝나면 `onEvent`가 `type: "success"`로 호출돼요. \
   결제 완료 화면을 보여주거나 사용자 보유 상품 정보를 새로고침해 주세요. 결제 흐름이 끝나면 `createOneTimePurchaseOrder`가 반환한 cleanup 함수를 호출해 리소스를 해제해 주세요.

#### 미결 주문 복구 흐름

앱 종료, 네트워크 오류, 서버 오류 등으로 상품 지급이 끝나지 못하면 주문이 미결 상태로 남을 수 있어요. \
사용자가 결제했는데 상품을 받지 못하는 상황을 막기 위해 앱 시작 시점이나 결제 화면 진입 시점에 미결 주문을 확인해 주세요.

1. [`IAP.getPendingOrders`](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/iap/iap.getpendingorders)로 결제는 완료됐지만 상품 지급이 끝나지 않은 주문을 조회해요.
2. 각 주문의 `orderId`와 `sku`를 기준으로 상품·권한·콘텐츠를 다시 지급해요. 이미 지급한 주문인지 확인해 중복 지급되지 않도록 처리해 주세요.
3. 지급 처리가 성공하면 [`IAP.completeProductGrant`](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/iap/iap.completeproductgrant)를 호출해 상품 지급 완료 상태로 변경해요. 지급에 실패했다면 완료 처리하지 말고, 다음 복구 시점에 다시 처리할 수 있게 남겨두세요.

#### 주문 상태와 환불 확인하기

상품 지급이 끝난 주문이나 환불된 주문 이력을 앱에서 확인해야 한다면 [`IAP.getCompletedOrRefundedOrders`](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/iap/iap.getcompletedorrefundedorders)를 사용해요. 이 함수는 미결 주문 복구용이 아니라, 이미 완료됐거나 환불된 주문 내역을 확인할 때 사용해 주세요.

서버에서 특정 주문의 최신 상태를 검증해야 한다면 [결제 상태 조회 API](https://developers-apps-in-toss.toss.im/api/iap)를 호출할 수 있어요. \
이 API는 파트너 서버에서 앱인토스 서버로 호출하는 서버 간 통신이므로 mTLS 인증서 설정이 필요해요.

{% hint style="info" %}
**상품 지급 처리 기준**

상품 지급은 사용자에게 실제 혜택을 제공하고, 그 결과를 파트너 시스템에 저장하는 단계예요. 예를 들어 코인을 충전하거나, 광고 제거 권한을 부여하거나, 유료 콘텐츠 접근 권한을 활성화하는 처리를 말해요. 이 처리가 성공한 뒤에만 지급 성공으로 판단해 주세요.
{% endhint %}

***

### 성과 확인하기

개발과 연동을 마친 인앱 결제의 성과 지표를 한 화면에서 확인할 수 있어요. 매출 흐름과 사용자의 결제 행동을 함께 분석해 상품 구성과 운영 전략을 개선해 보세요. 데이터는 D+1 오전 8시 이후부터 순차적으로 업데이트돼요.

* 매출 지표: 총 결제 금액, 총 매출, 결제자당 평균 매출, 결제 사용자당 매출
* 사용자 지표: 활성 사용자 수, 결제 사용자 수, 신규 결제 사용자 수, 재결제 사용자 수, 결제율, 최종 전환율

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FPcVTPy6VJlt4t51tJBUG%2Fimage.png?alt=media&#x26;token=d172209b-2352-4dc6-909b-e6cacd2eb1a3" alt=""><figcaption></figcaption></figure>

***

### 자주 묻는 질문

<details>

<summary>인앱 결제 수수료는 어떻게 되나요?</summary>

인앱 결제 수수료는 앱마켓 수수료 15% (향후 매출에 따라 변동 가능) + 토스 수수료 5%가 적용돼요.

자세한 내용은 정산 이해하기 > 인앱 결제 항목을 확인해 주세요.

</details>

<details>

<summary>인앱 결제 테스트를 하고 싶어요.</summary>

인앱 결제는 샌드박스에서 테스트할 수 있어요. 가이드를 확인해 주세요.

</details>

<details>

<summary>사용자가 환불을 희망할 경우 어떻게 해야 하나요?</summary>

iOS 사용자의 경우 애플 고객센터로 안내해 주세요. (애플에 모든 권한이 있어요.)

안드로이드 사용자의 경우 가이드처럼 토스 앱 내에서 환불 신청을 할 수 있게 안내해 주세요.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/guide/monetization/in-app-payment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.