Trustly Pay & Play Pure Flow

The following BusinessOperation is covered in this section:

ID	Name	Credit/Debit State
	TrustlyLogin	Not applicable.

Payment method interaction type: Redirection to External Payment Provider and notification (see Interaction Types).

Payment flow

Merchant sends a v5 REST API request to PXP Financial. A Business Operation request is created.
PXP sends a Deposit request to Trustly with a "KYC":"1" parameter.
Trustly return the redirectURL in a response.
The redirectURL is passed to the merchant. The merchant should redirect the user to the Trustly iframe.
Trustly will retrieve KYC information from the user´s bank account and pass them in a KYC notification to PXP Financial.
PXP forwards the KYC information in a handlePaymentStateChangedNotificationRequest.
Merchant will send status 0 (ProcessedSuccessfully) along with user´s final userID to PXP Financial.

State Machine

The following Business Operation (BO) states are reached:

State	Description
Created	Business Operation for Trustly Quick Login is created
LoginRequestSent	A Deposit request has been sent to Trustly
LoginResponseReceived	A Deposit response has been received from Trustly
LoginUrlCreated	A loginURL was returned from Trustly and is provided back to the merchant in the v5 response.
LoginFailed	An error was returned by Trustly for the Deposit request.
NotificationReceivedFromProvider	A KYC notification has been received from Trustly. PXP will always response with "FINISH" to Trustly as per the provider´s specification.
LoginSucessful	The KYC notification returned from Trustly included KYC details such as KYCPersonID, KYCFirstName, etc.
LoginUnsucessful	The KYC data was not received from provider due to an error "unverified" or "underage". The error is logged in a ProviderStatusMessage detail.
NotificationSentToMerchant	A handlePaymentStateChangedNotification request has been sent to the merchant. It will include either the KYC fields or an error (unverified or underage)
NotificationResponseReceivedFromMerchant	A handlePaymentStatechangedNotification response was received from the merchant.
NotificationAcceptedByMerchant	The notification was accepted by the merchant.
NotificationRefusedByMerchant	The notification was not accepted by the merchant.
NotificationErrorReportedByMerchant	This state is used for communication errors and timeouts.

📘
NotificationAccepted
The merchant should return a handlePaymentStateNotification response indicating that the notification was accepted for both the success case - KYC data was returned from provider - and the failure case - the provider returned an abortmessage "underage" or "unverified".

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in the POST request to the Kalixa Backend Service REST API (v5).

key (value type, account type, required)	Description
ID (string, required)	MerchantTransactionD of the Login request.
MerchantID (string, required)	Merchant ID for the request.
ShopID (string, required	Shop ID for the request.
SuccessUrl (string, required)	The URL to which the end-user should be redirected after a successful deposit. Trustly advices not to put any logic on that page since it's not guaranteed that the end-user will in fact visit it. Example: https://trustly.com/thank_you.html
CancelUrl (string, required)	The URL to which the end-user should be redirected after a failed deposit. Trustly advices not to put any logic on that page since it's not guaranteed that the end-user will in fact visit it. Example: https://trustly.com/payment_error.html
LanguageCode (string, required)	The language code is used to preselect the language in the trustly iframe.
IpAddress (string, required)	The IP-address of the end user.

Example of the request:

{
"Id":"c1da2b74-b4a1-4faf-a9ec-82f16380dec3",
"MerchantID":"B2BTestMerchant",
"ShopId":"150050",
"SuccessUrl":"success.com",
"CancelUrl":"error.com",
"LanguageCode":"SE",
"IpAddress":"127.0.0.1"
}

Example of the response:

{
    "id": "c1da2b74-b4a1-4faf-a9ec-82f16380dec3",
    "loginUrl": "https://test.trustly.com/5b4d2abb-689d-40f8-8697-4df5bc8fb2a3
}

The merchant has to redirect the user to the loginUrl to display the Trustly iframe.

The user will be asked to login to his online bank account. Trustly will retrieve the user´s bank data such as the PersonID and Firstname, Lastname and other details and pass these detail to PXP Financial.

KYC data notification

PXP will send a handlePaymentStateChanged notification to the merchant with the KYC data fields. The merchant has to reply with 0 (ProcessedSuccessfully) to every notification and provide also the assigned userID.

Possible states in notification:

Payment States	Description
‘InquiryRequestReceivedFromProvider	KYC data was received from provider and is attached to the notification.
KYCValidationFailed	The KYC data was not received from provider due to an error "unverified" or "underage". The error is logged in a ProviderStatusMessage detail.

Details in the notification:

Detail	Description
merchantTransactionID	The merchantTransactionID is the LoginID that the merchant sends in the v5 REST API (Login) request. The ID is also returned in the REST API response.

Example handlePaymentStateChangedNotificationRequest (success state):

<?xml version="1.0" encoding="UTF-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment>
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>RequestKYCShopProvider</shopID>
		<paymentMethod>
			<key>162</key>
			<value>TrustlyInstantBankDeposit</value>
		</paymentMethod>
		<merchantTransactionID>670b4f2f-4d9b-4540-a400-1e8b5a02e47b</merchantTransactionID>
		<paymentID>29f18418-ef09-4546-ba22-55b123b25e2f</paymentID>
		<userID>User</userID>
		<paymentProvider>
			<key>114</key>
			<value>Trustly</value>
		</paymentProvider>
		<amount currencyCode="EUR">1.00</amount>
		<state>
			<id>4ee96648-171d-4d67-9d53-cddbfc475852</id>
			<definition>
				<key>529</key>
				<value>InquiryRequestReceivedFromProvider</value>
			</definition>
			<createdOn>2021-09-01T13:48:42.1995819Z</createdOn>
		</state>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>KYCCity</key>
				<value>Björketorp</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCCountry</key>
				<value>Sweden</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCDateOfBirth</key>
				<value>1940-09-04</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCEntityId</key>
				<value>712447db-d7ec-412d-bef7-6dee792040bf</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCFirstname</key>
				<value>Marlon</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCLastname</key>
				<value>Johnsson</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCPersonId</key>
				<value>SE194009046094</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCStreet</key>
				<value>Gamla Svedalavägen 90</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>KYCZipCode</key>
				<value>510 13</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest (error state):

<?xml version="1.0" encoding="UTF-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment>
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>RequestKYCShopProvider</shopID>
		<paymentMethod>
			<key>162</key>
			<value>TrustlyInstantBankDeposit</value>
		</paymentMethod>
		<merchantTransactionID>ca3239ec-412d-4eb5-83b6-5e1c295d5419</merchantTransactionID>
		<paymentID>ebdae6f8-5b00-455b-88b7-e378b5641eb6</paymentID>
		<userID>User</userID>
		<paymentProvider>
			<key>114</key>
			<value>Trustly</value>
		</paymentProvider>
		<amount currencyCode="EUR">1.00</amount>
		<state>
			<id>4ee96648-171d-4d67-9d53-cddbfc475852</id>
			<definition>
				<key>529</key>
				<value>KYCValidationFailed</value>
			</definition>
			<createdOn>2021-09-01T13:48:42.1995819Z</createdOn>
		</state>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderStatusMessage</key>
				<value>underage</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationResponse:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<resultCode>
		<key>0</key>
		<value>ProcessedSuccessfully</value>
	</resultCode>
	<resultMessage>Request processed by mock service</resultMessage>
	<details xsi:nil="true" />
</handlePaymentStateChangedNotificationResponse>

The merchant should pass the UserID in the response.

📘
Response to Trustly
PXP will always respond to Trustly with 'FINISH' to abort the payment as a payment with a zero amount cannot be completed.

Testing instruction (TEST1 with mock)

For testing of PXP Financial´s TEST1 environment, please send the v5 request as described above.

After receiving the response please send a notication as described below to invoke PXP sending you the handlePaymentStateChangedRequest.

POST /ProviderListeners/providers/114/operations/notifications HTTP/1.1
Host: api.test.kalixa.com
Content-Type: application/json

{
  "method": "kyc",
  "params": {
    "signature": "X2p1H/fwwHua7s2q8alvE3Ji9ZjpZ7x5gIXZpit1zKOj5iYvCoOt+4OpJRdm1N4btRrj/+vLtHF1S0mAlYdu7GT114r1VHrYXZCjRX2WzsJmufxepEeACyJOrEHtgXDzJl/EIx1awPUyG5MxBQlgvTHJNIvFPG4cJlV8tKvv/bL/AyXZWzeKdgQkw7zpzo5fJnK0upfLKxzZoImws2Xt1KFrLOTfzfq49FlhqS6wsZYkfuPXV+vcOLT2/PYqoPI7kAjcagCeh4m+pnV7Fu40nksGkfOU5+4IySIIZgPlcqjnw2Mh4vu68mUWX+qLcrwkAM06RJ9SgIUnNxsBKIGk/A==",
    "uuid": "258a2184-2842-b485-25ca-293525152425",
    "data": {
      "orderid": "300123456",
      "messageid": "37878bd2-b973-4172-9c92-ecae94be5c5e",
      "kycentityid": "29a750aa-0bad-4a28-a42d-ffb9a690d93a",
      "notificationid": "9876543436",
      "attributes": {
        "personid": "SE196512171957",
        "firstname": "Joe",
        "lastname": "Johnson",
        "dob": "1965-12-17",
        "street": "Street 10",
        "zipcode": "11253",
        "city": "STOCKHOLM",
        "country": "Sweden"
      }
    }
  },
  "version": "1.1"
}

The messageID should be the "id" from the v5 response.
The signature can be any value. The orderID, kycentityid and notificationID can also be any value.

Testing Instructions - Provider

For testing PersonIDs for Sweden, refer to this site: fejk.se.

The Trustly test environment is forwarding the PersonID that you're entering (during SE flow). Whatever is being entered is being then returned by Trustly in the KYC notification.

On other markets, e.g. FI, the PersonID are not matching any real life checksums because essentially the data cannot be using real life data. Whenever a "new" PersonID/username is entered in Trustly´s test system, the system will create random KYC data for it and will keep it only till the end of month.

Also the test banks are independent from each other, meaning that if you use the same PersonID/Username across different test banks, you will get different KYC data.

Other testing details, see here.

Trustly Pay & Play Pure Flow - Quick Login

Payment flow

State Machine

📘
NotificationAccepted

Redirect Integration

Backend2BackendIntegration

KYC data notification

📘
Response to Trustly

Testing instruction (TEST1 with mock)

Testing Instructions - Provider

Payment flow

State Machine

📘NotificationAccepted

Redirect Integration

Backend2BackendIntegration

KYC data notification

📘Response to Trustly

Testing instruction (TEST1 with mock)

Testing Instructions - Provider

📘
NotificationAccepted

📘
Response to Trustly