# Payvit

> Payvit 은 **온라인 VAN 결제 시스템**입니다. 가맹점이 PG 의 하위가맹점이 아니라 **카드사와 직접 계약된 VAN 가맹점** 으로 등록되어, 여신전문금융업법상 **법정 우대수수료(영세 체크카드 0.1% / 신용카드 0.5%)가 그대로 적용** 됩니다. 결제금은 카드사에서 가맹점 통장으로 직접 정산되며 (PG 마진 없음), 카드 가맹등록·간편결제 하위가맹점 등록까지 자동화하여 사업자등록증 1장으로 분 단위 온보딩 가능합니다. 개발자와 AI 코드 생성 도구(ChatGPT / Claude / Gemini 등)가 연동 코드를 빠르게 생성할 수 있도록 문서·OpenAPI 스펙·예시가 LLM 친화적으로 정리되어 있습니다.

도메인: `https://api.getpayvit.com`

## 핵심 가치

- **수수료 우위**: 영세 체크카드 0.1% / 신용카드 0.5% — 일반 PG(토스/이니시스 등) 대비 최대 25배 저렴
- **직접 정산**: 카드사 → 가맹점 통장 직접 입금 (PG 마진 없음)
- **자동 가맹등록**: 사업자등록증 1장 → API 1회 호출 → 카드 가맹등록 + 간편결제 등록 자동 완료
- **AI 친화**: `openapi.yaml` + `llms.txt` 노출 → ChatGPT / Claude 첨부 시 즉시 연동 코드 생성
- **링크 결제**: 가맹점 자체 결제 화면 없어도 `paymentLink` 1줄로 결제 완결 (오프라인 매장·학원·1:1 청구 시나리오 강함)

## 빠른 요약

- **결제 생성**: `POST /api/payment/create` → `paymentLink` 반환 → 고객에게 전달
- **인증**: 모든 `/api/**` 요청에 `X-API-Key` 헤더 필수 (가맹점별 키 / ADMIN 키 2단계)
- **웹훅**: 결제 완료 시 가맹점 `webhookUrl` 로 자동 POST, 5분 간격 최대 5회 재시도
- **결제 상태**: `00`(대기) → `10`(인증완료) → `20`(승인완료) / `30`(취소) / `99`(실패) / `97`(확인필요)
- **응답 wrapper**: `{ "resultCode": "00", "data": {...} }` — `00`=성공, `98`=검증오류, `99`=비즈니스오류, `-1`=시스템오류

## Docs

- [개발자 가이드 (HTML)](https://api.getpayvit.com/guide): 결제 흐름·인증·결제수단·에러 코드·체크리스트 — 사람용 1차 진입점
- [OpenAPI 3.1 스펙 (machine-readable)](https://api.getpayvit.com/openapi.yaml): AI 코드 생성 / Postman / Swagger UI / OpenAPI Generator 용 기계 판독 가능 스펙
- [통합 연동 가이드 (Markdown)](https://github.com/lessonmonster/payvit/blob/master/docs/payvit-integration-guide.md): cURL / Java / Node.js / Python 예제 + 모바일 앱 통합 (Android `<queries>` + iOS `LSApplicationQueriesSchemes` scheme reference 포함)
- [짧은 연동 가이드 (Markdown)](https://github.com/lessonmonster/payvit/blob/master/docs/guide/README.md): 핵심 endpoint 만 추린 간이 버전
- [가맹점 FAQ (Markdown)](https://github.com/lessonmonster/payvit/blob/master/docs/faq-merchant.md): 가맹점 개발팀 자주 묻는 질문 / 트러블슈팅

## API 핵심 endpoint

- [결제 생성](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1payment~1create/post): `POST /api/payment/create`
- [결제 조회](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1payment~1{paymentId}/get): `GET /api/payment/{paymentId}`
- [결제 취소](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1payment~1{paymentId}~1cancel/post): `POST /api/payment/{paymentId}/cancel`
- [청구서 파기](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1payment~1{paymentId}~1void/post): `POST /api/payment/{paymentId}/void` (대기 상태만)
- [결제 검색](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1payment~1search/get): `GET /api/payment/search`
- [통합 가맹점 등록](https://api.getpayvit.com/openapi.yaml#/paths/~1api~1merchant~1register-full/post): `POST /api/merchant/register-full` (운영팀 전용)

## Optional

- [결제창 템플릿 가이드](https://api.getpayvit.com/guide#template): default / modern / minimal 무료, 화이트라벨 커스텀 템플릿 유료
- [가맹점 신청 (공개 신청 폼)](https://api.getpayvit.com/apply): `POST /api/merchant-request`