> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 거래 IP 정보 보강: 국가, ASN, VPN

> Didit은 모든 거래에 국가, ASN, VPN, Tor, 데이터센터, 통신사 등 IP 정보를 보강합니다. 월 1,000건 포함, 이후 건당 $0.001.

모든 거래 중 기기 IP 주소를 포함하는 거래는 규칙이 평가되기 전에 서버에서 실시간으로 보강됩니다. 보강을 통해 국가, 도시, VPN/Tor/데이터 센터 플래그, ASN, 통신사 정보가 추가되며, 이 모든 값은 규칙 조건으로 사용할 수 있습니다.

## 보강이 실행되는 시점

거래 생성 중 인라인으로 실행됩니다.

1. `POST /v3/transactions/`에 `subject.device_context.network_context.ip_address`(또는 어느 당사자의 기기 IP 주소든)를 포함하여 요청합니다.
2. Didit은 인메모리 캐시(TTL 24시간)에서 IP 주소를 조회합니다.
3. 캐시에 없으면 공유 IP 보강 테이블(약 30일 동안 최신 상태 유지)을 확인합니다.
4. 데이터가 오래되었거나 없으면 여러 제공자 간 장애 조치를 지원하는 Didit 보강 파이프라인으로 IP 주소를 확인합니다.
5. 보강된 필드를 거래 기록에 기록하고 규칙에서 사용할 수 있도록 합니다.

보강은 **인라인**으로 진행됩니다. 즉 규칙이 실행되기 전에 완료됩니다. 다만 실패 시 **차단하지 않습니다**. 보강을 완료하지 못하더라도 거래는 계속 진행되며, IP 주소는 보강 데이터 없이 표시됩니다.

## 보강 필드

| 필드 | 설명 |
| - | - |
| `ip_country` | 국가 이름 |
| `ip_country_code` | Didit이 확인한 경우 ISO 3166-1 alpha-2 코드입니다(제출한 값은 그대로 유지됩니다). 규칙 조건은 두 형식을 모두 정규화합니다. |
| `ip_state` | 행정 구역(주, 지역) |
| `ip_city` | 도시 이름 |
| `latitude`, `longitude` | 지리 좌표 |
| `isp` | 인터넷 서비스 제공자 이름 |
| `organization` | 등록 조직 이름 |
| `is_vpn_or_tor` | 불리언 값입니다. IP가 알려진 VPN 또는 Tor 출구 노드이면 true입니다. |
| `is_data_center` | 불리언 값입니다. IP가 호스팅/데이터 센터 대역에 속하면 true입니다. |
| `time_zone` | IANA 시간대(예: `America/New_York`) |
| `time_zone_offset` | UTC와의 오프셋 |
| `asn_number` | 자율 시스템 번호(ASN) |
| `asn_organization` | ASN에 등록된 조직 |
| `connection_type` | `mobile`, `broadband`, `dialup`, `corporate`, ... |
| `carrier` | 이동통신사(모바일 IP의 경우) |
| `proxy_type` | `VPN`, `TOR`, `PUBLIC_PROXY`, 또는 null |

## 규칙에서 보강 필드 사용하기

보강 필드는 모두 [규칙 조건](https://docs.didit.me/ko/transaction-monitoring/rules.md)으로 사용할 수 있습니다. 자주 쓰는 패턴은 다음과 같습니다.

**IP 기준 고위험 관할 지역**

```
condition: applicant.ip_country_code IN ['IRN', 'PRK', 'SYR']
action: add_score(35), add_tags(['high_risk_ip_country'])
```

**VPN / Tor 사용**

```
condition: applicant.is_vpn_or_tor == true
action: change_status('IN_REVIEW'), add_tags(['anonymization'])
```

**데이터 센터 / 비주거 출처**

```
condition: applicant.is_data_center == true AND amount > 10000
action: add_score(30)
```

**IP 국가 ≠ KYC 국가**

```
condition: applicant.ip_country_code != applicant.country_code
action: add_score(15), add_tags(['geo_mismatch'])
```

## 캐시 계층

| 계층 | TTL | 목적 |
| - | - | - |
| 인메모리 캐시 | 24시간 | 자주 조회되는 IP를 밀리초 미만으로 조회 |
| 공유 IP 보강 테이블 | 약 30일 | 인스턴스 간 공유되며, 다시 확인하는 것보다 비용이 적음 |
| 보강 파이프라인 | 해당 없음 | 다른 곳에 데이터가 없을 때 최신 데이터 제공 |

처음 두 계층에서 조회가 적중하면 추가 비용이 발생하지 않습니다. 새로 확인하는 작업에는 과금될 수 있으니 결제 콘솔에서 확인하십시오.

## 실패 시 동작

* 보강이 실패해도 거래 생성은 **절대 실패하지 않습니다**.
* 보강 필드가 누락되면 해당 필드를 참조하는 규칙 조건과 일치하지 않을 뿐입니다.
* 보강이 정체되었다는 알림은 내부 모니터링을 통해 운영팀에 전달되며, 고객에게 영향을 주지 않습니다.

## 유효성 필터링

라우팅할 수 없는 IP 주소는 보강 전에 건너뜁니다.

* 사설 주소(10/8, 172.16/12, 192.168/16)
* 루프백(127/8)
* 링크 로컬(169.254/16)
* 멀티캐스트 및 미지정 주소

이렇게 하면 제공자 할당량을 아끼고 의미 없는 보강 데이터가 생성되는 것을 막을 수 있습니다.

## 거래의 보강 결과 확인하기

**API를 통해.** 별도의 보강 블록은 없습니다. 보강 필드는 제출한 `ip_address` 옆, `parties` 배열에서 해당 항목의 당사자별 `device.network_context` 객체에 기록됩니다.

```json theme={null}
"parties": [
  {
    "role": "APPLICANT",
    "vendor_data": "user-42",
    "device": {
      "network_context": {
        "ip_address": "203.0.113.5",
        "ip_country": "United States",
        "ip_country_code": "US",
        "ip_state": "California",
        "ip_city": "San Francisco",
        "is_vpn_or_tor": false,
        "is_data_center": false,
        "asn_number": 64496,
        "asn_organization": "Example ISP",
        "proxy_type": null
      }
    }
  }
]
```

요청에서 제공한 필드는 유지되며, 보강은 생략된 키만 채웁니다. 확인 결과가 비어 있던 키는 생략됩니다. 전체 `device` 구조는 [응답 스키마](https://docs.didit.me/ko/transaction-monitoring/response-schema.md#device)를 참조하십시오.

**콘솔에서.** 거래 상세 페이지의 **IP 및 기기** 탭에서 지도 핀과 함께 IP 보강 정보를 확인할 수 있습니다.

## 개인정보 보호 고려 사항

* 원시 IP 주소는 거래와 함께 저장됩니다.
* 보강 데이터는 사용자별이 아니라 IP 키 기반의 공유 테이블에 저장됩니다.
* 잊힐 권리에 따른 삭제를 수행하면 거래에서 IP 주소가 제거됩니다. 다만 공유 캐시 항목은 남으며, 개인을 식별하지 않는 정보이기 때문입니다.

## 다음 단계

> [card] [규칙](https://docs.didit.me/ko/transaction-monitoring/rules.md)
>
> 조건에서 보강 필드를 사용합니다.

> [card] [규칙 라이브러리](https://docs.didit.me/ko/transaction-monitoring/rules-library.md)
>
> IP 기반 사전 설정 규칙을 확인합니다.

> [card] [응답 스키마](https://docs.didit.me/ko/transaction-monitoring/response-schema.md)
>
> IP 보강 정보가 표시되는 위치를 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.