---
url: https://developers.webzenk.kr/api/iap.md
---
# 결제

| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/iap/verify` | 유저 | 영수증 검증 → 결제 기록 |
| POST | `/v1/iap/consume` | 유저 | 지급 완료 보고 |
| GET | `/v1/iap/unconsumed` | 유저 | 검증됐지만 지급 보고가 없는 결제 — **로그인 직후 호출** |
| GET | `/v1/iap/history` | 유저 | 결제 내역 `?limit=50&before_id=` |

흐름과 상태는 [결제 검증 가이드](/guide/iap)를 먼저 보세요.

## 영수증 검증

POST `/v1/iap/verify`

::: code-group

```json [Google Play]
{ "store": "googleplay", "product_id": "gem_100", "purchase_token": "…",
  "price_micros": 1200000000, "currency": "KRW" }
```

```json [App Store]
{ "store": "appstore", "product_id": "gem_100", "transaction_id": "2000000812345678" }
```

```json [삼성 Instant Plays]
{ "store": "samsung", "product_id": "gem_100", "signed_receipt": "PurchaseItem.signedPurchaseReceipt" }
```

:::

Google Play는 스토어 응답에 가격이 없어서 앱의 표시 가격(`price_micros` = 가격 × 1,000,000, `currency`)을 매출 지표용으로 함께 보냅니다.

```json
{
  "purchase_id": "5012", "store": "googleplay", "product_id": "gem_100", "quantity": 1,
  "status": "verified", "is_sandbox": false, "order_id": "GPA.3312-…",
  "platform_purchase_id": null,
  "purchased_at": 1795055000, "verified_at": 1795055003, "consumed_at": null, "refunded_at": null,
  "already_processed": false
}
```

| `status` | 할 일 |
|---|---|
| `verified` | 지급 → `/v1/iap/consume` |
| `consumed` | 이미 지급 완료 — 스토어 완료 처리만 |
| `pending` | Google 보류 결제 — 지급하지 말고 나중에 다시 verify |

* 같은 영수증을 다시 보내면 같은 `purchase_id`와 `already_processed: true`가 옵니다.
* `platform_purchase_id`: 플랫폼 결제(삼성)에서 지급 후 플랫폼 소진에 쓰는 ID.

## 지급 완료 보고

POST `/v1/iap/consume` — `{ "purchase_ids": ["5012"] }` (최대 50건, 다시 보내도 안전)

```json
{ "items": [ { "purchase_id": "5012", "status": "consumed" } ] }
```

## 미지급 결제

GET `/v1/iap/unconsumed` → `{ "items": [ 결제 기록 … ] }` — `verified`인 건을 지급하고 consume 하세요.

## 오류

| 오류 | 뜻 | 대응 |
|---|---|---|
| `409 PURCHASE_OWNED_BY_OTHER` | 다른 유저가 등록한 영수증 | 지급하지 않음 |
| `422 RECEIPT_INVALID` | 위조·취소·상품 불일치 | 지급하지 않음 |
| `422 RECEIPT_REVOKED` | 환불·취소된 결제 | 지급하지 않음 |
| `503 STORE_UNAVAILABLE` | 스토어 장애 | 스토어 완료 처리 없이 나중에 재시도 |
| `400 PROVIDER_NOT_CONFIGURED` | 이 게임에 스토어 연동 없음 | 운영 담당자 문의 |
| `403 WEB_NOT_SUPPORTED` | 웹에서 Google Play·App Store 검증 | 앱에서만 |
