Trustly Pay & Play Pure Flow - Quick Login

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

  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:

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.