API REFERENCE · POST /v1/transactions

거래 Payload 상세 레퍼런스

test_site에서 실제로 전송하는 Payload를 기준으로 각 필드의 의미, 전송 규칙, FDS 탐지 활용 방법을 설명합니다.

보안 원칙: 카드번호·계좌번호·CVC·비밀번호·주민번호·원문 IP를 보내지 마세요. Token, BIN/last4, IP Prefix 등 계약된 파생값만 사용합니다.

1. 공통 Envelope

이 요청이 무엇이며 어느 고객사 가맹점의 어떤 사건인지 식별합니다.

schema_version필수

현재 API 계약 버전입니다.

1.0

source_event_id필수

전송 이벤트 ID입니다. transaction.tid가 있으면 Gateway가 TID를 저장·위험조회·결과 라벨의 공통 추적 키로 사용합니다.

tid_test_…

occurred_at / sent_at필수

거래 발생 시각과 Gateway 전송 시각입니다. ISO 8601 및 UTC Offset을 포함합니다.

source_system / event_type필수

원천 시스템과 사건 유형입니다. test_site는 guardian-test-site, PAYMENT_CAPTURE를 사용합니다.

merchant_external_id조건부

MULTI_MERCHANT 계약에서는 사이트 범위에서 유일한 가맹점 ID가 필수입니다. SINGLE_COMPANY 계약은 생략할 수 있으며, Guardian이 내부 기본 주체를 사용합니다.

correlation_id권장

주문·승인·취소 같은 관련 사건을 묶는 추적 ID입니다.

2. 거래와 결제수단

원장 저장·중복 방지·위험 평가의 최소 필수 데이터입니다.

transaction.*필수

거래 ID, 유형, 상태, 시각, 최소 화폐단위 금액, 통화, 채널을 포함합니다. amount_minor는 KRW라면 원 단위 정수입니다.

transaction.tid / auth_no_token권장

PG 거래 ID와 Token화된 승인 참조값입니다. TID를 보내면 source_event_id를 TID로 정규화하므로 두 source_event_id도 TID와 같게 보내는 것을 권장합니다.

payment_method.type / token필수

결제수단 종류와 안정 Token입니다. 전체 카드번호, 계좌번호, CVC는 절대 전송하지 않습니다.

payment_method.card.bin / last4조건부

계약된 BIN과 마지막 4자리만 허용됩니다. PAN 전체는 금지됩니다.

payment_method.three_ds권장

3DS 적용·인증 결과로 인증 우회 신호를 판단합니다.

3. 주문·고객·기기·세션

계정 탈취, 카드 테스트, 디지털 상품 악용 등의 맥락을 보강합니다.

order권장

주문 ID, 상품 분류, 디지털 상품 여부, 품목 수입니다.

customer.external_customer_token권장

고객 원문 ID 대신 재사용 가능한 안정 Token입니다.

device.fingerprint_token권장

기기 공유·변조 판단용 Token입니다. trusted, emulator_or_rooted를 함께 보냅니다.

session권장

MFA 완료 여부와 로그인 실패·결제 시도 수로 계정 탈취 신호를 보강합니다.

4. 네트워크·속도

우회 접속, 단기 급증, 반복 결제를 탐지합니다.

network권장

국가, ASN, VPN/Proxy/Tor 여부 및 계약된 IP Prefix만 전송합니다. 원문 IP는 보내지 않습니다.

velocity권장

집계 윈도우, 일일 거래 건수와 금액을 보냅니다. 급격한 거래량 증가 탐지에 사용됩니다.

전송 후 확인

성공한 POST 응답의 ingestion_id로 GET /v1/ingestions/{ingestion_id}를 호출하세요. 202 Accepted는 수신 보장이고, 최종 평가 완료 상태는 EVALUATED입니다.