운영
안정 운영 가이드
대사, 콜백 유실 복구, 발송 도착 확인, 포인트, 장애 대응 — 실제 고객에게 나갈 때 지켜야 할 운영 규칙입니다.
매일 하는 것
| 작업 | 방법 | 기준 |
|---|---|---|
| 승인 대사 | 전일 PAID 주문의 APPROVAL_AMOUNT 합계 vs 귀사 주문 금액 합계 | 불일치 0건 |
| 미결제 정리 | 24시간 넘은 PENDING 주문을 searchPayment로 확인 → 승인이면 복구, 아니면 만료·삭제 | 콜백 유실 복구 |
| 취소 대사 | CANCEL_COMPLETE 건이 귀사 CANCELED와 일치 | 불일치 0건 |
| 포인트 잔액 | GET /app/v1/points/me 또는 콘솔 | 다음 발송 예정량 이상 |
콜백 유실 복구
콜백은 실패하면 최대 30회(약 21시간) 재시도하지만, 귀사 서버 장애가 그보다 길면 끝내 도착하지 않습니다. 배치가 PENDING 주문을 주기적으로 조회해 승인된 건을 PAID로 전이시키는 것이 최종 안전망입니다. 배치와 콜백이 같은 settle()을 쓰면 중복 처리가 생기지 않습니다.
1분마다: SELECT trans_seqno FROM orders WHERE status='PENDING' AND created_at > now()-24h
→ 각 건 searchPayment → paid면 settle()알림톡·문자 도착 확인
- 발송 API의 성공은 알리고 접수입니다. 알림톡의 실제 도착은 발송 이력 상태 갱신(
refresh-status)으로 알리고 결과를 다시 읽어야 압니다. - 문자(LMS)는 접수 결과만 제공됩니다.
- 도착 실패가 반복되는 번호는 발송 수단을
SMS로 바꾸거나ALIMTALK_THEN_SMS를 기본값으로 쓰세요. - 고객 항의("못 받았어요")는 재발송으로 대응하고, 재발송도 포인트가 차감됨을 운영자가 알아야 합니다.
장애 대응
| 증상 | 확인 | 조치 |
|---|---|---|
결제 생성이 3001 | 운영/테스트 키 혼용, TRANS_AT 불일치 | 환경변수 점검 |
결제 생성이 4001 | 재시도가 같은 거래번호 재사용 | 거래번호를 재시도마다 새로 채번(단, 이미 생성된 링크가 있으면 그 링크를 재사용) |
| 콜백이 안 옴 | CONFIRM_URL이 http, 방화벽, 5xx 응답 | https·200 응답 확인, 폴링으로 복구 |
결제는 됐는데 주문이 PENDING | 콜백 유실 + 배치 미동작 | 배치 점검, 수동 searchPayment |
취소가 4004 | 카드사 취소 실패(CANCEL_FAIL) | 카리페이 문의 (거래번호 첨부) |
| 청구서 발송실패 | 포인트 부족, 게이트웨이 오류, 알림 접수 거절 | 발송 이력 errorMessage 확인 후 재발송 |
| 게이트웨이 헬스 | GET {BASE_URL}/actuator/health → {"status":"UP"} | 다운이면 카리페이 장애 채널 |
연락망
- 기술 지원: bellight@goatheaven.com (키 발급 시 안내된 담당자 채널 우선)
- 문의 시 포함할 것:
TRANS_SEQNO, 발생 시각(KST), 요청·응답 본문(API_KEY·카드정보 제외), 콜백 수신 여부.
변경 관리
- 게이트웨이 규격 변경·도메인 변경은 사전 고지 후 유예기간을 둡니다. 릴리즈 노트
- 콜백 본문 필드는 늘어날 수 있습니다. 모르는 필드는 무시하세요.
문서에 없는 내용이나 오류는 bellight@goatheaven.com 또는 지원 문의로 알려주세요.