개발하기

주의하세요

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

BaseURL

https://apps-in-toss-api.toss.im

1. 상품 목록 가져오기

SDK를 통해 연동해 주세요.

콘솔에 등록한 인앱결제 상품 목록을 가져와요.
가져온 상품 목록은 화면에 표시할 때 사용해요.

자세한 내용은 IapProductListItem 페이지를 확인해 주세요.

2. 인앱결제 요청하기

SDK를 통해 연동해 주세요.

인앱결제 결제창을 띄우고, 사용자가 결제를 진행해요.
결제 완료 후 앱인토스 서버가 실제 결제 여부를 검증하며, 구글/애플 영수증까지 확인해요.
만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.

SDK 1.1.3 버전부터는 결제 성공 시 파트너사 상품 지급 로직이 실행돼요
파트너사 상품 지급 로직이 정상적으로 완료되면 콜백(event.type: success)이 전달돼요.
지급 실패 시에는 PRODUCT_NOT_GRANTED_BY_PARTNER 오류 코드가 전달돼요. (토스앱 5.230.0 이상 지원)

자세한 내용은 인앱 결제 문서의 createOneTimePurchaseOrder 를 확인해주세요.

주의하세요

환불 권한은 앱마켓에 있어요.
앱마켓 환불 요청 및 승인 여부는 앱인토스에서 보장할 수 없으므로,테스트는 반드시 소액으로 진행해 주세요.

---

SDK 1.1.3 버전부터는 지급 완료 과정이 추가되었어요.
함수 인터페이스가 변경되어, SDK 업데이트 시 꼭 코드 수정을 해주세요.

3. 주문 복원하기

SDK를 통해 연동해 주세요.

미결 주문을 조회하여 사용자에게 상품을 지급하고, 해당 주문의 상태를 업데이트합니다.

• getPendingOrders

  • 결제는 완료되었지만 상품이 아직 지급되지 않은 주문 목록을 조회해요.
  • 조회된 주문의 orderId를 확인하여 사용자에게 상품을 지급하세요.

• completeProductGrant

  • 대기 중인 주문의 상품 지급을 완료 처리합니다.
  • 사용자에게 상품을 지급한 뒤, completeProductGrant 를 호출하여 지급 상태를 완료로 변경하세요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 undefined를 반환해요.

자세한 내용은 인앱 결제 문서의 getPendingOrders 및 completeProductGrant 를 확인해주세요.

4. 주문 조회하기

결제 및 상품 지급이 완료된 주문, 또는 환불된 주문의 상태를 조회할 수 있어요.
SDK와 API 두 가지 방식 중 상황에 맞게 선택해 사용해 주세요.

1) SDK로 조회하기

getCompletedOrRefundedOrders 는 인앱결제로 구매한 뒤 결제 및 지급이 완료된 주문과 환불된 주문 목록을 조회해요.
결제는 완료되었지만 상품이 지급되지 않은 주문은 조회되지 않아요.

앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 undefined를 반환해요.

자세한 내용은 인앱 결제 문서의 getCompletedOrRefundedOrders 를 확인해주세요.

2) API로 조회하기

API를 통해 서버에서 인앱결제 주문 상태를 직접 조회할 수 있어요.
승인 혹은 환불 응답을 받지 못한 경우에도 사용할 수 있어요.

• Content-type : application/json
• Method : POST
• URL : /api-partner/v1/apps-in-toss/order/get-order-status

참고하세요

결제 상태 조회 API 사용을 위해서는 토스 로그인 연동을 먼저 진행해 주세요.

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
orderId	String	Y	결제 생성 후 취득한 주문번호(uuid v7)

{
    "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0"
}

응답

이름	타입	설명
orderId	String	요청한 주문번호
sku	String	주문한 상품 ID
statusDeterminedAt	String	주문 완료 일시 (yyyy-MM-dd'T'HH:mm:ssZ) status가 REFUNDED일 경우 환불 완료 일시
status	String	주문에 대한 상태 (enum)
reason	String	상태에 대한 설명

status (enum)

상태	설명	상세 설명
PURCHASED	주문 완료	인앱 결제 및 상품 지급이 모두 완료된 상태
PAYMENT_COMPLETED	결제 완료	SDK 1.1.3 이상에서 결제는 완료되었으나 상품 지급이 실패한 상태
FAILED	주문 실패	결제가 실패한 경우
REFUNDED	주문 환불됨	환불 완료된 경우
ORDER_IN_PROGRESS	주문 진행 중	주문이 생성되었지만 결제/지급 처리가 완료되지 않은 경우
NOT_FOUND	주문 없음	해당 주문번호를 찾을 수 없는 경우
MINIAPP_MISMATCH	상품 불일치	주문한 상품이 해당 앱의 상품이 아닌 경우
ERROR	내부 오류	시스템 내부 오류 발생 시

{
    "resultType": "SUCCESS",
    "success": {
        "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0",
        "sku":"ait.0000010000.af647449.3bd55cfd00.0000000475",
        "statusDeterminedAt":"2025-09-12T16:57:12",
        "status": "PAYMENT_COMPLETED",
        "reason": "결제가 완료되었어요."
    }
}

{
    "resultType": "SUCCESS",
    "success": {
        "orderId": "13c9a1ff-2baa-4495-bbfa-0000000000",
        "sku":"ait.0000010000.af647449.00000000000.0000000475",
        "statusDeterminedAt":"2025-09-12T16:57:12",
        "status": "PURCHASED",
        "reason": "완료된 주문이에요."
    }
}

---

샌드박스 테스트

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

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	권장	서버 검증 및 정합성 확인

자주 묻는 질문

샌드박스에서는 실제 등록/승인된 상품이 아니라, "테스트 상품 - 1", "테스트 상품 - 2"와 같은 mock 데이터가 노출돼요.

토스앱 내에서 동작할 때는 승인된 실제 상품 목록이 정상적으로 표시돼요

샌드박스 환경 개선은 10월 말에 제공될 예정이에요.

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

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

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

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

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

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

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

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

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