SDK
REST API를 직접 호출하지 않고도 페이리를 연동할 수 있게 공식 SDK를 제공해요.
API 호출, 웹훅 서명 검증, 에러 처리를 언어별 관용구에 맞게 감쌌어요.
패키지
| 패키지 | 설치 | 설명 |
|---|---|---|
@payri/sdk | npm install @payri/sdk | JS/TS 코어 SDK. 서버·브라우저·엣지 런타임에서 동작하고 의존성이 없어요. |
@payri/nest | npm install @payri/nest @payri/sdk | NestJS 통합. 모듈·서비스 주입과 웹훅 가드를 제공해요. |
payri | pip install payri | Python SDK. 동기·비동기 클라이언트를 모두 제공하고 런타임 의존성은 httpx 하나뿐이에요. |
소스는 GitHub에 공개돼 있어요: PayRi-KR/sdk-js · PayRi-KR/sdk-python
구조
서버에서는 API 키로 인증하는 클라이언트를, 브라우저에서는 키가 필요 없는 공개 클라이언트를 써요.
페이리가 보내는 웹훅은 SDK의 검증 유틸로 서명을 확인한 뒤 처리해요.
공통 규칙
두 SDK는 언어만 다를 뿐 같은 규칙을 따라요.
Base URL
기본값은 https://api.payri.kr이고, 모든 클라이언트가 baseUrl(Python은 base_url) 옵션으로 override를 지원해요.
테스트 프록시나 스테이징 환경을 겨눌 때만 바꾸면 돼요.
웹훅 검증
페이리 웹훅은 Standard Webhooks 규격이에요.
webhook-id·webhook-timestamp·webhook-signature 헤더와 원본(raw) 본문으로 서명을 검증해요.
JSON으로 파싱했다가 다시 직렬화하면 서명이 깨지므로, 반드시 수신한 바이트를 그대로 SDK에 넘겨야 해요.
같은 이벤트가 중복 도착할 수 있으니 webhook-id를 멱등 키로 쓰는 걸 권장해요. (재전송과 멱등성)
에러 계층
모든 에러는 PayriError를 상속하고, 상황별로 아래처럼 나뉘어요.
| 에러 | JS | Python | 상황 |
|---|---|---|---|
| 인증 실패 | PayriAuthError | PayriAuthError | 401/403 — 키 누락·무효, 스코프 부족, IP 제한 |
| API 에러 | PayriApiError | PayriAPIError | 그 외 4xx/5xx. status·code·body를 보존해요 |
| 연결 실패 | PayriConnectionError | PayriConnectionError | 네트워크 실패·타임아웃 등 응답을 받지 못한 경우 |
| 웹훅 검증 실패 | PayriWebhookError | PayriWebhookError | 서명·타임스탬프·페이로드 문제. reason으로 사유를 확인해요 |
같은 개념이지만 표기가 달라요 — JS는 PayriApiError, Python은 PayriAPIError.
에러 코드 목록은 에러 코드에서 확인해요.
언어별 가이드
Last updated on