메인 콘텐츠로 건너뛰기

컨텍스트 신호

시작하기 전에​

컨텍스트 신호는 완료된 신용 거래를 평가하여 자기 사기(self-fraud) 또는 소셜 엔지니어링(social engineering)에 대한 위험 평가를 반환함으로써 자체적인 안티 사기 판단을 보완합니다.

컨텍스트 신호는 비대면 카드 검증을 보완하는 기능으로, 이미 사용 중인 거래 엔드포인트의 계약이나 동작을 변경하지 않습니다. 기존과 동일하게 거래의 최종 상태(approved, inconclusive 등)를 수신한 다음, 컨텍스트 신호를 조회하면 됩니다.

API 요청은 액세스 토큰을 사용하여 인증됩니다. 유효한 액세스 토큰을 포함하지 않는 요청은 오류를 반환합니다. 인증에서 자세히 알아보세요.

권한 기반 액세스 제어

이 엔드포인트에 대한 접근은 회사에 할당된 권한(역할)으로 제어됩니다. 권한이 없으면 엔드포인트가 403을 반환합니다. Unico 팀에 활성화를 요청하세요.

기본 URL
  • UAT: https://transactions.transactional.uat.unico.app/api/public/v1
  • 프로덕션: https://transactions.transactional.unico.app/api/public/v1

컨텍스트 신호 조회​

GET /transactions/{transaction_id}/signals — 완료된 거래의 위험 평가를 반환합니다.

결과는 거래가 최종 상태에 도달하는 즉시 비동기적으로 미리 계산되므로, 이 엔드포인트는 이미 준비된 결과를 조회하는 역할만 합니다.

경로 파라미터
파라미터타입필수설명
transaction_idstring예거래 ID(UUID v4)입니다. 예: 6ab1771e-dfab-4e47-8316-2452268e5481.
헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
Acceptapplication/json
요청 예시
GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json
200 OK
{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}
필드타입존재 여부설명
signals.auto_fraud_riskstring (enum)선택자기 사기 위험 수준입니다. 감지된 경우에만 존재합니다.
signals.social_eng_riskstring (enum)선택소셜 엔지니어링 위험 수준입니다. 감지된 경우에만 존재합니다.
signals.more_info.limited_databoolean항상신뢰할 수 있는 평가를 위한 데이터가 충분하지 않을 때 true입니다.
signals.more_info.holder_identifiedboolean항상카드 소유자를 식별할 수 없을 때 false입니다.

가능한 위험 값: very_low, low, medium, high, very_high.

정보

auto_fraud_risk와 social_eng_risk는 상호 배타적입니다 — 동일한 응답에 함께 나타나지 않습니다. limited_data가 true인 경우, 평가에 필요한 데이터가 충분하지 않으므로 두 위험 필드 모두 존재하지 않는 것이 정상입니다.

응답 예시

소셜 엔지니어링 위험이 감지된 경우:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

위험이 식별되지 않은 경우 — 일반 거래:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

데이터가 충분하지 않은 경우:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

카드 소유자를 식별할 수 없는 경우:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}
기타 응답 코드

오류는 오류에 설명된 표준 오류 형식으로 반환됩니다.

HTTP 코드코드상황조치 사항
202—결과가 아직 계산되지 않았습니다 — 비동기 처리가 진행 중입니다.200을 받을 때까지 호출을 반복하세요(폴링).
40040004transaction_id가 유효하지 않거나(UUID v4가 아님) 파라미터 형식이 잘못되었습니다.요청을 다시 보내기 전에 ID 형식을 수정하세요.
40340305회사에 이 엔드포인트에 대한 권한(역할)이 활성화되어 있지 않습니다.Unico 팀에 활성화를 요청하세요.
40440401거래를 찾을 수 없습니다.거래 ID를 확인하세요.
40440484평가 대상 거래를 찾을 수 없습니다."결과가 없을 것"으로 간주하고 조회를 중단하세요.
40940983거래가 아직 최종 상태에 도달하지 않았습니다.최종 상태에 도달할 때까지 기다린 후 다시 조회하세요.
500—내부 서비스 오류입니다.백오프를 적용하여 재시도하세요. 문제가 지속되면 Unico 지원팀에 문의하세요.

규칙 및 모범 사례​

  • 거래가 최종 상태에 도달한 후에만 엔드포인트를 조회하세요. 그 전에 조회하면 409가 반환됩니다.
  • 신용 거래만 평가 대상입니다. 사일런트 모드로 캡처된 거래는 평가되지 않습니다.
  • 202를 받으면 200을 받을 때까지 호출을 반복하세요. 거래 응답 후 1초 뒤에 첫 요청을 보내고, 이후 2초, 4초, 8초, 16초로 백오프하며 최대 5회까지 시도하세요.
  • 서비스 수준 목표는 거래 응답 후 10초입니다.
  • 404는 "결과가 없을 것"으로 간주하고 조회를 중단하세요.
  • auto_fraud_risk와 social_eng_risk는 상호 배타적입니다.
마지막 업데이트 에