Trustly Pay & Play Pure Flow - Quick Login

The following BusinessOperation is covered in this section:

IDNameCredit/Debit State
TrustlyLoginNot applicable.

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

Payment flow

651
  1. Merchant sends a v5 REST API request to PXP Financial. A Business Operation request is created.
  2. PXP sends a Deposit request to Trustly with a "KYC":"1" parameter.
  3. Trustly return the redirectURL in a response.
  4. The redirectURL is passed to the merchant. The merchant should redirect the user to the Trustly iframe.
  5. Trustly will retrieve KYC information from the user´s bank account and pass them in a KYC notification to PXP Financial.
  6. PXP forwards the KYC information in a handlePaymentStateChangedNotificationRequest.
  7. 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:

789
StateDescription
CreatedBusiness Operation for Trustly Quick Login is created
LoginRequestSentA Deposit request has been sent to Trustly
LoginResponseReceivedA Deposit response has been received from Trustly
LoginUrlCreatedA loginURL was returned from Trustly and is provided back to the merchant in the v5 response.
LoginFailedAn error was returned by Trustly for the Deposit request.
NotificationReceivedFromProviderA KYC notification has been received from Trustly. PXP will always response with "FINISH" to Trustly as per the provider´s specification.
LoginSucessfulThe KYC notification returned from Trustly included KYC details such as KYCPersonID, KYCFirstName, etc.
LoginUnsucessfulThe KYC data was not received from provider due to an error "unverified" or "underage". The error is logged in a ProviderStatusMessage detail.
NotificationSentToMerchantA handlePaymentStateChangedNotification request has been sent to the merchant. It will include either the KYC fields or an error (unverified or underage)
NotificationResponseReceivedFromMerchantA handlePaymentStatechangedNotification response was received from the merchant.
NotificationAcceptedByMerchantThe notification was accepted by the merchant.
NotificationRefusedByMerchantThe notification was not accepted by the merchant.
NotificationErrorReportedByMerchantThis 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, requiredShop 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 StatesDescription
‘InquiryRequestReceivedFromProviderKYC data was received from provider and is attached to the notification.
KYCValidationFailedThe 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:

DetailDescription
merchantTransactionIDThe 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.