Overview

Use this method to retrieve the transaction information using the externalTxnId (a transaction identifier on your side).

Response explained

The response is a JSON file that represents the structured transaction information available in the Sumsub system. The existence of some fields depends on the transaction type and matched rules.

Below, you can see the response structure and possible content with descriptions:

Root variables
data
review
scoringResult
- matchedRules
travelRuleInfo

Root variables

The following table explains the root variables that represent the core transaction data items. Some of them may include nested attributes and element fields.

Field	Type	Description
`id`	String	Unique transaction identifier in the Sumsub system.
`applicantId`	String	Unique applicant identifier in the Sumsub system (`applicantId`). This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant profile is created on the Sumsub side.
`externalUserId`	String	Unique transaction participant identifier as it is registered on your side.
`clientId`	String	Unique identifier of you as our client in the Sumsub system. This identifier is assigned to you when you are registered in and get access to the Sumsub system. It usually resembles your name or your company name. `clientId` is automatically added to the applicant profile when it is created.
`data`	Object	Transaction-related data submitted to Sumsub by the user. This data includes such details as transaction identifier, date and time when the transaction was initiated on the user side, financial information, transaction participants, and so on.
`score`	Integer	Transaction score based on the triggered rules.
`review`	Object	Explains the details of transaction status and check result.
`createdAt`	Date	Date and time (UTC) when a transaction was created in the Sumsub system.
`scoringResult`	Object	Includes an overall scoring result and its details.
`txnInactive`	Boolean	If this field returns `true`, the applicant profile associated with the transaction is deleted.

`data` attributes

The following table explains the data object fields which represent the transaction-related data submitted to Sumsub by the user. This data includes such details as transaction identifier, date and time when the transaction was initiated on the user side, financial information, transaction participants, and so on.

Field	Type	Description
`txnId`	String	Transaction identifier (`externalTxnId`) as it is on your side.
`txnDate`	Date	The date and time (UTC) when a transaction was initiated on your side (format `yyyy-MM-dd HH:mm:ss+XXXX` , for example, `2022-10-25 22:30:02+0000`).
`applicant`	Object	Includes the data of the financial transaction participant registered in the Sumsub system as an applicant. This data is submitted to Sumsub within the transaction and may differ from the relevant applicant profile. The applicant can be a sender or remitter depending on the `info.direction` parameter.
`counterparty`	Object	Includes the data related to the other party that participates in the financial transaction. This data is submitted to Sumsub within the transaction. The counterparty can be a sender or remitter depending on the `info.direction` parameter.
`type`	String	Transaction type. Expects values: `finance`(default) `gamblingBet` `gamblingLimitChange` `gamblingBonusChange` `kyc` `travelRule` `userPlatformEvent` `login` `signup` `passwordChange` `twoFaReset`
`info`	Object	Transaction-related financial information.
`props`	Map of strings	Map of strings in JSON format with custom keys and string values. Represents transaction properties.

`data.applicant` attributes

The following table explains the data.applicant object fields which contain the data of the financial transaction participant registered in the Sumsub system as an applicant. This data is submitted to Sumsub within a transaction and may differ from the relevant applicant profile.

An applicant can be a sender or remitter depending on the info.direction parameter.

Field	Type	Description
`externalUserId`	String	Unique applicant identifier as it is on your side. You can generate and add it manually when creating an applicant. If not, the external user ID is added automatically.
`fullName`	String	Applicant full name.
`dob`	Date	Date of birth (format `yyyy-mm-dd`).
`placeOfBirth`	String	Place of birth. This can be a city, a town or another settlement type.
`address`	Object	Applicant actual address details (if provided).
`type`	Enum	Applicant entity type: `individual` or `company`.
`paymentMethod`	Object	Payment method used by the applicant.
`paymentMethodExtractedInfo`	Object	Payment method information extracted from available data (represents the type that could be `smartContract`, `bankCard`, or `bankAccount`).
`device`	Object	Technical data of the device used by the applicant to complete a transaction.
`institutionInfo`	Object	Information regarding the financial institution through which the applicant made a transaction.
`institutionExtractedInfo`	Object	Financial institution information extracted from available data. Stands for BIC country.

`data.counterparty` attributes

The following table explains the data.counterparty object fields which contain the data related to the other party that participates in the financial transaction. This data is submitted to Sumsub within a transaction.

A counterparty can be a sender or remitter depending on the info.direction parameter.

Field	Type	Description
`externalUserId`	String	Unique user identifier as it is on your side.
`fullName`	String	Counterparty full name.
`dob`	Date	Date of birth (format `yyyy-mm-dd`).
`placeOfBirth`	String	Place of birth. This can be a city, a town or another settlement type.
`address`	Object	Counterparty actual address details (if provided).
`type`	Enum	Counterparty entity type: `individual` or `company`.
`paymentMethod`	Object	Payment method used by a counterparty.
`paymentMethodExtractedInfo`	Object	Payment method information extracted from available data (represents the type that could be `smartContract`, `bankCard`, or `bankAccount`).
`device`	Object	Technical data of the device used by a counterparty to complete a transaction.
`institutionInfo`	Object	Information regarding the financial institution through which a counterparty made a transaction.
`institutionExtractedInfo`	Object	Financial institution information extracted from available data. Stands for BIC country.

`address` attributes

The following table includes the details of the actual address (if provided). The address may be associated with a user, a device in use, a financial institution, and so on, depending on the object to which the address parameter refers.

Field	Type	Description
`buildingName`	String	Building name.
`flatNumber`	String	Flat or apartment number.
`subStreet`	String	Additional information related to the street. This could be a house number or any other details.
`subStreetEn`	String	Automatic transliteration of the additional information related to the street into Latin characters.
`street`	String	Street name.
`streetEn`	String	Automatic transliteration of the street name into Latin characters.
`state`	String	State, region, district, county or another territorial entity inside a country.
`stateEn`	String	Automatic transliteration of the territorial entity into Latin characters.
`buildingNumber`	String	Building number.
`town`	String	City, town, or another settlement.
`townEn`	String	Automatic transliteration of the settlement into Latin characters.
`postCode`	String	Address postal code.
`country`	String	Alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`formattedAddress`	String	Address in a human readable format. For example, `Design Offices, Philipsbornstraße 2, 30165 Hannover, Germany`.

`paymentMethod` attributes

The following table explains the details of the payment method used by the transaction participant.

Field	Type	Description
`type`	String	Payment method type: `card` / `account` / `crypto`.
`accountId`	String	Representation of the account ID: account number, IBAN/BIC or DC hash for `card`, crypto wallet address for `crypto` type, smart contract or not, and so on.
`issuingCountry`	String	Payment issuing country code in Alpha-3 format (ISO 3166-1). For example, `DEU`, `GBR`, `ARG`, and so on.
`3dsUsed`	Boolean	Indicates if 3d secure authentication was used.
`2faUsed`	Boolean	Indicates if 2FA (two-factor authentication) was used.

`device` attributes

The following table explains the specifications associated with the device used by the transaction participant to complete a transaction.

Field	Type	Description
`ipInfo`	Object	Includes the data related to the used IP address.
`userAgent`	String	Device user-agent.
`sessionId`	String	Identifier of the transaction session.
`sessionAgeMs`	Long	The session lifetime in milliseconds.
`acceptLang`	String	Language of the browser used by a transaction participant, e.g. `en`.
`platform`	String	Device platform, e.g. `Mobile Android`.
`coords`	Object	Geographical coordinates.
`address`	Object	The address related to a device.
`fingerprint`	String	Device fingerprint.

`ipInfo` attributes

This table explains the data elements associated with the IP address.

Field	Type	Description
`ip`	String	IP address.
`countryCode2`	String	Country code (ISO 3166-1 alpha-2).
`countryCode3`	String	Country code (ISO 3166-1 alpha-3).
`city`	String	City the IP address belongs to.
`zipCode`	String	ZIP code.
`lat`	Double	Represents the position latitude in decimal degrees.
`lon`	Double	Represents the position longitude in decimal degrees.
`asn`	Integer	Autonomous System Number.
`asnOrg`	String	ASN organization.
`riskyAsn`	Boolean	A value determining whether ASN is risky (`true`) or not (`false`).

`coords` attributes

This table describes the data elements representing geographical coordinates.

Field	Type	Description
`lat`	Double	Represents the position's latitude in decimal degrees.
`lon`	Double	Represents the position's longitude in decimal degrees.
`accuracy`	Double	Represents the accuracy of the latitude and longitude properties, expressed in meters.

`institutionInfo` and `institutionExtractedInfo` attributes

The following table explains the attributes of the institutionInfo and institutionExtractedInfo objects:

institutionInfo — Information regarding the financial institution through which a participant made a transaction.
institutionExtractedInfo — Financial institution information extracted from available data.

Field	Type	Description
`code`	String	Transaction institution code, e.g. BIC.
`name`	String	Transaction institution name.
`address`	Object	Transaction institution address.
`internalId`	String	VASP identifier for counterparty transaction. If provided, we trust the exchange and use the expected VASP for transaction approval.

`data.info` attributes

The following table explains the transaction-related financial information.

Field	Type	Description
`direction`	String	The direction in which the funds are transferred. `out` — the applicant sends to the counterparty. `in` — the counterparty sends to the applicant.
`amount`	Double	The amount of funds sent within a transaction (in a currency used by an applicant). The round transaction amounts are detected: 10, 5000, 100000, and so on.
`currencyCode`	String	Code of the currency in which the transaction was made.
`currencyType`	String	Indicates whether the transaction is `crypto` or `fiat`.
`amountInDefaultCurrency`	Double	Transaction amount in the default currency.
`defaultCurrencyCode`	String	Code of the default currency.
`paymentTxnId`	String	Crypto transaction identifier from the blockchain.
`paymentDetails`	String	Comment with the payment details.
`paymentTxnId`	String	Crypto transaction identifier from the blockchain.

`review` attributes

The following table explains the details of the transaction status and check result.

Field	Type	Description
`reviewId`	String	Unique identifier of the transaction check in the Sumsub system.
`attemptId`	String	Unique identifier of the check attempt. Transaction checks can be initiated more than once if, for example, they failed and the information was added/changed.
`attemptCnt`	Integer	The counting number of the check attempt.
`elapsedSincePendingMs`	Integer	Elapsed time since the transaction check passed to the `pending` status.
`createDate`	Date	Date and time (UTC) when the transaction was created in the Sumsub system.
`reviewDate`	Date	Date and time (UTC) when the transaction check was completed.
`reviewResult`	Object	Explains the transaction review result.
`reviewStatus`	String	Indicates the transaction status ( `onHold`, `completed`, `init`).
`confirmed`	Boolean	Indicates whether the officer has confirmed the verdict on the transaction as defined by the rules.

`reviewResult` attributes

Contains the reviewAnswer parameter that explains the transaction review result.

Field	Type	Description
`reviewAnswer`	String	Explains the transaction review result. `GREEN` — the transaction is approved. `RED` — the transaction is declined.
`reviewRejectType`	String	Indicates the type of rejection. `FINAL` — final rejection in case of major violations. The transaction cannot be resubmitted for verification. `RETRY` — temporary rejection in case of minor violations. The transaction can be resubmitted with new information provided.

`scoringResult` attributes

The following table explains the transaction overall scoring result and its details.

Field	Type	Description
`score`	Integer	Calculated score of a transaction.
`dryScore`	Integer	Calculated dry score of the transaction which would be assigned by the rules applied in the dry run mode.
`applicantActions`	Array of objects	Each object includes applicant action data.
`matchedRules`	Array of objects	All rules that matched during the scoring session.
`failedRules`	Array of objects	All rules that failed during the scoring session.
`action`	String	Result of all matched rules combined (`score` / `onHold` / `reject` / `approved`, and so on).
`ruleCnt`	Integer	Total number of the rules counted for a transaction.
`dryRunRuleCnt`	Integer	Total number of the dry run rules counted for a transaction.

`applicantActions` element fields

The following table describes the object fields of the applicantActions array.

Field	Type	Description
`applicantActionId`	String	Unique applicant action identifier on the Sumsub side.
`externalActionId`	String	Unique applicant action identifier on your side.

`matchedRules` element fields

The following table explains the details of the rule that matched during the scoring session. Each rule is represented by an individual object inside the matchedRules array.

Field	Type	Description
`id`	String	Rule identifier.
`name`	String	Rule name.
`revision`	Integer	Rule revision. Incremented after the rule has been edited.
`title`	String	Rule title.
`score`	Integer	Amount that will be added to the overall score if the rule is matched.
`dryRun`	Boolean	Indicates whether the rule is applied in a dry run mode (no affection on the transaction, no side effects). `true` — the rule in the dry run mode. `false` — the rule in the regular mode.
`action`	String	Result action of the matched rule (`score` / `onHold` / `reject`).

`travelRuleInfo` attributes

Field	Type	Description
`protocolName`	Enum	The name of the protocol used during the information exchange.
`applicant`	Object	Applicant information used during the information exchange.
`counterparty`	Object	Counterparty information used during the information exchange.
`status`	Enum	The current information exchange state.
`expiredAt`	Date	If the timer is set, the transaction will be re-scored after a certain period of time.
`applicantVaspId`	ObjectId	Stores information about the counterparty VASP institution.
`counterpartyVaspId`	ObjectId	Stores information about the counterparty VASP institution.

`protocolName` types

Value	Description
`sns`	Sumsub protocol.
`gtr`	Global Travel Rule Protocol.
`trp`	Travel Rule Protocol.
`vba`	VASP By Address.
`fallback`	Fallback notification.

travelRuleInfo.status

Value	Description
`counterpartyVaspNotReachable`	The data couldn't be sent since the second side of the transaction was not reachable. The response from the counterparty hasn’t been received.
`counterpartyVaspNotFound`	The second side of the transaction was not found.
`awaitingCounterparty`	The second side of the transaction was found and the data was sent. The response from the counterparty is awaited.
`onHold`	The second side of the transaction was found and the data was sent. The transaction has been interrupted on the second side.
`expired`	The second side of the transaction was found and the data was sent. There was no response received from the counterparty on time.
`unconfirmedOwnership`	The second side of the transaction was found and the data was sent. Wallet ownership has not been confirmed.
`counterpartyUnconfirmedOwnership`	The second side of the transaction was found and the data was sent. The negative response on wallet ownership has been received.
`counterpartyMismatchedData`	The data has been sent, compared and there is a mismatch between both data sets.
`completed`	Transaction is completed.

Overview

Response explained

Root variables

data attributes

data.applicant attributes

data.counterparty attributes

address attributes

paymentMethod attributes

device attributes

ipInfo attributes

coords attributes

institutionInfo and institutionExtractedInfo attributes

data.info attributes

review attributes

reviewResult attributes

scoringResult attributes

applicantActions element fields

matchedRules element fields

travelRuleInfo attributes

protocolName types