SelectAccount

Introduction

Initiates a new order where the end-user can select and verify one of his/her bank accounts.

You can find more information about how to display the Trustly URL here.

When the account has been verified an account notification is immediately sent to the NotificationURL.

A typical flow is:

The merchant makes an API-call to SelectAccount and redirects the end-user to the url.
The end-user selects his/her bank and completes the identification process.
The end-user is redirected back to the merchant at the SuccessURL, note that the account might not be verified yet at this point.
When the account is verified, Trustly sends an account notification to the merchant's system with information about the selected account

Request parameters

Parameter name	Description	Required	Type	Example
Username	The username.	Yes	Text	joe
Password	The password.	Yes	Text	secret
NotificationURL	The URL to which notifications for this order should be sent to. This URL should be hard to guess and not contain a ? ("question mark").	Yes	Text	https://example.com/trustly/ notification/a2b63j23dj23883jhfhfh
EndUserID	ID, username, hash or anything uniquely identifying the end-user to be identified. Preferably the same ID/username as used in the merchant's own backoffice in order to simplify for the merchant's support department.	Yes	Text	123123
MessageID	Your unique ID for the account selection order. Each order you create must have an unique MessageID.	Yes	Text	12345678
Attributes	Optional attributes for this method.	Yes	Object	{ "Locale": "sv_SE" }

The parameter Attributes is a JSON object. Some of the attributes are required and some are optional to include. New attributes may be added in future versions of the API but existing attributes will never be removed.

Attributes

Attribute name	Description	Req.	Type	Example
Locale	The end-users localization preference in the format [language[_territory]]. Language is the ISO 639-1 code and territory the ISO 3166-1-alpha-2 code.	Yes	Text	en_US
Country	The ISO 3166-1-alpha-2 code of the end-user's country. This will be used for preselecting the correct country for the end-user in the iframe.	Yes	Char(2)	SE
Firstname	The end-user's firstname.	Yes	Text	Steve
Lastname	The end-user's lastname.	Yes	Text	Smith
SuccessURL	The URL to which the end-user should be redirected after he/she has completed the initial identification process. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.	Yes	Text	https://example.com/ thank_you.html
FailURL	The URL to which the end-user should be redirected after a failed/aborted account selection. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.	Yes	Text	https://trustly.com/ error.html
RequestDirectDebitMandate	Only for Trustly Direct Debit. Request a direct debit mandate from the selected account. 1 or 0. See section "Direct Debit Mandates" below for details.	No	Numeric	1
Email	The email address of the end user. *This attribute is required when using RequestDirectDebitMandate = 1.	Yes*	Text	[email protected]
TemplateURL	The URL to your template page. Read more about the TemplateURL on the Deposit page	No	Text	https://example.org/ checkout_trustly.html
URLTarget	The html target/framename of the SuccessURL. Only _top, _self and _parent are supported.	No	Text	_top
NationalIdentification Number	The end-user's social security number / personal number / birth number / etc. If a Swedish personid ("personnummer") is provided, it will be pre-filled when the user logs in to their bank.	No	Text	197901311234
UnchangeableNational IdentificationNumber	This attribute disables the possibility to change/type in national identification number when logging in to a Swedish bank. If this attribute is sent, the attribute NationalIdentificationNumber needs to be correctly included in the request. Note: This is only available for Swedish banks.	No	Numeric	1
ShopperStatement	Only for Trustly Direct Debit. The text to show in the email sent to end users for mandate requests The ShopperStatement should contain either your brand name, website name, or company name.	No	Text	MyBrand.com
IP	The IP-address of the end-user.	No	Text	83.140.44.184
MobilePhone	The mobile phonenumber to the end-user in international format.	No	Text	+46709876543
DateOfBirth	The end-user's date of birth.	No	Text	1979-01-31
[DEPRECATED, see ReturnToAppURL instead] URLScheme	Please note that when rendering the Trustly Checkout from a native app you are required to pass your application's URLScheme as an attribute to the order initiation request. By doing so, Trustly can redirect users back to your app after using external identification apps such as Mobile BankID. Please visit this link for more info. It must not be included for transactions that are not originating from an app	No	Text	yourCustomURLScheme://
ReturnToAppURL	When rendering the Trustly Checkout in a native app you are required to pass your application's url as an attribute to the order initiation request. By doing so, Trustly can redirect users back to your app after using external identification apps such as Mobile BankID: Please visit this link for more info. It must not be included for transactions that are not originating from an app. NOTE! This value is only used for redirecting users back to the native app within the flows. See also SuccessURL and FailURL descriptions.	No	Text	youCustomAppURL://
PSPMerchant	Human-readable identifier of the consumer-facing merchant (e.g. legal name or trade name)	No	Text	Merchant Ltd.
PSPMerchantURL	URL of the consumer-facing website where the order is initiated	No	Text	www.merchant.com
MerchantCategoryCode	VISA category codes describing the merchant's nature of business.	No	Text	5499

🚧
PSPMerchant, PSPMerchantURL and MerchantCategoryCode
PSPMerchant, PSPMerchantURL and MerchantCategoryCode are mandatory attributes for Trustly Partners that are using Express Merchant Onboarding (EMO) and aggregate traffic under a master processing account.

Response

The result returned is a hash with the following elements:

Hash key	Description	Type	Example
orderid	The globally unique OrderID the account selection order was assigned in our system.	BigInt	7653345737
url	The URL that should be loaded so that the end-user can complete the identification process.	Text	https://trustly.com/_/2f6b14fa-446a-4364-92f8-84b738d589ff

Code example

{
  "method": "SelectAccount",
  "params": {
    "Data": {
      "Attributes": {
        "Country": "SE",
        "Firstname": "Steve",
        "IP": "83.140.44.184",
        "Lastname": "Smith",
        "Locale": "sv_SE",
        "Email": "[email protected]",
        "MobilePhone": "+46709876543",
        "NationalIdentificationNumber": "197901311234",
        "DateOfBirth": "1979-01-31",
        "SuccessURL": "https://your_success_page.com"
      },
      "EndUserID": "12345",
      "MessageID": "your_unique_id",
      "NotificationURL": "https://URL_to_your_notification_service",
      "Password": "merchant_password",
      "Username": "merchant_username"
    },
    "Signature": "Hh+sfaUnbtMKW[...]9YngA9bTpiqxw==",
    "UUID": "258a2184-2842-b485-25ca-293525152425"
  },
  "version": "1.1"
}

{
    "result": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "SelectAccount",
        "data": {
            "orderid": "2190971587",
            "url": "https://trustly.com/_/bec96a48-d454-448e-a9ba-25fea8eeba3f"
        }
    },
    "version": "1.1"
}

Direct Debit Mandates

If the RequestDirectDebitMandate attribute is set, the behavior of the order changes with respect to how account notifications are emitted:

Once the normal order flow is done and the end-user has chosen an account, an account notification without the directdebitmandate attribute can be sent to the NotificationURL if the account is not immediately ready to be charged.
If the end-user's bank has approved the mandate on the selected account and the account can be charged, an account notification with the directdebitmandate attribute set to "1" is sent.
If creating the mandate is rejected by the end-user's bank or an active mandate is cancelled, an account notification with the directdebitmandate attribute set to "0" is sent.
If the mandate at some point is revoked additional notificications will be sent to all selectaccount orders concerned. It will have the directdebitmandate attribute set to indicate the new status of the mandate.