개발하기

인앱결제는 일회성 결제와 구독결제 두 가지 방식을 지원해요.
상품 유형에 맞는 방식을 선택해 연동해 주세요.

일회성 결제

소모품, 비소모품처럼 한 번 구매로 완료되는 상품에 사용해요.

주요 연동 흐름은 아래와 같아요.

상품 목록 가져오기 (getProductItemList)
결제 요청하기 (createOneTimePurchaseOrder)
미결 주문 복원하기 (getPendingOrders, completeProductGrant)
주문 상태 조회하기 (getCompletedOrRefundedOrders 또는 API)

주의하세요

SDK 1.1.3 버전 이상을 사용해 주세요.
- SDK 1.1.3 버전부터는 상품 지급 완료 과정이 추가되어 함수 인터페이스가 변경되었어요.
SDK 1.2.2 버전부터는 구매 복원 기능이 추가되었어요.
사용자의 기기가 변경되더라도 인앱결제 상품이 지급 유지될 수 있도록 반드시 연동해주세요.
- 네이티브 저장소 기능을 활용해 주세요.
- 토스 로그인 연동과 인앱결제 상태 조회 API를 활용해 주세요.
인앱결제 상태 조회 API 사용을 위해서는 사전에 필히 토스 로그인 연동을 진행해 주세요.

자세한 개발 가이드와 API 레퍼런스는 아래 문서를 확인해 주세요.

구독결제

자동 갱신 구독 상품에 사용해요.
정해진 주기마다 자동으로 결제되며, 취소 전까지 계속 이용할 수 있어요.

주요 연동 흐름은 아래와 같아요.

구독 상품 목록 가져오기
구독 결제 요청하기
구독 상태 조회하기

자세한 개발 가이드와 API 레퍼런스는 아래 문서를 확인해 주세요.

샌드박스 테스트

출시 전에는 반드시 샌드박스 앱 환경에서 인앱결제가 정상적으로 동작하는지 테스트해 주세요.
샌드박스에서는 실제 결제(과금)는 발생하지 않으며, 모든 결제가 테스트 시나리오로 처리돼요.

참고하세요

현재 샌드박스 테스트는 일회성 결제만 지원해요.
구독결제의 샌드박스 테스트는 현재 지원하지 않아요.

1. 샌드박스에서 상품 목록 조회 시 동작

샌드박스 앱에서 getProductItemList() 를 호출하면 콘솔에 등록된 인앱결제 상품 중 노출 상태가 ON인 상품만 조회돼요.

실제 콘솔에 등록한 상품 목록이 그대로 내려와요.
콘솔에서 노출 OFF인 상품은 샌드박스 앱에서도 보이지 않아요.

2. 필수 테스트 시나리오

샌드박스에서는 아래 3가지 테스트를 반드시 각각 수행해야 해요.
각 시나리오마다 앱이 올바르게 대응하는지 확인해 주세요.

① 결제 성공 테스트

성공 콜백(event.type: success)이 정상적으로 전달되는지 확인해요.
실제 결제(과금)는 발생하지 않아요.
SDK 1.1.3 이상에서는 파트너사의 상품 지급 로직까지 성공해야 최종 성공으로 처리돼요.

확인해야 할 항목

orderId, amount 등 event.data 정상 반환 여부
내부 지급 로직 정상 동작 여부
지급 완료 후 화면/UI 업데이트

② 결제 성공(서버 실패) 테스트

결제는 성공했지만 파트너 서버의 지급 로직이 실패하는 경우를 반드시 테스트해야 해요.

앱은 다음 처리를 지원해야 해요:
- 사용자에게 지급 실패 안내
- 앱 재실행 시 getPendingOrders 로 미결 주문 복원
- 지급 완료 후 completeProductGrant 호출

실서비스에서도 충분히 발생 가능한 시나리오이므로 반드시 테스트해야 해요.

③ 에러 테스트

결제 도중 오류가 발생하는 다양한 상황을 미리 시뮬레이션하세요.

테스트해야 할 대표 상황

네트워크 오류
사용자가 결제 취소
내부 오류
파트너사 상품 지급 실패

3. 테스트 체크리스트

테스트 항목	필수	확인 포인트
상품 목록 노출	✔️	콘솔에서 등록한 상품이 정상적으로 내려오는지
결제 성공 테스트	✔️	`event.data` 처리, 지급 로직, UI 처리
결제 성공 + 서버 지급 실패 (주문 복원)	✔️	미결 주문 복원 및 재지급 처리
에러 테스트	✔️	에러 UI, 오류 처리, 재시도 흐름
주문 상태 조회 API	권장	서버 검증 및 정합성 확인

자주 묻는 질문

주의하세요

SDK 1.1.3 버전 이상을 사용해주세요.
- SDK 1.1.3 버전부터는 상품 지급 완료 과정이 추가되어 함수 인터페이스가 변경되었어요.
SDK 1.2.2 버전부터는 구매 복원 기능이 추가되었어요.
사용자의 기기가 변경되더라도 인앱결제 상품이 지급 유지될 수 있도록 반드시 연동해주세요.
- 네이티브 저장소 기능을 활용해 주세요.
- 토스 로그인 연동과 인앱결제 상태 조회 API를 활용해 주세요.
인앱결제 상태 조회 API 사용을 위해서는 사전에 필히 토스 로그인 연동을 진행해 주세요.

SDK 1.0.3 버전 이상에서는 승인/실패를 포함한 모든 주문 건에 대해 "orderId" 프로퍼티가 전달됩니다.

단, 네트워크 오류 등으로 "orderId" 가 발급되기 전에 오류가 발생할 경우, "orderId"가 내려오지 않을 수 있어요.

SDK 1.1.3 버전 이상에서 "errorCode"가 정상적으로 내려오도록 수정되었어요.

최신 SDK로 업데이트해 주세요.

SDK 1.2.2 버전 이상에서 주문 복원 함수를 사용하여 연동해주세요.

ggetPendingOrders 함수를 사용해 미결 주문을 조회하고, 조회된 주문의 orderId를 사용해 사용자에게 상품을 지급하세요.

ompleteProductGrant 함수를 호출해 지급 상태를 완료로 변경하세요.

토스앱 5.229.1 버전 이상에서 사용자가 인앱 결제 구매내역을 확인할 수 있어요.

구글 결제 건 : "환불받기" 버튼을 눌러 사유 선택 후 환불 요청 가능
파트너사 : 콘솔의 환불 내역에서 환불 요청을 승인 또는 반려 가능
결과 안내 : 환불 처리 결과는 사용자에게 푸시 알림으로 전달됨

개발하기

일회성 결제

일회성 결제 레퍼런스 >

구독결제

구독결제 레퍼런스 >