Refinitiv WCO 기능을 이용한 위험 평가 API

Refinitiv WCO를 이용한 위험 평가

POST http://<enclave-endpoint>/v1/risk-assessment/refinitiv-wco

Refinitiv WCO (World Check One) API는 Refinitiv 서비스와 연계하여 송신자나 수신자에 대한 위험도를 평가하기 위해 사용하는 API입니다.

WCO API를 호출하기 위해서는 반드시 먼저 사용자 검증(POST /verifications)을 완료해야 합니다.

Refinitiv WCO API를 활용하면 거래 상대방이 위험한 인물이나 조직인지를 평가할 수 있습니다. 이를 통해 사용자 검증 후 거래 상대방에 대한 추가적인 위험 평가를 수행할 수 있으며 신뢰할 수 있는 고객에게 가상 자산을 전송할 수 있게끔 지원합니다.

Refinitiv World Check One API 란

Refinitiv World Check One (WCO) API는 개인 식별 정보를 활용하여 개인 또는 법인의 위험 평가를 수행하는 유료 기반 API입니다. 위험 평가 요청은 각각 "case"로 지칭되며, Refinitiv에서 할당한 "caseSystemId"를 통해 구분됩니다. 또한, "group"이라는 개념을 사용하여 case 할당을 관리합니다. 각 case는 하나의 group에 속하며, 이를 통해 효율적인 관리가 가능합니다. Refinitiv WCO API를 통합 기능으로 사용하기 전에 group 구조를 검토하는 것을 권장합니다.

Refinitiv WCO 통합 기능을 사용하기 위해서는 Refinitiv에 회원가입하고 라이센스를 구매해야 합니다. 아래 링크를 통해 Refinitiv에 문의하여 WCO API 라이센스를 구매하시거나 또는 VerifyVASP팀에 별도로 문의주시면 Refinitiv 팀과의 미팅 진행을 도와드리겠습니다.

• Refinitiv World Check One

Refinitiv WCO API 라이센스를 구입한 후, WCO 콘솔 사이트에 로그인하여 WCO API Key를 발급받을 수 있습니다. 로그인 후 "Admin page > Users > 사용자"를 클릭하면 해당 사용자의 세부 정보에서 API Key와 Secret이 표시됩니다.

• Refinitiv WCO Console Site

Refinitiv WCO API에 대한 자세한 내용은 아래 링크에서 확인하실 수 있습니다.

• Refinitiv WCO API Overview

• Refinitiv WCO API Reference

사전 준비 사항

이 기능을 사용하기 위해서는 아래의 2가지 사항을 미리 준비해야 합니다.

1. Enclave 환경 변수 설정

   • VEGA_REFINITIV_WCO_API_KEY : Refinitiv WCO Console Site의 Admin page > Users > 사용자를 클릭하면 세부 정보에서 API Key를 확인할 수 있습니다.

   • VEGA_REFINITIV_WCO_API_SECRET : Refinitiv WCO Console Site의 Admin page > Users > 사용자를 클릭하면 세부 정보에서 API Secret를 확인할 수 있습니다.

   • VEGA_REFINITIV_WCO_GROUP_ID : Refinitiv WCO Console Site의 Admin 메뉴에서 case 관리를 위한 group을 생성할 수 있습니다.

     • 생성된 group에 대한 group ID는 REST API 호출을 통해 확인할 수 있습니다. 쉬운 API 호출을 위해 Refinitiv WCO API Quick Start에서 postman collection 과 environment를 다운로드하세요.

     • 위 postman collection 중에서 Group Information 폴더의 SEQ-pre-groups: Get my top-level groups 요청을 호출하면 됩니다. 그전에 API Key 와 API Secret을 environment 변수에 입력하는 것을 잊지 마십시오.

2. Enclave 데이터베이스 테이블 생성

   • Refinitiv WCO API 호출 이력들이 enclave 데이터베이스에 저장됩니다. 따라서 이를 위한 데이터베이스 테이블을 따로 생성해야 합니다.

   • 테이블 정의는 Refinitiv WCO Results 테이블을 참고하시기 바랍니다.

Request Body

Request Body Examples

{
  "verificationUuid": "d63398e3-c806-4300-bd99-170b54642080",
  "payload": {
    "version": "1.0",
    "ivms101": {
      "originator": {
        "originatorPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "James",
                    "secondaryIdentifier": "Din",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["1P8j2mhMszoC7P69oqZF2n8fLK3TL3wFgJ"]
      },
      "beneficiary": {
        "beneficiaryPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Robbins",
                    "secondaryIdentifier": "Taylor",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["1G3qCGKP5dQtQ7secCPTCDPU9Wfjp9x3Hb"]
      }
    }
  }
}

Field Name	Data Type	Required	Description
verificationUuid	string	true	위험 평가를 수행할 사전에 수행했던 트래블룰 검증 (verification)의 verificationUuid
payload	string	false	사전에 수행한 트래블룰 검증(verification)의 개인 정보보다 더 추가된 개인 정보로 검증하려고 할 때 입력

만약 이전에 수행된 트래블룰 검증에 기록된 개인 정보보다 더 자세한 개인 정보를 획득했을 경우 payload를 사용할 수 있습니다.

예를 들어 사전 트래블룰 검증에서는 상대방 거래자에 대한 이름 정보밖에 없었는데, 다른 경로를 통해 생년월일이나 출생지와 같은 추가 정보를 획득한 경우, 추가된 개인 정보까지 포함하여 위험 평가를 수행하려면 payload에 추가된 개인 정보까지 포함된 ivms101을 기입할 수 있습니다.

Response Body

성공 케이스

Response Body Examples

• 200 OK

{
  "requestId": "f7231c6f-f1e7-4ae7-b143-2c87cd38abe9"
}

Field Name	Data Type	Required	Description
requestId	string	true	위험 평가 요청을 구분하기 위한 식별자. verificationUuid 와는 다르며, 위험 평가를 요청할 때마다 새로 부여된다.

Refinitiv WCO 기능은 비동기적으로 동작합니다. 따라서 이 API를 호출하는 즉시 결과가 반환되지 않습니다. Refinitiv WCO 기능을 이용한 위험 평가 결과는 Callback VASP API를 통해 전달됩니다. Callback VASP API로 전달되는 위험 평가 결과는 다음과 같은 형식으로 전달됩니다.

Request Body Example for REFINITIV_WCO_RESULT callbackType

{
  "callbackType": "REFINITIV_WCO_RESULT",
  "data": {
    "verificationUuid": "69a310e6-810f-4a31-83d1-bcdafccf5304",
    "riskAssessment": {
      "refinitivWorldCheckOne": {
        "requestId": "f7231c6f-f1e7-4ae7-b143-2c87cd38abe9",
        "counterpartyVaspId": "15952089931162058999",
        "direction": "INCOMING",
        "caseSystemId": "5jb7r2c9xjfk1hoc95gfayv6m",
        "status": "PROCESSED",
        "matchStrength": "EXACT",
        "aggregatedSummaryResult": "{\"caseId\":\"69a310e6-810f-4a31-83d1-bcdafccf5304-INCOMING-1684413585757\", ... }}}",
        "createdAt": "2023-05-18T12:39:48.000Z",
        "assessedAt": "2023-05-18T12:39:57.834Z"
      }
    }
  }
}

위험 평가 결과가 전달될 때 riskAssessment property가 전달되며 그중에 WCO 기능을 이용한 위험 평가 결과는 riskAssessment 하위의 refinitivWorldCheckOne property를 통해 전달됩니다.

refinitivWorldCheckOne 구조체는 다음과 같은 속성들을 가집니다.

Field Name	Data Type	Required	Description
requestId	string	true	각각의 위험 평가 요청을 구분하기 위한 식별자
counterpartyVaspId	string	true	거래 상대방 VASP의 ID
direction	string	true	출금일 경우 "OUTGOING", 입금일 경우에는 "INCOMING"
caseSystemId	string	false	각 위험 평가 요청을 구분하기 위해 Refinitiv에서 부여한 식별자
status	string	true	위험 평가 요청의 상태, 아직 결과가 나오지 않았으면 "REGISTERED", 위험 평가 결과가 나왔으면 "PROCESSED"
matchStrength	string	false	위험 평가가 성공한 경우, 개인 정보 매칭 건 중에서 가장 높은 매칭률을 보인 건의 매칭 강도, 낮은 순서대로 "WEAK", "MEDIUM", "STRONG", "EXACT"
aggregatedSummaryResult	string	false	위험 평가가 성공한 경우, 결과에 대한 요약 정보
createdAt	string	true	위험 평가 이력이 만들어진 시간
assessedAt	string	false	Refinitiv로부터 위험 평가 결과가 도출된 시간

실패 케이스

필수 파라미터를 입력하지 않은 경우

Response Body Examples

• 400 Bad Request

{
  "code": "MISSING-VERIFICATION-UUID",
  "message": "`verificationUuid` is required."
}

API Key가 올바르지 않을 경우

Response Body Examples

• 401 Unauthorized

{
  "code": "UNKNOWN-ERROR-CODE",
  "message": "Failed to call POST Refinitiv API(https://api-worldcheck.refinitiv.com/v2/cases) for identifier(James Lim)"
}

존재하지 않는 verificationUuid인 경우

Response Body Examples

• 400 Bad Request

{
  "code": "NOT-FOUND-VERIFICATION",
  "message": "Verification(8d729bf4-38db-471d-b052-896f8660916a) is not found"
}

Group ID를 잘 못 입력한 경우

Response Body Examples

• 404 Not Found

{
  "code": "GROUP_NOT_FOUND",
  "message": "Access to the Group is denied or the Group ID is not found."
}

기타 잘못된 요청인 경우

Response Body Examples

• 400 Bad Request

{
  "code": "BAD-REQUEST",
  "message": "......"
}