GUARDIAN FDS API 연동 시작하기

사이트와 개발 환경 준비

개발자 센터에서 현재 연동 주소와 예제를 확인합니다. 사이트 코드와 서버 API 키를 준비하고 개발 모드로 요청하세요. API 키는 서버 환경 설정에 보관하며 브라우저 번들이나 공개 저장소에 넣지 않습니다.

입력 계약 확인

현재 거래 입력은 transaction 안의 금액·통화·거래 식별자·결제 상태·단말기·채널 등을 사용합니다. 거래 시각 paidAt은 공개 입력 계약에서 한국 시간 yyyyMMddHHmmss 형식의 문자열입니다. 내부 저장 시각 형식을 추측해 입력으로 보내지 마세요.

예를 들어 가상의 2026년 10월 7일 14시 30분 5초 거래는 paidAt을 20261007143005로 표현합니다. 10,000원은 amount 숫자 10000으로 보내고 화면용 쉼표를 포함하지 않습니다. 실제 전체 요청 본문은 요청 필드와 실행 예제를 사용하세요.

결과 확인

HTTP 성공 코드만 확인하지 말고 응답의 이벤트 식별자, 처리 상태, 위험 점수와 규칙별 결과를 확인합니다. 응답 유실이 발생했을 때 같은 업무 요청을 재전송할 수 있도록 멱등성을 함께 설계합니다.

운영 전환

정상 승인, 중복 요청, 전체 취소, 잘못된 키, 잘못된 금액·시각을 시험합니다. 개발 거래가 운영 목록에 섞이지 않는지 확인한 후 운영 환경과 키로 전환하세요. 문서의 예시 값은 가상 값이며 실제 회원·카드 정보를 복사해 테스트하지 않습니다.

가상 검증 사례

가상의 개발 거래를 한 번 전송하고 같은 키와 본문으로 다시 보냅니다. 두 번째 응답의 duplicate와 eventId를 확인합니다. 인증 오류가 발생하면 요청을 반복하기 전에 사이트 코드와 키 조합을 확인합니다.

이 사례는 실측 성능이나 실제 고객 자료가 아닙니다. 제품의 적용 범위는 GUARDIAN 공개 API 계약를 기준으로 확인합니다.

가상 요청 본문

아래 JSON은 입력 계약 검증용 가상 승인입니다. 거래신호 전송의 주소와 인증 헤더를 적용하고 개발 모드를 유지하세요. 재전송에는 같은 본문과 키를 사용합니다.

{
  "mode": "development",
  "eventId": "geo-example-20261008",
  "transaction": {
    "deviceId": "geo-device",
    "mid": "geo-mid",
    "order_no": "geo-order",
    "tid": "geo-tid",
    "paidAt": "20261008162200",
    "amount": 10000,
    "currency": "KRW",
    "channel": "ONLINE",
    "paymentType": "AUTH",
    "paymentStatus": "APPROVED"
  }
}