화면 모드
결제
| 경로 | 인증 | 설명 | |
|---|---|---|---|
| POST | /v1/iap/verify | 유저 | 영수증 검증 → 결제 기록 |
| POST | /v1/iap/consume | 유저 | 지급 완료 보고 |
| GET | /v1/iap/unconsumed | 유저 | 검증됐지만 지급 보고가 없는 결제 — 로그인 직후 호출 |
| GET | /v1/iap/history | 유저 | 결제 내역 ?limit=50&before_id= |
흐름과 상태는 결제 검증 가이드를 먼저 보세요.
영수증 검증
POST/v1/iap/verifyjson
{ "store": "googleplay", "product_id": "gem_100", "purchase_token": "…",
"price_micros": 1200000000, "currency": "KRW" }json
{ "store": "appstore", "product_id": "gem_100", "transaction_id": "2000000812345678" }json
{ "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 검증 | 앱에서만 |