Skip to main content
Search

Get VASP Detail

By invoking GET /api/common/v3/vasp/detail?vaspCode=[vaspCode], you will get the full details of a specific VASP in the GTR network.

Response​

You can expect to receive following response.

💡 You will receive an exception with verifyStatus = 100034 if your VASP is not on the allowlist of this target vasp code.

You can request this VASP to add you to their allowlist via GTR Website.

{
    "verifyStatus": 100000,
    "verifyMessage": "Success",
    "data": {
        "vaspCode": "lDPwXEIe6r1jZp5TdTfyI",
        "vaspEntitySlug": "axchange-us",
        "vaspEntityName": "Axchange USA",
        "allianceName": "Smile Travel Rule",
        "country": "US",
        "availability": 0,
        "couldPending": true,
        "supportedVerifyFields": [
            {
                "id": "IVMS101_LEGALPERSON_NAME_NAMEIDENTIFIER",
                "name": "Legal Person Name"
            }
        ],
        "requiredPiiFields": {
            "originatorLegalPerson": null,
            "beneficiaryLegalPerson": null,
            "beneficiaryNaturalPerson": null,
            "originatorNaturalPerson": {
                "and": [
                    {
                        "metadata": {
                            "fieldId": "100026",
                            "name": "Natural Person Name"
                        },
                        "operator": "equal"
                    },
                    {
                        "metadata": {
                            "fieldId": "100024",
                            "name": "Natural Person Place of Birth"
                        },
                        "operator": "equal"
                    },
                    {
                        "operator": "or",
                        "or": [
                            {
                                "metadata": {
                                    "fieldId": "100029",
                                    "name": "Natural Person Address - Country"
                                },
                                "operator": "equal"
                            },
                            {
                                "metadata": {
                                    "fieldId": "100048",
                                    "name": "Natural Person Country of Residence"
                                },
                                "operator": "equal"
                            },
                            {
                                "and": [
                                    {
                                        "metadata": {
                                            "fieldId": "100028",
                                            "name": "Natural Person Phonetic Name"
                                        },
                                        "operator": "equal"
                                    },
                                    {
                                        "metadata": {
                                            "fieldId": "100024",
                                            "name": "Natural Person Place of Birth"
                                        },
                                        "operator": "equal"
                                    }
                                ],
                                "operator": "and"
                            }
                        ]
                    },
                    {
                        "operator": "or",
                        "or": [
                            {
                                "and": [
                                    {
                                        "metadata": {
                                            "fieldId": "100046",
                                            "name": "Natural Person National ID - Country Of Issue"
                                        },
                                        "operator": "equal"
                                    },
                                    {
                                        "metadata": {
                                            "fieldId": "100044",
                                            "name": "Natural Person National ID - Type"
                                        },
                                        "operator": "equal"
                                    }
                                ],
                                "operator": "and"
                            },
                            {
                                "and": [
                                    {
                                        "metadata": {
                                            "fieldId": "100044",
                                            "name": "Natural Person National ID - Type"
                                        },
                                        "operator": "equal"
                                    },
                                    {
                                        "metadata": {
                                            "fieldId": "100029",
                                            "name": "Natural Person Address - Country"
                                        },
                                        "operator": "equal"
                                    }
                                ],
                                "operator": "and"
                            }
                        ]
                    }
                ],
                "operator": "and"
            }
        },
        "standardInfo": {
            "publicKeyInfo": {
                "receiverKeyInfo": {
                    "publicKey": "-----BEGIN CERTIFICATE-----\nMIICpzCC...."
                },
                "secretAlgorithm": "ed25519_curve25519"
            },
            "supportedPiiSpecInfo": {
                "piiSpecVersion": "ivms101-2020"
            },
            "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT"
        }
    }
}

Attributes wrapped by this response body is vital for you to initiate a Travel Rule request via One-Step API. Please see the section below to know how to digest this response.

  • [TARGET_VASP_CODE]
  • [TARGET_ALGORITHM]
  • [TARGET_PII_SPEC_VERSION]
  • [TARGET_PII_SECRET_FORMAT_TYPE]
  • [MY_PRIVATE_KEY]
  • [MY_PUBLIC_KEY]
  • [THEIR_PUBLIC_KEY]

Please note that even if a VASP supports multiple algorithms, GTR will only select the most suitable one, with the following priority:

  • (Highest priority) ed25519_curve25519
  • The other algorithms are selected in the order they are added to the public key

Simply, if a VASP supports the ed25519_curve25519 algorithm, you will always get this type.

Example: Fallback when ed25519_curve25519 is not shared by both sides​

If either side does not support ed25519_curve25519, GTR will pick another algorithm both sides support. For example, when both VASPs only share rsa_ecb_oaep_with_sha1_and_mgf1padding, the response will look like:

"standardInfo": {
    "publicKeyInfo": {
        "receiverKeyInfo": {
            "publicKey": "-----BEGIN CERTIFICATE-----\nMIICpzCC...."
        },
        "secretAlgorithm": "rsa_ecb_oaep_with_sha1_and_mgf1padding"
    },
    ...
}

Digest Response​

Please set up the global variables in your code-base or service environment, the structure is recommended to be like the following:

// please setup these information on your program
const myENV = {
  "supportedSecretAlgorithm" : {
    "ed25519_curve25519" : {
      "publicKey": "",
      "privateKey": ""
    },
    "rsa" : {
      "publicKey": "",
      "privateKey": ""
    },
  },
  "supportedPiiSpecVersion": {
    "ivms101-2020": {},
    "ivms101-2023": {}
  },
  "supportedPiiSecretFormatType": [
    "FULL_JSON_ENCRYPTION"
  ]
}

The public key and private key store format please refer to Secret Algorithm in GTR

Your VASP service must support these algorithm, PII format and PII encrypt format, and your server can route to the corresponding logic to process the verification request.

For TARGET_VASP_CODE​

Set the vaspCode from the response as [TARGET_VASP_CODE]:

const TARGET_VASP_CODE = response.data.vaspCode

For TARGET_ALGORITHM​

Use your myENV.supportedSecretAlgorithm and match it with response.data.standardInfo.publicKeyInfo.secretAlgorithm, then: i. Select your private key as [MY_PRIVATE_KEY] ii. Select their public key as [THEIR_PUBLIC_KEY] iii. Select the algorithm as [TARGET_ALGORITHM] iv. Select your public key as [MY_PUBLIC_KEY]

const TARGET_ALGORITHM = response.data.standardInfo.publicKeyInfo.secretAlgorithm

const selectedAlgorithmFromMyENV = myENV.supportedSecretAlgorithm[TARGET_ALGORITHM]

if(selectedAlgorithmFromMyENV == null) {
    throw new Error("no support algorithm")
}

const MY_PRIVATE_KEY = selectedAlgorithmFromMyENV.privateKey
const MY_PUBLIC_KEY = selectedAlgorithmFromMyENV.publicKey

const THEIR_PUBLIC_KEY = response.data.standardInfo.publicKeyInfo.receiverKeyInfo.publicKey

For TARGET_PII_SPEC_VERSION​

Use your myENV.supportedPiiSpecVersion to check if response.data.standardInfo.supportedPiiSpecInfo.piiSpecVersion is supported, and save it to a variable as [TARGET_PII_SPEC_VERSION] for later use:

const TARGET_PII_SPEC_VERSION = response.data.standardInfo.supportedPiiSpecInfo.piiSpecVersion
if(myENV.supportedPiiSpecVersion[TARGET_PII_SPEC_VERSION] == null) {
    throw new Error("no support pii spec version")
}

For TARGET_PII_SECRET_FORMAT_TYPE​

Use your myENV.supportedPiiSecretFormatType to check if response.data.standardInfo.piiSecretFormatType is supported, and save it to a variable as [TARGET_PII_SECRET_FORMAT_TYPE] for later use:

const TARGET_PII_SECRET_FORMAT_TYPE = response.data.standardInfo.piiSecretFormatType

if(TARGET_PII_SECRET_FORMAT_TYPE not in myENV.supportedPiiSecretFormatType) {
    throw new Error("not support pii secret format type")
}

About couldPending​

The counter-party VASP may enter a pending flow. The pending flow can occur in two stages as shown in the table below:

ScenarioStage SequenceStage Name
Pre-transaction Travel RuleStage 1Address Verification Pending
Pre-transaction Travel RuleStage 2PII Verification Pending
Post-transaction Travel RuleStage 1TX Verification Pending
Post-transaction Travel RuleStage 2PII Verification Pending

Each stage can be pending. If your compliance requirements only require submitting PII to the counter-party VASP before starting the transaction (without verifying PII), we suggest not proceeding with the transaction if Stage 1 is pending or failed. Refer to the table below for details on each property.

ScenarioStageSend Out PIIVerify PIICan Block Transaction
Pre-transaction Travel RuleAddress Verification PendingNoNoNo Transaction
Pre-transaction Travel RulePII Verification PendingSentNoStart Transaction
Post-transaction Travel RuleTX Verification PendingNoNoTransaction Already Done
Post-transaction Travel RulePII Verification PendingSentNoTransaction Already Done

If you don't want to transact with VASPs that have couldPending=true, you can filter them out.

Next​

Now, you have completed the most important variable digestion, you are ready to initiate a Travel Rule via One-Step API

💡 GTR Implementation Recommendations

  • Always invoke this VASP Detail API before initiating any Travel Rule transaction with a target VASP. This ensures you have the latest and most accurate information about the target VASP's encryption algorithm and public keys.
  • The publicKeyInfo section provides the public key and encryption algorithm that you must use to encrypt sensitive travel rule data before sending it to the target VASP.
  • The supportedFeatures, supportedVerifyFields, and requiredPiiFields fields inform you about the verification capabilities and required Personally Identifiable Information (PII) fields for the beneficiary.
  • The availability field indicates whether the VASP is currently available to receive travel rule data.
  • The standardInfo section also includes the PII specification version (piiSpecVersion) and the format type for encrypted PII data (piiSecretFormatType), which you should comply with when preparing data.

Reference Supported Verify Fields​

Each id in supportedVerifyFields identifies an IVMS101 field path that the target VASP is able to verify. When you actually request verification (e.g., expectVerifyFields) or return verification results (verifyFields), you use the numeric verify field codes defined in PII Verify Fields. The applicable codes depend on the role your VASP plays in the transaction — please refer to the mapping tables below.

Verify Field IDas Originator VASPas Beneficiary VASP
IVMS101_LEGALPERSON_NAME_NAMEIDENTIFIER101001111001
IVMS101_LEGALPERSON_NATIONALIDENTIFICATION_NATIONALIDENTIFIERTYPE101002111002
IVMS101_LEGALPERSON_NATIONALIDENTIFICATION_NATIONALIDENTIFIER101003111003
IVMS101_LEGALPERSON_NATIONALIDENTIFICATION_REGISTRATIONAUTHORITY101004111004
IVMS101_LEGALPERSON_NATIONALIDENTIFICATION_COUNTRYOFISSUSE101005111005
IVMS101_LEGALPERSON_CUSTOMER_IDENTIFICATION101006111006
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_COUNTRY101007111007
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_TOWNNAME101008111008
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_ADDRESSLINE101009111009
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_DEPARTMENT101010111010
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_SUBDEPARTMENT101011111011
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_STREETNAME101012111012
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_BUILDINGNUMBER101013111013
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_BUILDINGNAME101014111014
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_FLOOR101015111015
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_POSTBOX101016111016
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_ROOM101017111017
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_POSTCODE101018111018
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_TOWNLOCATIONNAME101019111019
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_DISTRICTNAME101020111020
IVMS101_LEGALPERSON_GEOGRAPHICADDRESS_COUNTRYSUBDIVISION101021111021
IVMS101_LEGALPERSON_COUNTRYOFREGISTRATION101022111022

Natural Person Fields​

Verify Field IDas Originator VASPas Beneficiary VASP
IVMS101_NATURALPERSON_DATEANDPLACEOFBIRTH_PLACEOFBIRTH100024110024
IVMS101_NATURALPERSON_DATEANDPLACEOFBIRTH_DATEOFBIRTH100025110025
IVMS101_NATURALPERSON_NAME_NAMEIDENTIFIER100026110026
IVMS101_NATURALPERSON_NAME_LOCALNAMEIDENTIFIER100027110027
IVMS101_NATURALPERSON_NAME_PHONETICNAMEIDENTIFIER100028110028
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_COUNTRY100029110029
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_TOWNNAME100030110030
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_ADDRESSLINE100031110031
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_DEPARTMENT100032110032
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_SUBDEPARTMENT100033110033
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_STREETNAME100034110034
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_BUILDINGNUMBER100035110035
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_BUILDINGNAME100036110036
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_FLOOR100037110037
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_POSTBOX100038110038
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_ROOM100039110039
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_POSTCODE100040110040
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_TOWNLOCATIONNAME100041110041
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_DISTRICTNAME100042110042
IVMS101_NATURALPERSON_GEOGRAPHICADDRESS_COUNTRYSUBDIVISION100043110043
IVMS101_NATURALPERSON_NATIONALIDENTIFICATION_NATIONALIDENTIFIERTYPE100044110044
IVMS101_NATURALPERSON_NATIONALIDENTIFICATION_NATIONALIDENTIFIER100045110045
IVMS101_NATURALPERSON_NATIONALIDENTIFICATION_COUNTRYOFISSUSE100046110046
IVMS101_NATURALPERSON_CUSTOMERIDENTIFICATION100047110047
IVMS101_NATURALPERSON_COUNTRYOFRESIDENCE100048110048

Other Fields​

Verify Field IDas Originator VASPas Beneficiary VASP
IVMS101_ACCOUNTNUMBER103023113023