변경 이력

2026-10

개발자 문서의 외부 연동 계약을 2026-10 기준으로 개편했어요.
실제 반영일은 BE·FE·Docs·SDK 동시 배포일로 기록하고, 날짜는 추후 공지해요.

계약 변경과 대체 수단

아래 항목은 새 외부 연동 계약에서 사용할 수 없어요.
대체 기능은 새 경로와 권한을 사용해 연결하세요.

폐지 항목	대체 수단
목록 응답	목록은 `{ data, total, page, limit }`를 반환해요. `page` 기본값은 1, `limit` 기본값은 20이고 최대 100이에요. `sort`나 `order`를 보내면 400으로 거절돼요.
선택으로 보내던 `Idempotency-Key`	앱 라이선스 API를 제외한 모든 v1 `POST`에 1~255자의 `Idempotency-Key`를 필수로 보내요. 누락하면 `400 VALIDATION_FAILED`예요.
`pk_live_` · `pk_test_` 형식의 키와 브라우저용 키	서버 전용 `pyr_live_…` · `pyr_test_…` API 키를 발급하고 `Authorization: Bearer …`로 인증해요.
`X-Api-Key` 인증 헤더	`Authorization: Bearer pyr_live_…` 또는 `Authorization: Bearer pyr_test_…`를 사용해요.
`linkId` 기반 Checkout Session 본문	`POST /v1/checkout/sessions`에 `productId`를 보내요. 구독이면 `planId`와 `interval`을 모두 보내요. `interval`은 `monthly` 또는 `yearly`이고, `planId`는 `GET /v1/products`의 `pricing.plans[].id`예요.
`POST /v1/orders/refund`	`POST /v1/orders/:id/refund`로 주문 id를 경로에 넣어요. Refunds를 확인해요.
`POST /v1/subscriptions/cancel` · `POST /v1/subscriptions/cancel-preview`	`POST /v1/subscriptions/:id/cancel`로 해지하고 `GET /v1/subscriptions/:id/cancel-preview`로 미리보기 해요. Subscriptions를 확인해요.
본문에 요청 id를 넣는 `POST /v1/refund-requests/approve` · `/reject` · `/hold`	`POST /v1/refund-requests/:id/approve`, `/:id/reject`, `/:id/hold`를 사용해요. Refunds를 확인해요.
API 키로 호출하는 라이선스 `verify` · `activate` · `deactivate`	앱은 라이선스 키로 인증하는 라이선스 앱 API를 호출해요. 서버 조회에는 `licenses:read` 권한을 사용해요.
`POST /v1/public/orders/:orderId/license`	앱의 라이선스 키 확인은 라이선스 앱 API를 사용하고, 구매자 전달은 상품의 라이선스 발급 방식을 설정해요.
라이선스 전용 시크릿과 외부 연동 통합 시크릿	REST API에는 `pyr_…` API 키를, 웹훅에는 엔드포인트별 `whsec_…` 시크릿을 사용해요. 앱 라이선스 API는 라이선스 키로 인증해요.
`orders:write` · `licenses:write` 권한	주문 조회는 `orders:read`, 환불 작업은 `refunds:read` · `refunds:write`를 사용해요. 앱 라이선스 API는 라이선스 키로 호출하고, 내 서버 발급은 `license.issue` 웹훅으로 처리해요.
`subscription.renewed` · `subscription.canceled` 이벤트	`subscription.renewed` 대체: 갱신 결제 성공은 `order.paid`의 `data.subscriptionEvent=renewal`로, 기간 갱신은 `subscription.updated`의 `data.change.kind=period_renewed`로 확인해요. `subscription.canceled` 대체: 해지 예약은 `subscription.updated`의 `data.change.kind=cancel_scheduled`로, 실제 종료는 `subscription.ended`의 `endReason`으로 확인해요.
`/developers/guide` · `/developers/api-keys/create` · `/developers/rest-api/authentication` · `/developers/licensing/integration-types` · `/developers/licensing/verify-api` 문서 경로	흐름은 퀵스타트, 인증은 인증과 API 키, 앱 검증은 라이선스 앱 API, 서버 발급은 내 서버에서 발급으로 옮겼어요.

API 키 계약 확정

API 키 접두어 뒤는 base62 38자이며 본문 32자와 체크섬 6자로 구성돼요. 예: pyr_test_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZab.
401 API_KEY_INVALID은 인증 헤더 누락·형식 오류, 체크섬 불일치, 미등록 키, 회전 유예 만료를 구분하지 않고 같은 코드로 응답해요.
403 API_KEY_IP_NOT_ALLOWED는 허용되지 않은 IP를, 403 API_KEY_SCOPE_MISSING은 부족한 권한을 나타내요. 후자의 details.required는 필요한 권한 문자열 배열이에요.
API 키별 한도는 분당 300회예요. 초과하면 429 RATE_LIMITED와 초 단위 Retry-After 헤더를 반환해요.
키 회전은 기본 24시간 유예이며 즉시 폐기도 선택할 수 있어요. 유예 중인 옛 키 응답의 Payri-Key-Deprecated 값은 만료 시각 ISO 8601이에요.
API 키 인증이 필요한 /v1 REST API는 서버 전용이에요. 브라우저에서 호출할 수 있는 API는 키 없는 라이선스 앱 API의 verify, activate, deactivate뿐이에요.

문서 정정

SDK: npm @payri/sdk 1.0.0을 제공하고, @payri/nest는 폐기(deprecate)해요.
order.paid는 최초 결제뿐 아니라 갱신 결제와 차액 결제를 포함한 모든 결제 성공 이벤트예요. 구독과 관련한 결제 종류는 data.subscriptionEvent로 구분해요.
API 경로 표기에서 중복된 /v1/v1을 제거했어요. Base URL은 https://api.payri.kr이고 경로는 /v1/…예요.
웹훅 성공 응답 기준을 200에서 모든 2xx로 바로잡았어요.
상품 응답에 refundPolicy.refundDays 필드를 추가했어요.
라이선스 앱 API 응답은 mode를 포함하고, Test·Live 키가 같은 엔드포인트를 사용해요.
웹훅 수신 URL은 공개 http·https 주소만 등록하고 내부·특수 주소에는 보내지 않아요.