Payvit 개발자 가이드 v1.0

curl -X POST https://api.getpayvit.com/api/payment/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {발급받은 API Key}" \
  -d '{
    "merchantId": "{가맹점 ID}",
    "orderId": "ORDER-001",
    "productName": "테스트 상품",
    "price": 1000
  }'

{
  "resultCode": "00",
  "data": {
    "paymentId": "enc_abc123...",
    "paymentLink": "https://api.getpayvit.com/pay/enc_abc123...",
    "merchantId": "my-store",
    "merchantNm": "내 가게",
    "price": "1000"
  }
}

{
  "paymentId": "enc_abc123...",
  "orderId": "ORDER-001",
  "merchantId": "my-store",
  "payStatus": "20",
  "price": 1000,
  "approvalNum": "12345678",
  "approvalTime": "20260410173025",
  "paymentCompCode": "KKP2"
}

다음 OpenAPI 스펙을 참고해서 Payvit 결제 연동 코드를 Node.js + Express 로 작성해줘:
https://api.getpayvit.com/openapi.yaml

요구사항:
- POST /api/payment/create 호출하여 paymentLink 발급
- /webhook endpoint 에서 결제 완료 수신 (HTTP 200 + {"resultCode":"OK"} 응답)
- extraData 에 내부 주문번호 JSON 으로 넣고 webhook 에서 그대로 매칭

# TypeScript SDK 자동 생성
npx @openapitools/openapi-generator-cli generate \
  -i https://api.getpayvit.com/openapi.yaml \
  -g typescript-fetch \
  -o ./payvit-sdk

# Python SDK 자동 생성
npx @openapitools/openapi-generator-cli generate \
  -i https://api.getpayvit.com/openapi.yaml \
  -g python \
  -o ./payvit-sdk-python

X-API-Key: {발급받은 API Key}

Content-Type: multipart/form-data
X-API-Key: {ADMIN API Key}

{
  "resultCode": "00",
  "data": {
    "merchantId": "stb-gangnam",
    "apiKey": "a1b2c3d4e5f6...",
    "catId": "6126530",
    "mid": "NICE-MID-001",
    "naverMerchantId": "LINKPstbgangnam",
    "nicevanStatus": "2",
    "steps": {
      "merchant":  { "success": true,  "message": "가맹점 등록 완료" },
      "catId":     { "success": true,  "message": "CAT-ID 할당 완료: 6126530" },
      "contract":  { "success": true,  "message": "계약서 등록 완료" },
      "affInfo":   { "success": true,  "message": "가맹점번호 조회 완료" },
      "nicevan":   { "success": true,  "message": "NiceVAN 등록 완료 (MID: NICE-MID-001)" },
      "naverPay":  { "success": true,  "message": "NaverPay 등록 완료: LINKPstbgangnam" }
    }
  }
}

{
  "resultCode": "00",
  "data": {
    "merchantId": "stb-gangnam",
    "apiKey": "a1b2c3d4e5f6...",
    "catId": "6126530",
    "mid": "",
    "naverMerchantId": "",
    "nicevanStatus": "0",
    "steps": {
      "merchant":  { "success": true,  "message": "가맹점 등록 완료" },
      "catId":     { "success": true,  "message": "CAT-ID 할당 완료: 6126530" },
      "contract":  { "success": false, "message": "CONT_9999: 파일 형식 오류" },
      "affInfo":   { "success": false, "message": "미실행 (계약서 등록 실패)" },
      "nicevan":   { "success": false, "message": "미실행 (계약서 등록 실패)" },
      "naverPay":  { "success": false, "message": "미실행 (계약서 등록 실패)" }
    }
  }
}

Content-Type: application/json
X-API-Key: {API Key}

{
  "merchantId": "biz-gangnam",
  "orderId": "ORD-2026-0412-001",
  "productName": "PT 10회권",
  "price": 500000,
  "returnUrl": "https://example.com/orders",
  "cancelUrl": "https://example.com/orders/failed"
}

https://example.com/orders?paymentId=enc_abc123&orderId=ORD-2026-0412-001&status=paid

// status: paid(완료) / cancelled(취소) / failed(실패)

// 학원
{"수강생":"박시훈","반":"심화반","기간":"2026.03.01~03.31"}

// 쇼핑몰
{"배송지":"서울 강남구","수량":"2개","옵션":"블랙 L"}

{
  "resultCode": "00",
  "data": {
    "paymentId": "enc_abc123...",
    "paymentLink": "https://api.getpayvit.com/pay/enc_abc123...",
    "price": "250000",
    "merchantId": "biz-gangnam",
    "merchantNm": "솔레아스 강남"
  }
}

X-API-Key: {API Key}

{
  "resultCode": "00",
  "data": {
    "paymentId": "enc_abc123...",
    "merchantId": "biz-gangnam",
    "orderId": "ORD-2026-001",
    "productName": "3월 학원비",
    "price": 250000,
    "payStatus": "20",
    "paymentCompCode": "KKP2",
    "webhookSent": "1",
    "regTs": "2026-04-10T17:30:00",
    "payTs": "2026-04-10T17:32:15"
  }
}

Content-Type: application/json
X-API-Key: {API Key}

{
  "resultCode": "00",
  "data": {
    "paymentId": "enc_abc123...",
    "approvalNum": "87654321",
    "approvalTime": "20260410180500"
  }
}

X-API-Key: {API Key}

?orderId=ORD-001&payStatus=20&startDate=2026-04-01&endDate=2026-04-10&page=1&size=20

X-API-Key: {API Key}
Content-Type: application/json

{
  "merchantId": "biz-1",
  "issueType":  "INCOME",
  "cashNoType": "PHONE",
  "cashNo":     "01012345678",
  "amount":     10000
}

{
  "resultCode": "00",
  "data": {
    "cashReceiptId": "enc_abc123...",
    "status":   "20",
    "apprNo":   "12345678",
    "apprDate": "260527",
    "seqNo":    "260527XXXXXX",
    "resultCode": "0000"
  }
}

X-API-Key: {API Key}
Content-Type: application/json

{
  "reason": "고객 환불 요청"
}

{
  "resultCode": "00",
  "data": {
    "cashReceiptId": "enc_abc123...",
    "status":       "30",
    "cancelApprNo": "98765432",
    "cancelSeqNo":  "260527XXXXXX"
  }
}

X-API-Key: {API Key}

X-API-Key: {API Key}

?startDate=2026-05-01&endDate=2026-05-27&status=20&page=1&size=20

@PostMapping("/api/payment/webhook")
public ResponseEntity<Map<String, Object>> receiveWebhook(
        @RequestBody Map<String, Object> payload) {

    String paymentId = (String) payload.get("paymentId");
    String orderId   = (String) payload.get("orderId");
    int price        = (int) payload.get("price");
    String payStatus = (String) payload.get("payStatus");

    // 주문 상태 업데이트
    orderService.updatePaymentStatus(orderId, payStatus, price);

    // 응답 (HTTP 200 필수)
    Map<String, Object> response = new HashMap<>();
    response.put("resultCode", "OK");
    return ResponseEntity.ok(response);
}

app.post('/api/payment/webhook', (req, res) => {
    const { paymentId, orderId, price, payStatus } = req.body;

    // 주문 상태 업데이트
    updateOrder(orderId, payStatus, price);

    // 응답 (HTTP 200 필수)
    res.json({ resultCode: 'OK' });
});