API를 통해 웹훅 URL을 등록, 조회, 수정, 삭제하고 샘플 거래통보로 검증하는 가이드

• 운영 ClientId (R1_ 또는 R2_ prefix)
• 운영 SecretKey
• HTTPS 웹훅 엔드포인트 URL

웹훅을 받을 서버 엔드포인트가 다음 조건을 만족해야 합니다:

HTTP Status: 200
Content-Type: text/html
Response Body: "OK"

⚠️ 주의: Content-Type이 application/json이면 안 됩니다!

Base64 인코딩으로 인증 토큰을 생성합니다.

# macOS/Linux
echo -n "R2_your_client_id:your_secret_key" | base64

# 결과 예시
UjJfeW91cl9jbGllbnRfaWQ6eW91cl9zZWNyZXRfa2V5

카드 결제 웹훅 URL을 등록합니다.

curl -X POST 'https://api.nicepay.co.kr/v1/webhook' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6eW91cl9zZWNyZXRfa2V5' \
-d '{
  "method": "card",
  "url": "https://your-domain.com/webhook/nicepay",
  "managerEmail": "[email protected]"
}'

1. API 요청 전송
2. NICEPAY가 등록한 URL로 샘플 거래통보 전송
3. 서버에서 HTTP 200 + "OK" 응답
4. 검증 성공 시 등록 완료

{
  "resultCode": "0000",
  "resultMsg": "정상 처리되었습니다.",
  "messageSource": "nicepay"
}

웹훅 URL 등록 시 NICEPAY가 보내는 샘플 데이터 예시:

{
  "resultCode": "0000",
  "resultMsg": "sample",
  "tid": "nictest00m01012109281716439616M3497138",
  "orderId": "SAMPLE-ORDER-ID",
  "amount": 1000,
  "payMethod": "card",
  "status": "paid",
  "signature": "샘플_signature",
  "ediDate": "2024-01-01T00:00:00+09:00"
}

샘플 데이터 특징:

• resultMsg: "sample" - 테스트 데이터임을 표시
• Signature 검증 불필요 (더미 데이터)

• 서버 로그에서 샘플 데이터 수신 확인
• HTTP 200 + "OK" 응답 확인
• API 응답에서 resultCode: "0000" 확인

등록된 웹훅 URL을 조회합니다.

curl -X GET 'https://api.nicepay.co.kr/v1/webhook' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6eW91cl9zZWNyZXRfa2V5'

{
  "resultCode": "0000",
  "resultMsg": "정상 처리되었습니다.",
  "messageSource": "nicepay",
  "urls": [
    {
      "method": "card",
      "url": "https://your-domain.com/webhook/nicepay",
      "managerEmail": "[email protected]"
    }
  ]
}

curl -X POST 'https://api.nicepay.co.kr/v1/webhook' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6...' \
-d '{
  "method": "vbank",
  "url": "https://your-domain.com/webhook/nicepay"
}'

curl -X POST 'https://api.nicepay.co.kr/v1/webhook' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6...' \
-d '{
  "method": "bank",
  "url": "https://your-domain.com/webhook/nicepay"
}'

curl -X POST 'https://api.nicepay.co.kr/v1/webhook/card/update' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6...' \
-d '{
  "url": "https://your-domain.com/webhook/nicepay-v2"
}'

curl -X POST 'https://api.nicepay.co.kr/v1/webhook/card/delete' \
-H 'Content-type: application/json' \
-H 'Authorization: Basic UjJfeW91cl9jbGllbnRfaWQ6...'

원인:

• Content-Type이 application/json
• Response Body가 "OK"가 아님
• HTTP Status가 200이 아님

해결: 웹훅 엔드포인트가 다음 형식으로 응답하는지 확인:

HTTP/1.1 200 OK
Content-Type: text/html

OK

원인:

• HTTPS 인증서 오류
• 방화벽에서 NICEPAY IP 차단
• 웹훅 엔드포인트가 응답하지 않음

해결:

1. SSL 인증서 확인: openssl s_client -connect your-domain.com:443
2. 방화벽 인바운드 규칙 확인
3. 서버 실행 상태 확인

원인:

• 서버가 실행 중이 아님
• 웹훅 엔드포인트 경로 오류
• 로드밸런서/프록시 설정 오류

해결:

1. 서버 실행 상태 확인
2. 엔드포인트 경로 확인
3. nginx/apache 프록시 설정 확인

• Authorization 토큰 생성
• 웹훅 엔드포인트 구현 (HTTP 200 + text/html + "OK")
• 카드 결제 웹훅 URL 등록 성공
• 샘플 거래통보 수신 확인
• 조회 API로 등록 상태 확인

• 웹훅 테스트 - 실제 결제로 웹훅 수신 테스트
• 웹훅 API 상세 명세