API REFERENCE · V1

Guardian FDS 공개 API

이 페이지는 고객 연동용 공개 /v1 경로만 다룹니다. 기준 원본은 OpenAPI 계약이며, Gateway와의 자동 계약 검증을 통과해야 배포할 수 있습니다.

OpenAPI 3.0 계약 다운로드

Base URL

https://api.fdsguard.co.kr

인증

x-api-key: Site credential

재시도

Idempotency-Key: 8–128자

PRODUCTION OPERATIONS · V1

활성화·사용량·서비스 목표

Production 활성화

시스템 관리자 승인 + 품질·보안 Gate + 활성 계약

Rate limit

Site credential당 120건 / 60초 · 429 RATE_LIMITED

월 quota

활성 계약 capacity_limit · 초과 시 429 API_QUOTA_EXCEEDED

SLO

수신 99.9% · 평가 P95 5분 · Webhook 99.5%

GET /v1/usage에서 현재 credential의 UTC 월별 사용량과 남은 quota를 조회합니다. 429·5xx·네트워크 오류만 동일한 Idempotency-Key로 지수 백오프 재시도하세요. P1 수신 장애는 15분, P2 평가·Webhook 지연은 1시간 내 대응합니다.

WEBHOOK SECURITY CONTRACT · V1

원문 body 서명과 안전한 Secret 회전

식별·시각

x-guardian-event-id · x-guardian-timestamp(UTC ISO-8601)

서명

x-guardian-signature: v1=<HMAC-SHA256 hex>

서명 원문

timestamp + '.' + event ID + '.' + raw request body

재전송 방지

수신 시 ±5분 시각 검증과 event ID 중복 제거

Secret 교체 뒤 24시간 동안 이전 Secret으로 만든 x-guardian-signature-previous도 함께 보냅니다. 수신기는 현재 Secret으로 먼저 검증하고, 유효 기간 안에서만 이전 Secret 검증을 허용하세요. Endpoint 활성화 시에는 event_type: webhook.challenge 테스트 이벤트가 전달됩니다. Secret·URL·payload는 로그에 남기지 않습니다.

공개 경로

Site code는 URL이나 body에 넣지 않습니다. credential이 호출 Site를 결정합니다.

POST/v1/transactionsPayload 상세 →

거래 Event를 비동기 원장과 평가 큐에 수신합니다.

202 수신 · 200 Sandbox · 400 계약 오류 · 401 인증 · 409 멱등성 충돌 · 429 제한 · 503 재시도

GET/v1/ingestions/{ingestionId}

수신된 거래의 원장·평가 상태를 같은 Site 범위에서 조회합니다.

200 조회 · 400 ID 형식 · 401 인증 · 404 없음 · 429 제한

GET/v1/transactions/{sourceEventId}/risk

거래 TID(저장 source_event_id)로 안전한 평가 상태·점수·결정을 같은 Site 범위에서 조회합니다.

200 조회 · 400 ID 형식 · 401 인증 · 404 없음 · 429 제한

GET /v1/transactions/tid_demo_auth_001/risk

POST/v1/transactions/{sourceEventId}/outcomes

사기 확정·오탐·차지백 확정 라벨을 거래 원장에 append-only로 기록합니다. Idempotency-Key로 같은 요청을 안전하게 재전송합니다.

202 수신 · 400 형식/label 오류 · 401 인증 · 404 없음 · 409 멱등성 충돌 · 429 제한

Idempotency-Key: outcome_20260827_001
{ "outcome_label": "FRAUD_CONFIRMED" }

GET/v1/usage

현재 credential의 월간 사용량과 계약 quota를 조회합니다.

200 조회 · 401 인증 · 429 제한 · 503 일시 오류

TRANSACTION LIFECYCLE EXAMPLES

승인·취소·환불·차지백

모든 예제는 POST /v1/transactions에 같은 형식으로 전송합니다. 예제의 식별자와 Token은 문서 전용 값이며 카드번호·계좌번호·CVC·실제 API Key를 포함하지 않습니다.

승인 · PAYMENT_AUTH / AUTH

승인 이벤트는 할부가 없더라도 installment_months: 0을 포함합니다. TID가 있으면 source_event_id 두 곳은 TID와 같게 보내며, 서버도 TID를 저장·조회 기준으로 사용합니다.

요청 body

{
  "schema_version": "1.0",
  "source_event_id": "tid_demo_auth_001",
  "occurred_at": "2026-08-27T10:00:00+09:00",
  "sent_at": "2026-08-27T10:00:01+09:00",
  "source_system": "merchant-payment-server",
  "event_type": "PAYMENT_AUTH",
  "merchant_external_id": "merchant_demo_001",
  "transaction": {
    "source_event_id": "tid_demo_auth_001",
    "type": "AUTH", "status": "APPROVED",
    "occurred_at": "2026-08-27T10:00:00+09:00",
    "amount_minor": 18000, "currency": "KRW", "channel": "ECOMMERCE",
    "installment_months": 0, "tid": "tid_demo_auth_001",
    "auth_no_token": "auth-token-demo-001"
  },
  "payment_method": { "type": "CARD", "token": "payment-method-token-demo-001" }
}

취소 · PAYMENT_CANCEL / CANCEL

취소는 새 Event로 수신합니다. 기존 승인 Event를 수정하지 않으며 transaction.original_event_id에 원거래 source_event_id를 반드시 연결합니다.

요청 body

{
  "schema_version": "1.0",
  "source_event_id": "tid_demo_cancel_001",
  "occurred_at": "2026-08-27T10:05:00+09:00",
  "sent_at": "2026-08-27T10:05:01+09:00",
  "source_system": "merchant-payment-server",
  "event_type": "PAYMENT_CANCEL",
  "merchant_external_id": "merchant_demo_001",
  "transaction": {
    "source_event_id": "tid_demo_cancel_001",
    "original_event_id": "tid_demo_auth_001",
    "type": "CANCEL", "status": "CANCELED",
    "occurred_at": "2026-08-27T10:05:00+09:00",
    "amount_minor": 18000, "currency": "KRW", "channel": "ECOMMERCE", "tid": "tid_demo_cancel_001"
  }
}

환불 · PAYMENT_REFUND / REFUND

환불도 원거래와 연결된 별도 Event입니다. 계약은 amount_minor가 0 이상의 정수이고 통화가 ISO 4217 대문자 3자리인지 검사합니다.

요청 body

{
  "schema_version": "1.0",
  "source_event_id": "tid_demo_refund_001",
  "occurred_at": "2026-08-27T11:00:00+09:00",
  "sent_at": "2026-08-27T11:00:01+09:00",
  "source_system": "merchant-payment-server",
  "event_type": "PAYMENT_REFUND",
  "merchant_external_id": "merchant_demo_001",
  "transaction": {
    "source_event_id": "tid_demo_refund_001",
    "original_event_id": "tid_demo_auth_001",
    "type": "REFUND", "status": "REVERSED",
    "occurred_at": "2026-08-27T11:00:00+09:00",
    "amount_minor": 18000, "currency": "KRW", "channel": "ECOMMERCE", "tid": "tid_demo_refund_001"
  }
}

차지백 · PAYMENT_CHARGEBACK / CHARGEBACK

차지백 Event에는 원거래 연결이 필수입니다. 확정 결과를 별도로 기록할 때는 POST /v1/transactions/{sourceEventId}/outcomes의 CHARGEBACK_CONFIRMED 라벨을 사용하며, 둘 다 append-only입니다.

요청 body

{
  "schema_version": "1.0",
  "source_event_id": "tid_demo_chargeback_001",
  "occurred_at": "2026-08-27T12:00:00+09:00",
  "sent_at": "2026-08-27T12:00:01+09:00",
  "source_system": "merchant-payment-server",
  "event_type": "PAYMENT_CHARGEBACK",
  "merchant_external_id": "merchant_demo_001",
  "transaction": {
    "source_event_id": "tid_demo_chargeback_001",
    "original_event_id": "tid_demo_auth_001",
    "type": "CHARGEBACK", "status": "APPROVED",
    "occurred_at": "2026-08-27T12:00:00+09:00",
    "amount_minor": 18000, "currency": "KRW", "channel": "ECOMMERCE", "tid": "tid_demo_chargeback_001"
  }
}

결과 라벨: 사기 확정·오탐·차지백 확정은 거래 Event를 수정하지 않고 POST /v1/transactions/{sourceEventId}/outcomes에 Idempotency-Key와 FRAUD_CONFIRMED, FALSE_POSITIVE, CHARGEBACK_CONFIRMED 중 하나를 보내 append-only로 기록합니다.

오류와 안전한 재시도

HTTP	대표 errorCode	처리 방법
400	CONTRACT_VALIDATION_FAILED	필수 필드, 형식, enum 또는 금지 필드를 수정합니다.
401	UNAUTHORIZED	x-api-key가 누락·비활성·다른 Site credential인지 확인합니다.
409	IDEMPOTENCY_CONFLICT	같은 Idempotency-Key에는 최초 요청과 완전히 같은 payload만 재전송합니다.
429	API_QUOTA_EXCEEDED / rate limit	Retry-After를 따르고 지수 백오프로 재시도합니다.
404	TRANSACTION_NOT_FOUND	현재 x-api-key Site 범위에 해당 거래가 있는지 확인합니다.
503	INGESTION_UNAVAILABLE	같은 Idempotency-Key로 재시도합니다.

카드번호·계좌번호·CVC·비밀번호·원문 IP는 전송하지 않습니다. 안정 Token, BIN/last4, IP prefix 같은 계약된 파생값만 사용합니다.