Risk Assessment with Refinitiv WCO API

Risk Assessment with Refinitiv WCO API

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

The Refinitiv WCO (World Check One) API is used to assess the risk level associated with the Originator or Beneficiary. It is necessary to complete user verification (POST /verifications) before calling WCO API.

The Refinitiv WCO API allows VASPs to evaluate the risk level of the Originator/Beneficiary of a transaction. This enables VASP to perform additional risk assessments on whether the Beneficiary or Originator is a risky individual or organization.

Refinitiv World Check One API

The Refinitiv World Check One (WCO) API is a paid API that uses PII of individuals or organizations to assess the risks associated with them. Risk assessment requests are each referred to as ‘case’ and are distinguished by the ‘caseSystemId’ issued by Refinitiv. Additionally, the concept of ‘group’ is used to manage assigned cases. Each case belongs to certain group, allowing VASPs to manage effectively. Reviewing the structure of ‘group’ before using Refinitiv WCO API is strongly recommended.

In order to use Refinitiv WCO API, VASP needs to sign up on Refinitiv and purchase the product. Please approach to VerifyVASP point of contact for a referral and follow the link below to request WCO API subscription.

After acquiring Refinitiv WCO API subscription, VASP can access to WCO API key by signing in Refinitiv WCO Console. Click on Admin page > Users > User to find out the API Key and Secret after signing in.

Please refer to the following link for information on Refinitiv WCO API.

Prerequisites

Following 2 items need to be prepared in advance to use WCO API:

  1. Setting up Enclave Environment Variable

    • VEGA_REFINITIV_WCO_API_KEY : Obtain API Key from the Admin in the "Admin page > Users > User" section of the Refinitiv WCO Console Site.

    • VEGA_REFINITIV_WCO_API_SECRET : Obtain API Secret from the Admin in the "Admin page > Users > User" section of the Refinitiv WCO Console Site.

    • VEGA_REFINITIV_WCO_GROUP_ID : Create groups for case management in the Admin menu of the Refinitiv WCO Console Site.

      • The created group ID can be obtained by calling REST API. For easier API call, download the ‘postman collection’ and ‘environment’ from the Refinitiv WCO API Quick Start.

      • Call the SEQ-pre-groups: Get my top-level groups request in the Group Information folder of the postman collection. Before doing so, don’t forget to input the API Key and API Secret into the environment variables.

  2. Creating Enclave Database Table

    • The Refinitiv WCO API call histories are stored in the Enclave database. Therefore, it is necessary to create separate database table to store WCO results.

    • Please refer to the Refinitiv WCO Results Table for the table definition.

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 UUID for Travel Rule verification which will be subject to risk assessment.

payload

string

false

Used when trying to verify with additional information more than the personal information collected during the Travel Rule verification.

If additional information more than PII submitted in the Travel Rule verification is available, then use payload for risk assessment.

For example, If the Travel Rule verification only had the name of the user, but acquired additional information such as Date of Birth or Place of Birth via another channel, additional information can be added to the payload in the IVMS101 packet in the request to perform risk assessment.

Response Body

Success Cases

Response Body Examples

  • 200 OK

{
  "requestId": "f7231c6f-f1e7-4ae7-b143-2c87cd38abe9"
}
Field Name
Data Type
Required
Description

requestId

string

true

An identifier to distinguish risk assessment requests. It is different from the verificationUuid and is issued for each risk assessment.

The Refinitiv WCO operates asynchronously. Therefore, the results are not returned immediately upon calling this API. The results of the risk assessment using the Refinitiv WCO are delivered through the Callback VASP API. The risk assessment results delivered via the Callback VASP API are provided in the following format

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"
      }
    }
  }
}

When the risk assessment result is delivered, the riskAssessment property is provided, and among them, the risk assessment result using the WCO is conveyed through the refinitivWorldCheckOne property under riskAssessment.

The refinitivWorldCheckOne structure has the following attributes.

Field Name
Data Type
Required
Description

requestId

string

true

An identifier to distinguish each risk assessment request

counterpartyVaspId

string

true

Counterparty VASP’s vaspId

direction

string

true

‘OUTGOING’ for withdrawal, ‘INCOMING’ for deposit

caseSystemId

string

false

An identifier assigned by Refinitiv to distinguish each risk assessment request

status

string

true

The status of the risk assessment request; 'REGISTERED' if the results have not yet been obtained, and 'PROCESSED' if the risk assessment results are available

matchStrength

string

false

In case of a successful risk assessment, the highest matching strength among the personal information matching entries, in descending order of 'WEAK', 'MEDIUM', 'STRONG', 'EXACT'.

aggregatedSummaryResult

string

false

Summary information on the results in case of a successful risk assessment

createdAt

string

true

The time when the risk assessment history was created

assessedAt

string

false

The time when the risk assessment results were derived from Refinitiv

Failed Cases

Missing mandatory parameter case

Response Body Examples

  • 400 Bad Request

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

Incorrect 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)"
}

Invalid verificationUuid

Response Body Examples

  • 400 Bad Request

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

Incorrect GroupID

Response Body Examples

  • 404 Not Found

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

Incorrect requests

Response Body Examples

  • 400 Bad Request

{
  "code": "BAD-REQUEST",
  "message": "......"
}
PreviousRisk Assessment with Chainalysis KYT APINextUser Account Verification

Last updated