SelectAccount

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:

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

Request parameters:

Parameter nameDescriptionRequiredTypeExample
UsernameThe username.YesTextjoe
PasswordThe password.YesTextsecret
NotificationURLThe URL to which notifications for this order should be sent to. This URL should be hard to guess and not contain a ? ("question mark").YesTexthttps://example.com/trustly/
notification/a2b63j23dj23883jhfhfh
EndUserIDID, 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.
YesText123123
MessageIDYour unique ID for the account selection order. Each order you create must have an unique MessageID.YesText12345678
AttributesOptional attributes for this method.YesHash{ "Locale": "sv_SE" }

The parameter Attributes is a hash of optional attributes. New attributes may be added in future versions of the API but existing attributes will never be removed.

The attributes to this method are:

Attribute nameDescriptionTypeExample
LocaleThe 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.Texten_US
CountryThe 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.Char(2)SE
IPThe IP-address of the end-user.Text83.140.44.184
SuccessURLThe 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.Texthttps://example.com/
thank_you.html
FailURLThe 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.Texthttps://trustly.com/
error.html
TemplateURLThe URL to your template page. Read more about the TemplateURL on the Deposit pageTexthttps://example.org/
checkout_trustly.html
URLTargetThe html target/framename of the SuccessURL. Only _top, _self and _parent are suported.Text_top
MobilePhoneThe mobile phonenumber to the end-user in international format.Text+46709876543
FirstnameThe end-user's firstname.TextSteve
LastnameThe end-user's lastname.TextSmith
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.
Text197901311234
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.Numeric1
DateOfBirthThe end-user's date of birth.Text1979-01-31
EmailThe email address of the end user. This attribute is required when using RequestDirectDebitMandate = 1.Text[email protected]
RequestDirectDebitMandateOnly for Trustly Direct Debit.
Request a direct debit mandate from the selected account. 1 or 0. See section "Direct Debit Mandates" below for details.
Numeric1
ShopperStatementOnly 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.
TextMyBrand.com
URLSchemeIf you are using Trustly from within your native iOS app, this attribute should be sent so that we can redirect the users back to your app in case an external app is used for authentication (for example Mobile Bank ID in Sweden).

The URLScheme can also be registered in Trustly's backend. Please reach out to your Trustly contact if you want us to configure a fixed URLScheme.
TextyourCustomURLScheme://
PSPMerchantHuman-readable identifier of the consumer-facing merchant (e.g. legal name or trade name)TextMerchant Ltd.
PSPMerchantURLURL of the consumer-facing website where the order is initiatedTextwww.merchant.com
MerchantCategoryCodeVISA category codes describing the merchant's nature of business.Text5499

🚧

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.

The result returned is a hash with the following elements:

Hash keyDescriptionTypeExample
orderidThe globally unique OrderID the account selection order was assigned in our system.BigInt7653345737
urlThe URL that should be loaded so that the end-user can complete the identification process.Texthttps://trustly.com/_/2f6b14fa-446a-4364-92f8-84b738d589ff

Example of SelectAccount call

{
  "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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.