KYC notification

What is KYC notifcation

In this section we will discover how merchants are able to retrieve KYC data from this notification as well as any market specific requirements around these data points.

Trustly will send a KYC notification to the merchant’s NotificationURL if the attribute "RequestKYC" : “1” is sent in a Deposit API call. The KYC notification should be expected after the player has performed one successful login to their bank and always before a deposit transfer is initiated.

Once the data is processed by the merchant, the merchant will reply to either Allow (CONTINUE) the deposit transfer or Deny (FINISH) the deposit.

KYC notification JSON RPC HTTPS POST data, sent by the Trustly system to the merchant’s listening service at the specified NotificationURL

{
	"method": "kyc",
	"params": {
		"signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",
		"uuid": "258a2184-2842-b485-25ca-293525152425",
		"data": {
			"orderid": "87654567",
			"messageid": "mytransaction-001",
			"kycentityid": "29a750aa-0bad-4a28-a42d-ffb9a690d93a",//***
			"notificationid": "9876543456",
			"attributes": {
				"personid": "SE196512171957", //only available in SE/FI/EE
				"firstname": "Joe",
				"lastname": "Johnson",
				"dob": "1965-12-17",
				"street": "Street 10",
				"zipcode": "11253",
				"city": "STOCKHOLM",
				"country": "Sweden"

			}
		}
	},
	"version": "1.1"
}

Notification hash keys

Hash key	Description	Type	Example
orderid	The unique ID in our system for the order.	Text	87654567
messageid	The unique ID in merchant’s system for the order	Text	mytransaction-001
kycentityid	Trustly generated unique identifier based on player’s bank account profile. Can be used as an identifier when personid is not available. **Ihe identifier may change, hence our suggestion is to have a logic that does not include KYCEntityID	Text	29a750aa-0bad-4a28-a42d-ffb9a690d93a
notificationid	Unique ID for this notification. Each notification must only be handled once in your system.	Text	4567897654
personid	Entity’s personal number (SSN) Can be considered as a unique identifier Only present in markets where SSN is applicable	Text	19900501
firstname	Entity’s first name.	Text	Joe
lastname	Entity’s last name.	Text	Johnson
dob	Entity’s date of birth in YYYY-MM-DD format.	Date	1989-12-29
street	Entity’s street name.	Text	Johnsons street 5
zipcode	Entity’s ZIP code.	Text	13650
city	Entity’s city.	Text	Stockholm
gender	Avoid doing any logic that depends on this parameter for the following reasons: Some banks have different binary logic interpretation There are cases were this is a hidden attribute	Text	F
country	Entity’s country of residence	Text	Sweden
abortmessage	This will be sent incase the KYC information can’t be forwarded or is not present (more information in the upcoming sections below)	Text	unverified

Respond to a KYC notification

In this section we will look at the three possible options you can reply to KYC notifications:

CONTINUE
FINISH
CONTINUE + Limit - Optional response (see Appendix Section 8.9 CONTINUE with LIMIT response)

CONTINUE response

Most common scenario. Merchant has performed all necessary checks and prompts Trustly to CONTINUE with prompting the player to sign their deposit transfer (or complete login towards their bank if amount is not populated in the Deposit call)

Example of KYC notification response with status “CONTINUE”:

{  
	"result": {  
		"uuid": "258a2184-2842-b485-25ca-293525152425",  
		"signature": "hnXTkeo...B57GO+w=",  
		"method": "kyc",  
		"data": {  
			"status": "CONTINUE"  
		}  
	},  
	"version": "1.1"  
}

FINISH response

Here are common scenarios where FINISH scenarios are expected:

Session limit reached
Player is trying to perform a login+deposit where deposit limit is reached and merchant does not support the Continue + Limit functionality
Player is self excluded from gambling
Player is blacklisted from gambling altogether
Player is blacklisted through other site under same Whitelabel
Any other scenario should entail the player to be able to CONTINUE through the Trustly checkout flow.

Example of “FINISH” response:

{  
	"result": {  
		"uuid": "258a2184-2842-b485-25ca-293525152425",  
		"signature": "xn3Tkgo...F53GO+w=",  
		"method": "kyc",  
		"data": {

```
		"status": "FINISH"
	}
},
"version": "1.1"
```
}

CONTINUE with LIMIT response

{
	"result": {
		"uuid": "321e2184-2123-b485-67de-32525152425",
		"signature": "hnXTkeo...B57GO+w=",
		"method": "kyc",
		"data": {
			"status": "CONTINUE",
             "limit": "900.00"
		}
	},
	"version": "1.1",
}

When KYC data are missing (AbortMessage)

AbortMessage Data flow

Unverified KYC information

In the rare event that the player’s KYC information is not available, you will not receive this data in the KYC notification. Our experience indicates that this usually only occurs when special restrictions are enforced by the government or enforcement agencies. In that case, you will receive a KYC notification with the following attribute:

"abortmessage": "unverified",

upon which you need to reply with “FINISH”.

Underage detection

If the player is underage, Trustly will send a KYC notification with the following data:

"abortmessage": "underage",

upon which you need to reply with “FINISH”.

Example notification response for underage case (similar for unverified):

{  
	"version": "1.1",  
	"method": "kyc",  
	"params": {  
		"uuid": "adse3ed8-5559-464f-827d-c1b6def43528",  
		"data": {  
			"messageid": "12464352351",  
			"abort": "1",  
			"abortmessage": "underage",  
			"notificationid": "2435650790",  
			"orderid": "3065591686"  
		},  
		"signature": "FqzroHS/[...]]4fvFfvr3spozKW3xaUt+HSLA=="  
	}  
}

Match KYC data

For a Pay N Play integration, we recommend that you do regular KYC re-checks to cross check provided player data against your controlled database.

To do that, you need to

Use attribute RequestKYC: 1 for the login/registration stage and for players that are already logged to avoid deposits from 3rd parties.
For all markets its recommended to always include logic revolving around KYC data. SSN / Person ID aids in identifying users. KYC data checks can include the following logic:

{FirstName} AND/OR {LastName} AND/OR {DOB} AND/OR {Street} AND/OR {ZipCode} AND/OR {City} AND/OR {Country}

Note: The end result of the above information aims to guide merchants in making a calculated CONTINUE decision. Please note that it’s up to the merchant’s own interpretation of any Gaming Requirements on how such cases are to be handled. The above acts as a suggestive approach based on past, successful, integrations

Note that for the instance of a previously used bank account, the AccountID provided in the Account Notification will remain the same. Though this data is sent after the deposit is done, merchants may find this aspect useful as they can flag if the player in question used an existing AccountID or not.