Trustly Instant Bank Deposit

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

162

TrustlyInstantBankDeposit

DepositedByProvider

362

TrustlyInstantBankRefund

Refunded

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

Redirect Integration

Currently not supported.

Payment states flow

Note: the KYC flow is not consider in this flow diagram.

756756

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)

value

MerchantNotificationUrl
(string, required)

The URL where the user will be redirected after payment execution with payment execution result

UrlTarget (string, optional)

The html target/framename of the SuccessUrl. Used for updating iframe. Only _top, _self or _parent are supported.

ShouldRequestKYC (string, optional)

When the merchant sends true, the payment is extending with the KYC flow. This flow can only be used when activated by Trustly. See the section further below for details.

AppReturnURL

URLScheme for redirecting the customer back to the merchant´s mobile app

Fields in userData xml section:

key (value type)

value

Firstname (string, required)

The end-user´s first name.

Lastname (string, required)

The end-user´s last name.

Email (string, required)

The end-user´s email address.

Country (string, required)

The end user`s country (ISO 3166). This will be used for pre-selecting the country for the end-user in the iframe.

If a user has done a previous deposit, the country that was last used will be pre-selected.

Phone number (string, optional/required)

The mobile phone number of the end-user in international format. This is used by Trustly for KYC and AML routines.

This is a required attribute for merchants in the financial services business.

IdentificationNumber (string, optional)

The end-user´s social security number / personal number / birth number etc. Useful for some banks for identifying transactions and KYC/AML.

If a Swedish personlid ("personnummer") is provided, it will be pre-filled when the user logs in to their bank.

Address (consisting of street, postalcode and city, optional)

Full address of the customer / beneficiary. Mandatory for money remittance business.

DateOfBirth (string, optional)

Date of birth of the customer / beneficiary. Mandatory for money remittance business.

Example initiatePaymentRequest:

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>YourMerchantID</merchantID>
    <shopID>YourShopID</shopID>
    <merchantTransactionID>d1424c6c-61a6-4b22-b271-a9d9ca873377</merchantTransactionID>
    <paymentMethodID>162</paymentMethodID>
    <amount currencyCode="GBP">10</amount>
    <userID>061d3d1c-0a93-4ab8-8936-6a6896</userID>
    <userData>
        <username>UserName</username>
        <firstname>FirstName</firstname>
        <lastname>LastName</lastname>
        <languageCode>en</languageCode>
        <address>
            <countryCode2>GB</countryCode2>
            <telephoneNumber>0044123456789</telephoneNumber>
        </address>
        <identificationNumber>1234567</identificationNumber>
    </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>86aefacf-193c-433e-b042-a945c6108856</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>MerchantNotificationUrl</key>
            <value>http://notification.url</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>UrlTarget</key>
            <value>_parent</value>
        </data>
        <data xsi:type="keyBooleanValuePair">
            <key>ShouldRequestKYC</key>
            <value>true</value>
        </data>
        <data xsi:type="keyStringValuePair">
                  <key>AppReturnURL</key>
                  <value>myapp://www.test.com</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <merchantID>YourMerchantID</merchantID>
        <shopID>YourShopID</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>d1424c6c-61a6-4b22-b271-a9d9ca873377</merchantTransactionID>
        <paymentID>c5d6a9e5-f364-4159-ab31-7fc82a6102ff</paymentID>
        <userID>061d3d1c-0a93-4ab8-8936-6a6896</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="GBP">10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>d84ab002-3a50-4728-96cb-b81715154c7c</id>
            <definition>
                <key> 30</key>
                <value> RedirectURLCreated</value>
            </definition>
            <createdOn> 2012-09-20T08:57:08.9244171Z</createdOn>
            <description> https://test.backend.cqrpayments.com/WebMockProviders/Trustly.aspx?SessionID=7fad590e-fa89-46ee-a8ec-984cf0101c17&amp;OrderID=3161310259</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value> http://test.backend.cqrpayments.com/WebMockProviders/Trustly.aspx?SessionID=7fad590e-fa89-46ee-a8ec-984cf0101c17&amp;OrderID=3161310259</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>3161310259</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

The possible payment states in initiatePaymentResponse are listed below:

Payment States

Description

RedirectURLCreated (287)

OK state; Redirect user to the URL

DuplicatePaymentValidationFailed (369)

A payment with the same merchantTransactionID already exists.

InitiateErrorReportedByProvider (4)

Payment was not initiated; See below table Error Codes for list of common errors

Regular Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDEMO</merchantID>
        <shopID>KalixaAcceptDEMO</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>20141230_6</merchantTransactionID>
        <paymentID>b22aa889-fa79-4762-88a7-863ad33bceed</paymentID>
        <userID>KalxiaTestUser_7</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">100.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>195.72.132.1</userIP>
        <state>
            <id>ac60f8c8-4ebd-4ba3-a070-83c1f82581c0</id>
            <definition>
                <key>29</key>
                <value>DepositedByProvider</value>
            </definition>
            <createdOn>2014-12-30T09:16:58.293</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">100.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1270</value>
            </detail>
            <detail xsi:type="keyIntValuePair">
                <key>PaymentScoring</key>
                <value>722501</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>1939284750</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Possible payment states in notification:

Payment States

Description

DepositedByProvider (29)

Success state; Payment has been executed

RefusedByProvider (100)

Refused state. Payment was not accepted by provider.

ChargedBackByProvider (118)

Reversal state. Payment was reversed.

PaymentDataChangedByCustomer (501)

See below comment on Payment input data changed by customer.

Payment input data changed by customer

In some rare cases case it can happen that the customer changes the initial payment amount or currency when making a deposit. In this case a new payment will be created and will go to the DepositedByProvider state. The state change notification sent to the merchant will then contain field ReassignedFromPaymentID that points to the original payment. The payment originally initiated by merchant goes to PaymentDataChangedByCustomer state and the merchant notification about this state change will contain field ReassignedToPaymentID that points to the new payment.

Offline payment created by customer

It is possible that a user registered in the PXP Financial payment system can create an offline payment using a previous Trustly payment as a template. The provider will notify us about this and a new payment that will go to DepositedByProvider state will be created in the PXP Financial payment service. A state change notification for this state will be sent to the merchant containing a new MerchantTransactionID (a GUID).

Standalone Account Notification

Account notifications, if received from Trustly, are sent a as seperate PaymentAccountChangedNotification.

On the first payment of a new user using a new bank account for a TrustlyInstantBankDeposit payment, an handlePaymentAccountChanged notification will be sent to the merchant. This notification will include a reference to the payment (the paymentID).

On a subsequent payment of the same user with the same bank account a notification will not be sent .
If on a subsequent payment of the same user a different bank account will be used, another handlePaymentAcountChanged notification will be sent.

📘

Account notification data vs. KYC data

The Account notification data is sent by Trustly anytime the user selects the account they want the deposit taken from.

The KYC notification, in contrast, is sent by Trustly at Bank login stage.

Example handlePaymentAccountChangedNotification:

<?xml version="1.0" encoding="UTF-8"?>
<handlePaymentAccountChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <paymentAccount>
      <merchantID xmlns="http://www.cqrpayments.com/PaymentProcessing">29101992</merchantID>
      <userID xmlns="http://www.cqrpayments.com/PaymentProcessing">pp_party332</userID>
      <paymentAccountID xmlns="http://www.cqrpayments.com/PaymentProcessing">29cd12e8-71ea-4f16-b446-17440237a34b</paymentAccountID>
      <paymentAccountTypeID xmlns="http://www.cqrpayments.com/PaymentProcessing">25</paymentAccountTypeID>
      <isActive xmlns="http://www.cqrpayments.com/PaymentProcessing">true</isActive>
      <isVisible xmlns="http://www.cqrpayments.com/PaymentProcessing">true</isVisible>
      <specificPaymentAccountData xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <data xsi:type="keyStringValuePair">
            <key>AccountNumber</key>
            <value>1ebeb0db-f822-4675-a582-4228cce306fa</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>AccountOwnerAddressName</key>
            <value>Examplestreet 1</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>AccountOwnerAddressCity</key>
            <value>Helsinki</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>AccountOwnerAddressPostalCode</key>
            <value>12345</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>CustomerID</key>
            <value>FI080360-268A</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>AccountOwnerCountryName</key>
            <value>FINLAND</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>PaymentAccountLabel</key>
            <value>************000011</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>BankName</key>
            <value>Demos Bank</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>CustomerName</key>
            <value>Riku Pohjonen</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>InitialMerchantTransactionID</key>
            <value>da97653a-03f5-44ba-b0be-d9c0a8a4d6b5</value>
         </data>
      </specificPaymentAccountData>
      <state xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <id>6047666c-a75d-4196-9162-ce798925f716</id>
         <definition>2</definition>
         <createdOn>2021-04-16T05:59:44.9602539Z</createdOn>
         <paymentAccountStateDetails>
            <detail xsi:type="keyStringValuePair">
               <key>paymentAccountStateReasonMessage</key>
               <value>Wallet account created.</value>
            </detail>
         </paymentAccountStateDetails>
      </state>
   </paymentAccount>
</handlePaymentAccountChangedNotificationRequest>

Possible account details in notification:

Account detail

Description

PaymentAccountID

A payment account is being created at PXP. Trustly´s accountID has been saved at PXP.

It will be possible to initiate a bank transfer withdrawal with the payment method TrustlyInstantBankWithdrawal.

InitialMerchantTransactionID

The merchantTransactionID of the payment with which is account was created.

AccountOwnerAddressName

The address of the account holder, e.g. "Examplestreet 1"

AccountOwnerAddressCity

The city of the account holder, e.g. "Examplecity"

AccountOwnerAddressPostalCode

The zip code of the account holder, e.g. "12345"

CustomerID

An ID that uniquely identifies the account holder (also called personID). Note: The format of this field will for some countries look different than the example, e.g. "SE198201019876",

AccountOwnerCountryName

The country of the bank account / bank, e.g. "SWEDEN".

AccountNumber

The Trustly account number value.

BankName

Bankname of this acount. e.g. "Demo bank" or "SEB"

PaymentAccountLabel

The bank account number, shown as a masked value, e.g. "*** 084057". This value - called "descriptor" by Trustly - may contain spaces or other characters that are non-numerical (- or / for example). This value is meant to be used to display the value to the end user.

CustomerName

The name on the account holder, e.g. "John Doe"

KYC flow

When the merchant sends the field ShouldRequestKYC as true in initiatePaymentRequest.specificPaymentData, then the payment is created with the KYC flow.

PXP then will send a handlePaymentStateChanged notification to the merchant. The merchant has to reply with 0 (ProcessedSuccessfully/Approved) or 15 (BlockedByMerchant/Rejected). When the merchant replies with OK, the payment is continued and a notification for the state DepositedByProvider will be sent.

By replying "15", the payment will be stopped and moved to state KYCValidationFailed.

Additional instead of the KYC data, the provider may return an error that KYC data cannot be retrieved or that the user is underage. In that case the state "KYCValidationFailed" is set and a notification is sent to the merchant.

📘

KYC data vs. Account notification data

The KYC notification in the Pay N Play flow is sent by Trustly at Bank login stage.

The Account notification data, in contrast, is sent anytime the user selects the account they want the deposit taken from.

Example handlePaymentStateChangedNotificationRequest with state=InquiryRequestReceivedFromProvider:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>150001</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>7e4035d9-d769-41f4-a65c-482586bbac54</merchantTransactionID>
        <paymentID>35b6691b-abdf-4170-927e-a2f1c0dd02ae</paymentID>
        <userID>pp_party332</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">12.0300</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>6842c5b3-924b-4707-ad15-465482409f71</id>
            <definition>
                <key>529</key>
                <value>InquiryRequestReceivedFromProvider</value>
            </definition>
            <createdOn>2019-12-04T08:12:28.0644155Z</createdOn>
            <description>{    "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": "3109226646BDD",        "messageid": "5436",        "kycentityid": "29a750aa-0bad-4a28-a42d-ffb9a690d93a",        "notificationid": "9876543456",        "attributes": {          "personid": "SE196512171957",          "firstname": "Joe",          "lastname": "Johnson",          "dob": "1965-12-17",          "street": "Street 10",          "zipcode": "11253",          "city": "STOCKHOLM",          "country": "Sweden"        }      }    },    "version": "1.1"  }</description>
            <paymentStateDetails>
                <detail xsi:type="keyIntValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">12.0300</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5436</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>3109226646BDD</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCEntityId</key>
                <value>29a750aa-0bad-4a28-a42d-ffb9a690d93a</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCPersonId</key>
                <value>SE196512171957</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCFirstname</key>
                <value>Joe</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCLastname</key>
                <value>Johnson</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCDateOfBirth</key>
                <value>1965-12-17</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCStreet</key>
                <value>Street 10</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCZipCode</key>
                <value>11253</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCCity</key>
                <value>STOCKHOLM</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCCountry</key>
                <value>Sweden</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationResponse (successful case):

<?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>Approved payment</resultMessage>
</handlePaymentStateChangedNotificationResponse>

Example handlePaymentStateChangedNotificationResponse (error case):

<?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>15</key>
        <value>BlockedByMerchant</value>
    </resultCode>
    <resultMessage>Rejected payment</resultMessage>
</handlePaymentStateChangedNotificationResponse>

Example handlePaymentStateChangedNotification for KYCValidationFailed state :

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>150001</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>77c030fe-5e0b-4b30-b1ff-1298bb12f73d</merchantTransactionID>
        <paymentID>0280f8e0-310a-4c90-b9d9-9b19849f4b06</paymentID>
        <userID>pp_party332</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">46.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>4bbe038b-e7d2-44dc-8ba9-f7d27f0298e8</id>
            <definition>
                <key>605</key>
                <value>KYCValidationFailed</value>
            </definition>
            <createdOn>2019-12-04T08:25:40.55</createdOn>
            <description />
            <paymentStateDetails>
                <detail xsi:type="keyIntValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">46.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5437</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>2986525230BDD</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCEntityId</key>
                <value>29a750aa-0bad-4a28-a42d-ffb9a690d93a</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCPersonId</key>
                <value>SE196512171957</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCFirstname</key>
                <value>Joe</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCLastname</key>
                <value>Johnson</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCDateOfBirth</key>
                <value>1965-12-17</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCStreet</key>
                <value>Street 10</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCZipCode</key>
                <value>11253</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCCity</key>
                <value>STOCKHOLM</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>KYCCountry</key>
                <q1:value>Sweden</q1:value>
            </q1:detail>
        </q1:paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

When the state KYCValidationFailed is reached due to the user being underage, the information underage is saved in PaymentDetails as ProviderStatusMessage. The same applies for message unverified (Insufficient KYC information).

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>150001</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>c8c5d800-374a-4768-82f4-4f5cfcd57645</merchantTransactionID>
        <paymentID>f89b2ec8-058d-43fb-85ef-08b44a0314a9</paymentID>
        <userID>pp_party332</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">21.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>dcac8616-90f6-42c7-b4ad-6b7885a161e6</id>
            <definition>
                <key>605</key>
                <value>KYCValidationFailed</value>
            </definition>
            <createdOn>2019-12-04T13:39:56.247</createdOn>
            <description />
            <paymentStateDetails>
                <detail xsi:type="keyIntValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">21.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5468</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>2312017550BDD</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderStatus</key>
                <value>1</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderStatusMessage</key>
                <value>underage</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Pay N Play flow

On the Pay N Play flow a payment is initiated without userdata such as Firstname and Lastname.
The merchant still needs to send ShouldRequestKYC = true.

initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>XXX</merchantID>
    <shopID>XXXX</shopID>
    <merchantTransactionID>TrustlyProviderTestingTRY002</merchantTransactionID>
    <paymentMethodID>162</paymentMethodID>
    <amount currencyCode="EUR">12.55</amount>
    <userID>dec43127-5078-41ed-9799-19051e</userID>
    <userData>
        <username xsi:nil="true" />
        <firstname xsi:nil="true" />
        <lastname xsi:nil="true" />
        <currencyCode xsi:nil="true" />
        <languageCode xsi:nil="true" />
        <email xsi:nil="true" />
        <address>
            <street xsi:nil="true" />
            <houseName xsi:nil="true" />
            <houseNumber xsi:nil="true" />
            <houseNumberExtension xsi:nil="true" />
            <postalCode xsi:nil="true" />
            <city xsi:nil="true" />
            <state xsi:nil="true" />
            <countryCode2>SE</countryCode2>
            <telephoneNumber xsi:nil="true" />
        </address>
        <identificationNumberType xsi:nil="true" />
        <drivingLicenseNumber xsi:nil="true" />
        <drivingLicenseIssuingState xsi:nil="true" />
    </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>3c994bc9-eadb-4045-bb39-516de14a6bb6</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>UrlTarget</key>
            <value>http://urlTargetForIFrameUpdates</value>
        </data>
        <data xsi:type="keyBooleanValuePair">
            <key>ShouldRequestKYC</key>
            <value>true</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>MerchantNotificationUrl</key>
            <value>https://merchantnotificationurl</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

initiatePaymentResponse:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>RequestKYCShopProvider</shopID>
        <paymentMethod>
            <key>162</key>
            <value>TrustlyInstantBankDeposit</value>
        </paymentMethod>
        <merchantTransactionID>TrustlyProviderTestingTRY002</merchantTransactionID>
        <paymentID>1ed35838-cd16-4b45-8f02-47be9f342598</paymentID>
        <userID>dec43127-5078-41ed-9799-19051e</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">12.55</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>9da321e6-0e58-4520-a427-f2d9cab154b8</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2021-03-17T08:58:23.0369586Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://test.trustly.com/_/orderclient.php?Locale=en_SE&amp;OrderID=13944871735&amp;SessionID=77b412ea-d52f-4ce1-b7d1-11da2de6a911</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">12.55</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>13944871735</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>245008</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Testing instruction KYC-flow

Please try the following test banks:

Sparkasse Prignitz - 16050101
UniCredit Bank - HVB Settlement EAC27 - 20730027

Once you select the bank then use any end user:
ex. deuser001, deuser99, detestuser123
basically any entry should work. `

In Trustly´s test env. whenever a new username is entered, KYC data gets randomly generated. However that set of KYC data will be kept binded to that username till end of month (which is when the servers' KYC data gets reset). So for ex. deuser001 you will be able to get the same data for the next 7 days, after which that same username will have new KYC data binded till end of next month.

For testing user being underage, please do the following:

This can be done by making a Deposit with a Swedish bank, and choosing a "personid" where the age < 18 years. For example "20081101-0000".

Unfortunaltely it is not possible to test the ‘unverified’ or ‘data not found’ use case on the KYC flow with provider Trustly.

Refund

In order to refund a TrustlyInstantBankDeposit, the iniitatePaymentFromReference call is utilized.

The possible payment states in initiatePaymentFromReferenceResponse are listed below:

Payment States

Description

Refunded

Success state. The refund was successful processed.

RefundErrorOccurred

Failed state. The refund was refused by provider.

RefundCommunicationErrorOccured

Failed state. Sending the refund request to provider or fetching a response from provider has failed.

initiatePaymentFromReferenceRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>xxxx</merchantID>
    <shopID>xxxx</shopID>
    <originalPaymentID>27bb46d0-b5f8-4178-a4d2-3de01c1b6001</originalPaymentID>
    <merchantTransactionID>572d7b3d-a13f-4d03-b734-9a415cd006a6</merchantTransactionID>
    <paymentMethodID>362</paymentMethodID>
    <amount currencyCode="EUR">21.10</amount>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>superb description</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>OriginalPaymentID</key>
            <value>27bb46d0-b5f8-4178-a4d2-3de01c1b6001</value>
        </data>
    </specificPaymentData>
    <creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>

initiatePaymentFromReferenceResponse: (successful)

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>xxxx</merchantID>
        <shopID>xxxx</shopID>
        <paymentMethod>
            <key>362</key>
            <value>TrustlyInstantBankRefund</value>
        </paymentMethod>
        <merchantTransactionID>572d7b3d-a13f-4d03-b734-9a415cd006a6</merchantTransactionID>
        <paymentID>74044056-16cf-4361-8421-40dcd49d9c87</paymentID>
        <userID>pp_party332</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">21.10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>f602c37b-0409-4d1c-afdc-b578dc572022</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2020-10-21T13:42:40.244242Z</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">21.1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>33642079</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>266f7c45-f2af-45e7-b958-d35ec0ed83c4</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentFromReferenceResponse>

initiatePaymentFromReferenceResponse: (error case)

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>xxxx</merchantID>
        <shopID>xxxx</shopID>
        <paymentMethod>
            <key>362</key>
            <value>TrustlyInstantBankRefund</value>
        </paymentMethod>
        <merchantTransactionID>572d7b3d-a13f-4d03-b734-9a415cd006a6</merchantTransactionID>
        <paymentID>74044056-16cf-4361-8421-40dcd49d9c87</paymentID>
        <userID>userID</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">21.10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>f602c37b-0409-4d1c-afdc-b578dc572022</id>
            <definition>
                <key>310</key>
                <value>RefundErrorOccurred</value>
            </definition>
            <createdOn>2020-10-21T13:42:40.244242Z</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">21.1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>33642079</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>266f7c45-f2af-45e7-b958-d35ec0ed83c4</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentFromReferenceResponse>

handlePaymentStateChangedNotificationRequest:

<?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 xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>150001</shopID>
        <paymentMethod>
            <key>362</key>
            <value>TrustlyInstantBankRefund</value>
        </paymentMethod>
        <merchantTransactionID>572d7b3d-a13f-4d03-b734-9a415cd006a6</merchantTransactionID>
        <paymentID>74044056-16cf-4361-8421-40dcd49d9c87</paymentID>
        <userID>pp_party332</userID>
        <paymentProvider>
            <key>114</key>
            <value>Trustly</value>
        </paymentProvider>
        <amount currencyCode="EUR">21.1000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>f602c37b-0409-4d1c-afdc-b578dc572022</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2020-10-21T13:42:40.243</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">21.1000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>266f7c45-f2af-45e7-b958-d35ec0ed83c4</value>
            </detail>
            <detail xsi:type="keyIntValuePair">
                <key>MerchantSettlementCurrencyID</key>
                <value>2</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentID</key>
                <value>27bb46d0-b5f8-4178-a4d2-3de01c1b6001</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMerchantTransactionID</key>
                <value>572d7b3d-a13f-4d03-b734-9a415cd006a6</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodID</key>
                <value>162</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodName</key>
                <value>TrustlyInstantBankDeposit</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Trustly error codes

ProviderResponseCode

ProviderResponseMessage

602

ERROR_FUNCTION_ACCESS_DENIED - The merchant does not have access to this function.

607

ERROR_HOST_ACCESS_DENIED - The IP address of the merchant has not been added to Trustly's IP-whitelist.

615

ERROR_INVALID_AMOUNT - The Amount specified in the deposit call is invalid. The amount must be > 0 with 2 decimals.

616

ERROR_INVALID_CREDENTIALS - The username and/or password used in the API call is incorrect.

620

ERROR_UNKNOWN - There could be several reasons for this error, contact your integration manager for details.

623

ERROR_INVALID_PARAMETERS - Some value or parameter in the deposit call does not match the expected format.

636

ERROR_UNABLE_TO_VERIFY_RSA_SIGNATURE - The signature in the deposit call could not be verified using the merchant's public key. Either the wrong private key is used, or the the data object used to create the signature was serialized incorrectly.

637

ERROR_DUPLICATE_MESSAGE_ID - The MessageID sent in the deposit has been used before.

638

ERROR_ENDUSER_IS_BLOCKED - The enduser that initiated the payment is blocked.

645

ERROR_INVALID_LOCALE - The Locale-attribute is sent with an incorrect value.

688

ERROR_DUPLICATE_UUID - This uuid has been used before.

696

ERROR_ENDUSERID_IS_NULL - The EndUserID sent in the request is null

697

ERROR_MESSAGEID_IS_NULL - The MessageID sent in the request is null

698

ERROR_INVALID_IP - The IP attribute sent is invalid. Only one IP address can be sent.

700

ERROR_MALFORMED_SUCCESSURL - The SuccessURL sent in the request is malformed. It must be a valid http(s) address.

701

ERROR_MALFORMED_FAILURL - The FailURL sent in the request is malformed. It must be a valid http(s) address.

702

ERROR_MALFORMED_TEMPLATEURL - The TemplateURL sent in the request is malformed. It must be a valid http(s) address.

703

ERROR_MALFORMED_URLTARGET - The URLTarget sent in the request is malformed.

704

ERROR_MALFORMED_MESSAGEID - The MessageID sent in the request is malformed.

705

ERROR_MALFORMED_NOTIFICATIONURL - The NotificationURL sent in the request is malformed. It must be a valid http(s) address.

706

ERROR_MALFORMED_ENDUSERID - The EndUserID sent in the request is malformed.

Useful links

Trustly checkout guidelines