> 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/documentation/api/iap.md).

# 인앱 결제

## 결제 상태 조회하기

> 생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있어요. 상황에 따라, 승인 응답을 수신하지 못한 경우에도 활용할 수 있어요.\
> \
> \### 비즈니스 오류 코드\
> \
> 아래 오류는 HTTP 200과 \`resultType: FAIL\`로 응답해요.\
> \
> \| errorCode | 설명 |\
> \| --- | --- |\
> \| \`4095\` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\
> \
> \*\*요청 한도\*\*: 앱당 분당 3,000회

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 파트너 API","version":"1.0.0"},"tags":[{"description":"인앱결제와 관련된 요청을 처리하는 API예요.","name":"iap"}],"servers":[{"description":"운영 (간편 로그인·메시지 발송·토스 포인트 지급 등)","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 [서버 API 이용하기](https://appsintoss.gitbook.io/appsintoss-docs/gS3ttrb5Le6IDbEbyixR/documentation/integration/server-api) 문서를 참고하세요.","type":"mutualTLS"}},"schemas":{"GetOrderRequest":{"description":"인앱 결제 주문 상태 조회 요청 본문이에요.","properties":{"orderId":{"description":"조회할 인앱 결제 주문의 ID예요.","type":"string"}},"required":["orderId"]},"TossApiSuccessGetIapOrderPartnerStatusResult":{"description":"성공 응답 봉투예요.","properties":{"resultType":{"description":"처리 결과예요. 성공이면 `SUCCESS`예요.","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/GetIapOrderPartnerStatusResult"}},"required":["resultType","success"],"type":"object"},"GetIapOrderPartnerStatusResult":{"description":"파트너가 조회한 인앱 결제 주문의 상태 정보예요.","properties":{"orderId":{"description":"조회한 주문의 고유 식별자예요. 요청에 사용한 orderId와 같아요.","type":"string"},"reason":{"description":"status 값에 대한 사람이 읽을 수 있는 부연 설명이에요. status에 따라 문구가 달라져요.","type":"string"},"sku":{"description":"주문에 연결된 상품의 SKU예요. 주문 상태를 확정하지 못한 경우(status가 MINIAPP_MISMATCH, NOT_FOUND, ERROR일 때)에는 내려주지 않아요.","type":"string"},"status":{"description":"주문 상태예요. MINIAPP_MISMATCH: 요청한 미니앱의 주문이 아니에요, NOT_FOUND: 주문을 찾을 수 없어요, ORDER_IN_PROGRESS: 주문이 아직 진행 중이에요, PAYMENT_COMPLETED: 결제가 완료됐어요, PURCHASED: 구매가 완료됐어요, FAILED: 구매에 실패했어요, REFUNDED: 주문이 환불됐어요, ERROR: 카탈로그 조회 실패 등으로 정상 범위를 벗어난 상태예요.","enum":["MINIAPP_MISMATCH","NOT_FOUND","ORDER_IN_PROGRESS","PAYMENT_COMPLETED","PURCHASED","FAILED","REFUNDED","ERROR"],"type":"string"},"statusDeterminedAt":{"description":"주문 상태가 마지막으로 확정된 시각이에요. 주문 상태를 확정하지 못한 경우(status가 MINIAPP_MISMATCH, NOT_FOUND, ERROR일 때)에는 내려주지 않아요.","format":"date-time","type":"string"}},"required":["orderId","reason","status"]},"TossApiFail":{"description":"실패 응답 봉투예요. 비즈니스 오류는 HTTP 200으로 응답하니 `resultType`을 반드시 확인하세요.","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"요청 필드 검증에 실패했을 때의 응답이에요.","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"처리 결과예요. `SUCCESS`가 아닌 값은 모두 실패로 처리하세요. 일반적으로 `FAIL`이에요.","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"실패 시 항상 null이에요."}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"오류 상세 정보예요.","properties":{"data":{"description":"오류 부가 정보예요. 요청 한도 초과 시 `retryAfterSeconds`가 담겨요.","properties":{"errorDetails":{"description":"필드별 검증 실패 상세 목록이에요.","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"오류 코드예요. 각 API의 비즈니스 오류 코드 표를 참고하세요.","type":"string"},"errorType":{"description":"내부 오류 분류 값이에요. 오류 구분에는 `errorCode`를 사용하세요.","format":"int32","type":"integer"},"reason":{"description":"사람이 읽을 수 있는 오류 설명이에요.","type":"string"},"title":{"description":"오류 제목이에요. 대부분 null이에요.","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"필드별 검증 실패 상세 목록이에요.","properties":{"field":{"description":"검증에 실패한 필드 이름이에요.","type":"string"},"message":{"description":"검증 실패 사유예요.","type":"string"},"rejectedValue":{"description":"거부된 입력 값이에요."}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/order/get-order-status":{"post":{"description":"생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있어요. 상황에 따라, 승인 응답을 수신하지 못한 경우에도 활용할 수 있어요.\n\n### 비즈니스 오류 코드\n\n아래 오류는 HTTP 200과 `resultType: FAIL`로 응답해요.\n\n| errorCode | 설명 |\n| --- | --- |\n| `4095` | 요청 한도를 초과했어요. 잠시 후 다시 시도해주세요. |\n\n**요청 한도**: 앱당 분당 3,000회","operationId":"getIapOrderStatus","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetOrderRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessGetIapOrderPartnerStatusResult"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessGetIapOrderPartnerStatusResult"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"인앱 결제 상태 조회에 성공했어요"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"요청 본문이 형식에 맞지 않아요. `error.data.errorDetails`에서 필드별 상세를 확인하세요."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요."}},"summary":"결제 상태 조회하기","tags":["iap"]}}}}
```


---

# 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/documentation/api/iap.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.