장애 인지 가이드

토스페이먼츠 결제 장애를 실시간으로 인지하고 빠르게 대응하는 방법을 알려드릴게요. Status Page 웹훅을 구독하면 결제 장애와 복구 시점을 알림으로 받을 수 있어요. 이걸 활용해서 아래와 같은 대응을 자동화할 수 있어요.

• 구매자 안내 — 결제 오류 시 "일시적 장애" 안내 메시지를 보여주고 재시도를 유도해요.
• 내부 알림 — Slack, PagerDuty 등으로 운영팀에 즉시 알림을 보내요.
• 빌링 배치 시간 변경 — 장애 중 자동결제(빌링) 배치 실행을 지연하거나 일시 중단해요.

결제 실패 에러 코드(REJECT_CARD_PAYMENT, PROVIDER_ERROR 등)는 카드 한도초과·비밀번호 오류 등 장애와 무관한 원인이 대부분이에요. 토스페이먼츠 시스템 장애 시에도 동일한 코드가 반환되거나 요청 자체가 실패하는 경우가 있어서, 가맹점에서 운영하는 거래 성공률 모니터링과 함께 Status Page 웹훅을 활용하면 장애를 더 정확하게 인지할 수 있어요.

status.tosspayments.com에 접속해서 아래 순서로 구독해요.

1. Subscribe to Updates 클릭
2. 전달 방식에서 Webhook 선택
3. 수신 URL 입력 후 완료

수신 엔드포인트는 30초 안에 2xx 응답 코드를 반환해야 해요. 테스트 웹훅이 자동 발송되지 않으니, 4. Payload 예시 샘플로 직접 검증하세요.

Component 상태가 바뀌면 아래 종류 웹훅이 모두 발송돼요. 자세한 명세는 Atlassian Statuspage 웹훅 문서, 전체 Payload는 4. Payload 예시에서 확인할 수 있어요.

• Component Update — 각 서비스별 status 변경 알림. 자동화 로직에 적합.
• Incident Update — 장애 제목·본문·진행 경과 등 사람이 읽는 텍스트. Slack·구매자 안내 메시지에 활용.

Component 종류 — Status Page는 토스페이먼츠 서비스별 상태를 Component 단위로 보여줘요. 상황별 자세한 감지 방법은 3. 장애를 감지하고 대응하세요를 참고하세요.

Payload는 아래 형태의 JSON이 HTTP POST로 전송돼요. 핵심 필드는 component.id, component_update.new_status·old_status예요.

Component status — 각 Component의 상태값이에요.

Payload는 아래 형태로 전송돼요. 핵심 필드는 incident.status와 incident.incident_updates[].body예요.

Incident status — investigating으로 시작해서 resolved로 종료돼요. 중간 단계(identified, monitoring)와 사후 분석(postmortem)은 상황에 따라 생략돼요.

웹훅의 component.id로 장애 종류를 구분하고, component_update.new_status로 상태 변화를 판단해요. 자주 마주치는 두 상황(원천사 장애, 결제 시스템 전체 장애)을 살펴볼게요.

원천사 이슈 Component(ckdj8w8bby5v)는 카드사, 은행, 간편결제사 등 외부 제휴사 장애를 별도로 분리해서 알려줘요. degraded_performance ↔ operational 두 상태로만 전환돼요.

어떤 원천사가 영향받았는지는 Incident Update의 incident.incident_updates 배열(display_at 기준 최신 항목)의 body로 확인하세요. 본문은 아래 형식이에요.

결제 Component(0xsnykf1zpq7)는 토스페이먼츠 결제 시스템 전체 상태를 반영해요. 전체 결제 불가(major_outage)를 감지할 때 사용하세요.

원천사 Component(ckdj8w8bby5v)에서 토스카드 장애가 발생했다가 해소되는 시나리오예요. 한 건의 이벤트마다 Component Update와 Incident Update 두 종류가 모두 발송돼요.