결제의 흐름에,
안전한 연결을 더하세요.

가맹점 정보 없이 첫 거래를 연결하세요.#

안정적인 deviceId 하나로 시작할 수 있습니다. 가디언은 거래를 저장하고, 같은 HTTP 응답에서 위험 점수와 규칙별 결과를 반환합니다.

1. 1

   사이트와 API 키 준비

   가입·이메일 인증 후 관리자 사이트·설정에서 사이트 코드와 키를 확인하세요.

   인증 설정
2. 2

   개발 환경에서 거래 전송

   mode: "development"를 지정하고 샘플 요청을 서버에서 실행하세요.

   요청 예제
3. 3

   판정 확인 후 운영 전환

   score, risk, results를 확인하고 오류·재시도를 검증하세요.

   전환 체크리스트

인증 / API 키#

모든 Gateway 요청의 x-api-key 헤더에 해당 사이트의 API 키를 전달합니다. 로그인 세션과 Gateway API 키는 용도가 다릅니다. 사이트 코드와 키가 일치해야 하며, 다른 사이트의 이벤트는 조회할 수 없습니다.

export GUARDIAN_BASE_URL="https://api.fdsguard.co.kr"
export GUARDIAN_SITE_CODE="YOUR_SITE_CODE"
export GUARDIAN_API_KEY="YOUR_API_KEY"

가디언 API는 위 HTTPS 주소로 호출합니다. 개발 테스트 시에는 요청 본문에 mode: "development"를 명시하세요. 아래 cURL 예제는 Bash / zsh 기준입니다.

거래신호 전송#

거래신호를 전송하면 거래·단말기 연결·위험평가·사용량 저장을 완료한 뒤 결과를 반환합니다. 아래 예제는 코드 생성용이며 실제 거래를 전송하지 않습니다.

curl -X POST "$GUARDIAN_BASE_URL/api/v1/sites/$GUARDIAN_SITE_CODE/api-risk-score" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $GUARDIAN_API_KEY" \
  -H "Idempotency-Key: T202607120001:APPROVED" \
  -d '{
  "transaction": {
    "paidAt": "20260710091200",
    "amount": 850000,
    "mid": "111",
    "order_no": "222",
    "tid": "T202607120001",
    "auth_no": "12345678",
    "paymentType": "CARD_BILL",
    "cardNo": "557042******2076",
    "paymentStatus": "APPROVED",
    "currency": "KRW",
    "deviceId": "device-abc-123",
    "dailyCount": 12,
    "settlementDay": "D+1",
    "channel": "ONLINE"
  },
  "mode": "development"
}'

샘플 식별자를 실제 거래에 맞게 변경하세요. 취소 예제는 승인 예제를 먼저 전송한 뒤 같은 주문에 사용합니다. 재시도할 때는 키와 본문을 그대로 유지합니다.

요청 필드#

Content-Type: application/json으로 전송합니다. 요청 본문은 최대 64 KiB이며, 정의되지 않은 필드는 허용하지 않습니다. 식별자는 공백을 제거한 뒤 길이를 검증합니다.

결제수단 / 거래 채널#

channel은 ONLINE 또는 OFFLINE을 전달합니다. mid·결제수단과는 별개이며, 가디언이 결제수단에서 채널을 추정하지 않습니다.

위 5개 대문자 코드만 허용합니다. 한글명·공백·CARD·SMSK 등은 422 응답으로 거절됩니다.

동기 응답#

HTTP 200과 status: "completed"는 위험평가와 저장 완료를 의미합니다. risk는 normal·review·high, score는 0~100입니다. 위험평가 응답 자체가 결제를 승인하거나 취소하지는 않습니다.

{
  "eventId": "8f20a620-47a2-4f1e-a674-df0606408237",
  "tid": "T202607120001",
  "mode": "development",
  "status": "completed",
  "duplicate": false,
  "score": 0,
  "risk": "normal",
  "results": [
    {
      "id": "R01",
      "name": "단건 고액 거래",
      "status": "clear",
      "score": 0,
      "threshold": 1000000,
      "reason": "설정한 탐지 조건에 해당하지 않습니다.",
      "version": 1
    }
  ],
  "deviceId": "device-abc-123",
  "merchantIdentityStatus": "provisional",
  "cancellationLinkStatus": "not_applicable",
  "originalTransactionId": null,
  "completedAt": "2026-07-10T00:12:00.100Z"
}

results는 1개 규칙만 표시한 축약 예제입니다. 실제 응답은 전체 규칙 결과를 제공합니다. 점수·판정은 사이트 설정과 거래 이력에 따라 달라집니다.

이벤트 조회#

응답의 eventId를 같은 사이트 키로 조회합니다. 정상 동기 처리에는 폴링이 필요 없지만, 취소의 최신 연결 상태와 운영 복구를 확인할 때 사용할 수 있습니다.

# EVENT_ID에는 POST 응답의 eventId(UUID)를 넣으세요.
export EVENT_ID="8f20a620-47a2-4f1e-a674-df0606408237"
curl "$GUARDIAN_BASE_URL/api/v1/sites/$GUARDIAN_SITE_CODE/events/$EVENT_ID" \
  -H "x-api-key: $GUARDIAN_API_KEY"

이벤트가 존재하면 처리 상태와 관계없이 HTTP 200을 반환합니다. 조회 응답의 시간 필드는 received_at·completed_at(UTC ISO)이며, 완료 전에는 completed_at이 null입니다. 동기 POST의 completedAt과 필드 이름이 다릅니다. 동기 계약 이벤트에는 cancellationLinkStatus·originalTransactionId도 포함됩니다.

멱등성#

응답이 유실되어도 같은 거래를 안전하게 다시 보낼 수 있습니다. 각 거래 요청에 고유한 키를 만들고, 결과가 확정될 때까지 요청 본문과 함께 저장하세요.

위 순서로 키를 선택합니다. 헤더는 1~180자이며, 동일 사이트·mode 범위에서 적용합니다. 같은 키·같은 정규화 본문은 최초 완료 판정과 duplicate: true를 반환합니다. 다른 본문은 409입니다.

취소 거래 연결#

paymentStatus: "CANCELED"와 원 승인과 같은 order_no를 전송합니다. 승인·취소 TID는 같거나 달라도 됩니다. 현재 계약은 전체 취소만 지원하며, 금액과 통화가 일치해야 합니다.

오류 / 재시도#

HTTP 상태와 응답의 code·message를 함께 확인합니다. 입력 검증 오류는 issues에 필드 경로와 이유를 제공합니다.

{
  "code": "VALIDATION_ERROR",
  "message": "입력 형식을 확인하세요.",
  "issues": [
    {
      "path": [
        "transaction",
        "channel"
      ],
      "message": "ONLINE 또는 OFFLINE을 입력하세요."
    }
  ]
}

운영 전환 체크리스트#

샘플 요청에서 확인한 흐름을 실제 연동 환경에서도 검증하세요. 아래 체크는 현재 페이지에서만 유지됩니다.

변경 이력#