GuidesAPI ReferenceDiscussions
Guides

Trustly Instant Bank Deposit

Suggest Edits

The following method IDs are covered in this section:

IDNameCredit/Debit State
162TrustlyInstantBankDepositDepositedByProvider
362TrustlyInstantBankRefundRefunded
446Trustly Instant Bank Refund ReturnReturnedByProvider

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.

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
SuccessPageUrl
(string, required)		The URL where the user will be redirected after the payment is executed sucessfully
RefusedPageUrl
(string, required)		The URL where the user will be redirected when the payment has failed. When the user is redirected to this URL, also a notification is sent for state AbortedByProvider (activation at Trustly for cancelled notification required)
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.
AppReturnURLURLScheme for redirecting the customer back to the merchant´s mobile app

📘

URL fields:

Either the merchantNotificationURL or the SuccessPageURL and RefusedPageURL have to be provided.

The following parameters can be provided in initiatePaymentRequest.UserData:

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.

The following parameters can be provided in 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 StatesDescription
RedirectURLCreated (287)OK state; Redirect user to the URL
DuplicatePaymentValidationFailed (369)A payment with the same merchantTransactionID already exists.
InitiateErrorReportedByProvider (4)An error occurred during initiation of the payment. See below table Error Codes for list of common errors
InitiateRefusedByProvider ()The payment initiation was refused by provider.

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 StatesDescription
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 detailDescription
PaymentAccountIDA 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.
InitialMerchantTransactionIDThe merchantTransactionID of the payment with which is account was created.
AccountOwnerAddressNameThe 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"
PaymentAccountLabelThe 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 initiatePaymentFromReference call is utilized.

🚧

Refund return

Watchout: in rare cases, refunds can be returned. See further below.

The possible payment states in initiatePaymentFromReferenceResponse are listed below:

Payment StatesDescription
RefundedSuccess state. The refund was successful processed.
RefundErrorOccurredFailed state. The refund was refused by provider.
RefundCommunicationErrorOccuredFailed 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 Refund Returns

In rare cases, a TrustyInstantBankRefund can be returned by the bank and a new payment of payment method Trustly Instant Bak Refund Return is created and notified to the merchant.

handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-16"?>
<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>446</key>
      <value>Trustly Instant Bank Refund Return</value>
    </paymentMethod>
    <merchantTransactionID>905dbbeb-f24b-4482-b3b6-ea9445fb284d</merchantTransactionID>
    <paymentID>602be4cf-23c4-412b-93c6-77fe643c1736</paymentID>
    <userID>pp_party332</userID>
    <paymentProvider>
      <key>114</key>
      <value>Trustly</value>
    </paymentProvider>
    <amount currencyCode="EUR">15.9900</amount>
    <creationType>
      <key>6</key>
      <value>Provider</value>
    </creationType>
    <state>
      <id>57c82bcc-2895-4958-a532-8860997f157c</id>
      <definition>
        <key>279</key>
        <value>ReturnedByProvider</value>
      </definition>
      <createdOn>2024-04-26T08:42:16.867</createdOn>
      <paymentStateDetails xsi:nil="true" />
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">15.9900</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>d63b3f39-4790-4c38-bca2-0e12ed88e62f</value>
      </detail>
      <detail xsi:type="keyIntValuePair">
        <key>SettlementCurrencyCode</key>
        <value>978</value>
      </detail>
      <detail xsi:type="keyIntValuePair">
        <key>MerchantSettlementCurrencyID</key>
        <value>2</value>
      </detail>
      <detail xsi:type="keyDecimalValuePair">
        <key>SettlementAmount</key>
        <value>15.990000000</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>9ce7de43-6aff-4f25-bc34-cf27ec07d081</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>905dbbeb-f24b-4482-b3b6-ea9445fb284d</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>362</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>TrustlyInstantBankRefund</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Trustly error codes

ProviderResponseCodeProviderResponseMessage
602ERROR_FUNCTION_ACCESS_DENIED - The merchant does not have access to this function.
607ERROR_HOST_ACCESS_DENIED - The IP address of the merchant has not been added to Trustly's IP-whitelist.
615ERROR_INVALID_AMOUNT - The Amount specified in the deposit call is invalid. The amount must be > 0 with 2 decimals.
616ERROR_INVALID_CREDENTIALS - The username and/or password used in the API call is incorrect.
620ERROR_UNKNOWN - There could be several reasons for this error, contact your integration manager for details.
623ERROR_INVALID_PARAMETERS - Some value or parameter in the deposit call does not match the expected format.
636ERROR_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.
637ERROR_DUPLICATE_MESSAGE_ID - The MessageID sent in the deposit has been used before.
638ERROR_ENDUSER_IS_BLOCKED - The enduser that initiated the payment is blocked.
645ERROR_INVALID_LOCALE - The Locale-attribute is sent with an incorrect value.
688ERROR_DUPLICATE_UUID - This uuid has been used before.
696ERROR_ENDUSERID_IS_NULL - The EndUserID sent in the request is null
697ERROR_MESSAGEID_IS_NULL - The MessageID sent in the request is null
698ERROR_INVALID_IP - The IP attribute sent is invalid. Only one IP address can be sent.
700ERROR_MALFORMED_SUCCESSURL - The SuccessURL sent in the request is malformed. It must be a valid http(s) address.
701ERROR_MALFORMED_FAILURL - The FailURL sent in the request is malformed. It must be a valid http(s) address.
702ERROR_MALFORMED_TEMPLATEURL - The TemplateURL sent in the request is malformed. It must be a valid http(s) address.
703ERROR_MALFORMED_URLTARGET - The URLTarget sent in the request is malformed.
704ERROR_MALFORMED_MESSAGEID - The MessageID sent in the request is malformed.
705ERROR_MALFORMED_NOTIFICATIONURL - The NotificationURL sent in the request is malformed. It must be a valid http(s) address.
706ERROR_MALFORMED_ENDUSERID - The EndUserID sent in the request is malformed.

Flow at Trustly

Without passing an account, the following is shown on the Trustly test system: first a list of banks is shown.

After this screen the user is redirected to the merchant´s success URL.

Useful links

Trustly checkout guidelines

Updated 7 months ago