Appearance

개발하기 ​

주의하세요

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


BaseURL

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

1. 상품 목록 가져오기 ​

SDK를 통해 연동해 주세요.

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

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

참고하세요

샌드박스에서는 실제 등록/승인된 상품이 아닌, 테스트 상품 - 1, 테스트 상품 - 2 와 같은 mock 데이터가 노출돼요.
토스앱 내에서 동작할 때는 승인된 실제 상품 목록이 정상적으로 보여져요.

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 두 가지 방식 중 상황에 맞게 선택해 사용해 주세요.

SDK로 조회하기 ​

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

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

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

API로 조회하기 ​

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

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

참고하세요

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

요청 헤더

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

요청 파라미터

이름타입필수설명
orderIdStringY결제 생성 후 취득한 주문번호(uuid v7)
json
{
    "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0"
}

응답

이름타입설명
orderIdString요청한 주문번호
skuString주문한 상품 ID
statusDeterminedAtString주문 완료 일시 (yyyy-MM-dd'T'HH:mm:ssZ)
statusString주문에 대한 상태 (enum)
reasonString상태에 대한 설명

status (enum)

상태설명상세 설명
PAYMENT_COMPLETED결제 및 상품 지급 완료SDK 1.1.3 이상에서 인앱 결제와 상품 지급이 모두 완료된 경우
PURCHASED구매 완료SDK 1.1.2 이하에서 인앱 결제가 성공한 경우
ORDER_IN_PROGRESS주문 진행 중주문이 생성되었지만 결제/지급 처리가 완료되지 않은 경우
FAILED주문 실패결제 실패 또는 상품 지급 실패
REFUNDED주문 환불됨환불 완료된 경우
NOT_FOUND주문 없음해당 주문번호를 찾을 수 없는 경우
MINIAPP_MISMATCH상품 불일치주문한 상품이 해당 앱의 상품이 아닌 경우
ERROR내부 오류시스템 내부 상태 이상
json
{
    "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": "결제가 완료되었어요."
    }
}

자주 묻는 질문 ​

샌드박스에서는 실제 등록/승인된 상품이 아니라, "테스트 상품 - 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 버전 이상에서 사용자가 인앱 결제 구매내역을 확인할 수 있어요.

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