가이드
페이리는 디지털 상품(파일·라이선스 키·구독·링크)을 파는 1인 크리에이터와 인디 개발자를 위한 결제 플랫폼이에요.
이 페이지는 연동 전에 꼭 알아둘 것만 모았어요.
엔드포인트 스펙은 REST API 레퍼런스에서 다뤄요.
연동 흐름
결제 한 건이 처리되는 전체 흐름이에요.
구매자·페이리·PG·셀러 서버가 어떻게 주고받는지 보여줘요.
결제는 인증 → 승인 2단계로 진행돼요.
구매자가 결제창에서 결제수단을 인증하면, 페이리가 그 결과로 PG 승인을 일으켜 주문을 paid로 확정해요.
그다음 셀러 서버는 order.paid 웹훅을 받아 서명을 검증하고 멱등 처리 후 200으로 응답하고, 라이선스 상품이면 발급 방식에 따라 키를 내려줘요.
라이선스 발급 분기는 라이선스 연동에서 다뤄요.
주문의 진실은 웹훅이 아니라 API 조회예요.
웹훅은 중복·지연·유실될 수 있으니, 중요한 처리 전에는 GET /v1/orders/:id로 최종 상태를 확인하세요.
연동 전 결정 사항
상품을 만들기 전에 아래 항목을 먼저 정해야 해요.
대부분 나중에 바꿀 수 있지만, 미리 정해두면 연동 코드와 테스트 시나리오가 명확해져요.
| 결정 항목 | 선택지 | 비고 |
|---|---|---|
| 전달물 종류 | file · license · link | license면 발급 방식을 추가로 정해요 |
| 가격 구조 | 일회성 · 구독(월/연) | 구독은 플랜×주기만큼 결제 링크가 생겨요 |
| 환불 정책 | no_refund · before_delivery · within_7days · custom | 상품의 refundPolicy로 설정해요 |
테스트 / 라이브 환경
API 키는 live(운영)와 test(개발·테스트) 두 모드로 발급돼요.
모드는 키를 환경별로 구분하는 표시예요.
개발 단계에서는 test 키로 연동을 검증하고, 운영 배포 시 live 키로 교체하는 걸 권장해요.
| 구분 | test | live |
|---|---|---|
| 키 접두어 | pk_test_… | pk_live_… |
| 용도 | 개발·스테이징 환경 | 운영 환경 |
키 모드는 발급 시점에 정해지고 바꿀 수 없어요.
운영으로 넘어갈 때는 live 키를 새로 발급해 환경변수만 교체하세요.
키는 코드·저장소에 하드코딩하지 말고 비밀 저장소(환경변수·시크릿 매니저)에 보관하세요.