Deposit

Introduction

The Deposit method returns a URL where the end-user can make a payment from their bank account.

A typical Deposit flow is:

The merchant sends a Deposit API call and receives a URL back from Trustly's API.
The merchant displays the Trustly URL to the end-user (you can find more information about how to display the Trustly URL here).
The end-user selects their bank and completes the payment (in case the payment is not completed, a cancel notification is sent).
Trustly sends a pending notification to the merchant's NotificationURL when the end-user has completed the payment process, and a credit notification is sent when the payment is confirmed. When the funds have settled, they will be credited to the merchant's Trustly account balance.
(Optional) An account notification is sent to provide the merchant with more information about the account that was used to make the payment. This notification is not enabled by default, please reach out to your Trustly contact if you want to receive it.
In case the Deposit fails, a debit notification is sent (see more information under "Failed Deposits" below).

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 payment should be sent to. This URL should be hard to guess and not contain a ? ("question mark").	Yes	Text	https://www.joe.com/Trustly/ Notify/a2b63j23dj23883jhfhfh
EndUserID	ID, username, hash or anything uniquely identifying the end-user requesting the deposit. 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 deposit.	Yes	Text	12345678
Attributes	Attributes for this method.	Yes	Object	{ "Locale": "sv_SE" }

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

Attributes

Attribute name	Description	Required	Type	Example
Currency	The currency of the end-user's account in the merchant's system.	Yes	Text	EUR
Firstname	The end-user's first name.	Yes	Text	Steve
Lastname	The end-user's last name.	Yes	Text	Smith
Country	The ISO 3166-1-alpha-2 code of the end-user's country. This will be used for pre-selecting the country for the end-user in the iframe. Note: This will only have an effect for new end-users. If an end-user has done a previous order (with the same EndUserID), the country that was last used will be pre-selected.	Yes	Text	SE
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. This will be used to pre-select the language in the trustly iframe.	Yes	Text	en_US
ShopperStatement	The text to show on the end-user's bank statement after Trustly's own 10 digit reference (which always will be displayed first). The reference must let the end user identify the merchant based on this value. So the ShopperStatement should contain either your brand name, website name, or company name. If possible, try to keep this text as short as possible to maximise the chance that the full reference will fit into the reference field on the customer's bank since some banks allow only a limited number of characters. If the full ShopperStatement does not fit into the reference it will be truncated from the end.	Yes	Text	MyBrand.com
SuccessURL	The URL to which the end-user should be redirected after a successful deposit. 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/thank_you.html
FailURL	The URL to which the end-user should be redirected after a failed deposit. 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/payment_error.html
Email	The email address of the end user.	Yes	Text	[email protected]
MobilePhone	The mobile phone number of the end-user in international format.	Yes	Text	+46709876543
Amount	The amount to deposit. See format in Currencies. Do not use this attribute in combination with SuggestedMinAmount or SuggestedMaxAmount. Only digits. Use dot (.) as decimal separator.	No	Text	103.50
SuggestedMinAmount	The minimum amount the end-user is allowed to deposit in the currency specified by Currency. Only digits. Use dot (.) as decimal separator.	No	Text	5.00
SuggestedMaxAmount	The maximum amount the end-user is allowed to deposit in the currency specified by Currency. Only digits. Use dot (.) as decimal separator.	No	Text	500.00
AccountID	The AccountID of a returning customer. Allows for a quicker payment experience in some markets, see Trustly Express.	No	Text	1234567890
IP	The IP-address of the end-user.	No	Text	83.140.44.184
TemplateURL	The TemplateURL should be used if you want to design your own payment page but have it hosted on Trustly's side. The URL of your template page should be provided in this attribute in every Deposit API call. Our system will then fetch the content of your template page, insert the Trustly iframe into it and host the entire page on Trustly’s side. In the response to the Deposit request, you will receive a URL to the hosted template page which you should redirect the user to (the hosted page cannot be iframed). There are some security restrictions to the TemplateURL: All images must have absolute URLs. Every link must use HTTPS. * Tags like: script, iframe, frame, frameset, object, applet, etc will not be allowed as they present a security risk. In addition, the template page must contain in some part of the code the following tag that we will use to insert Trustly’s iFrame: <!-- TRUSTLY-PAYMENT-PAGE-GOES-HERE --> The trustly payment window on the hosted page will default to 600px width. To dynamically adjust it to a mobile screen, please add the following to your CSS: "iframe {width: 100% !important;}"	No	Text	https://example.org/checkout_trustly.html
URLTarget	The html target/framename of the SuccessURL. Only _top, _self and _parent are suported.	No	Text	_top
NationalIdentificationNumber	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 personid ("personnummer") is provided, it will be pre-filled when the user logs in to their bank.	No	Text	790131-1234
UnchangeableNationalIdentificationNumber	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	Text	1
ShippingAddressCountry	The ISO 3166-1-alpha-2 code of the shipping address country.	No	Text	SE
ShippingAddressPostalCode	The postalcode of the shipping address.	No	Text	SE-11253
ShippingAddressCity	The city of the shipping address.	No	Text	Stockholm
ShippingAddressLine1	Shipping address street	No	Text	Main street 1
ShippingAddressLine2	Additional shipping address information.	No	Text	Apartment 123, 2 stairs up
ShippingAddress	The entire shipping address. This attribute should only be used if you are unable to provide the shipping address information in the 5 separate attributes above (ShippingAddressCountry, ShippingAddressCity, ShippingAddressPostalCode, ShippingAddressLine1, ShippingAddressLine2)	No	Text	Main street 1, SE-11253, Stockholm, Sweden.
[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	yourCustomReturnToAppURL://
RequestDirectDebitMandate	In addition to the deposit, request a direct debit mandate from the account used for the deposit. 1 enables, 0 disables. The default is disabled. If this attribute is set, additional account notifications might be sent. You can read more about Trustly Direct Debit here, under section 2.1	No	Text	1
ExternalReference	The ExternalReference is a reference set by the merchant for any purpose and does not need to be unique for every API call. The ExternalReference will be included in version 1.2 of the settlement report, ViewAutomaticSettlementDetailsCSV.	No	Text	23423525234
PSPMerchant	Human-readable identifier of the consumer-facing merchant (e.g. legal name or trade name)	Yes*	Text	Merchant Ltd.
PSPMerchantURL	URL of the consumer-facing website where the order is initiated	Yes*	Text	www.merchant.com
MerchantCategoryCode	VISA category codes describing the merchant's nature of business.	Yes*	Text	5499
RecipientInformation	Information about the Payee (ultimate creditor). The burden of identifying who the Payee for any given transaction is lies with the Trustly customer. ** Required for some merchants and partners, see below.	Yes**	Object	{"Firstname": "Mark" ...}

🚧
* PSPMerchant, PSPMerchantURL and MerchantCategoryCode
PSPMerchant, PSPMerchantURL and MerchantCategoryCode are mandatory attributes for Trustly Partners that are using Express Merchant Onboarding and aggregate traffic under a master processing account. It is also mandatory for E-wallets used directly in a merchant's checkout, whereby the purpose of a Trustly transaction is to pay for goods/services by placing funds on the payer's e-money account ("funding stage") following an immediate transfer into the e-money account of the payee ( "payment" stage).

🚧
** RecipientInformation
RecipientInformation{} is mandatory to send for money transfer services (including remittance houses), e-wallets, prepaid cards, as well as for Trustly Partners that are using Express Merchant Onboarding and aggregate traffic under a master processing account (other cases may also apply).

Attribute name	Description	Required	Type	Example
Partytype	Partytype can be "PERSON" or "ORGANISATION" (if the recipient is an organisation/company).	Yes	Text	PERSON
Firstname	First name of the person, or the name of the organisation.	Yes	Text	Mark
Lastname	Last name of the person (NULL for organisation).	Yes	Text	Smith
CountryCode	The ISO 3166-1-alpha-2 code of the country that the recipient resides in.	Yes	Text	ES
CustomerID	Payment account number or an alternative consistent unique identifier (e.g. customer number). Note: this is not a transaction ID or similar. This identifier must stay consistent across all transactions relating to this recipient (payee).	No	Text	123456789
Address	Full address of the recipient, excluding the country.	No	Text	Main street 1, 12345, Barcelona
DateOfBirth	Date of birth (YYYY-MM-DD) of the beneficiary, or organisational number for the organisation.	No	Text	1980-01-30

The result returned is an object with the following elements:

Hash key	Description	Type	Example
orderid	The globally unique OrderID the deposit was assigned in our system.	Text	5843996816
url	The URL that should be loaded so that the end-user can complete the deposit.	Text	`https://checkout.trustly.com/checkout?OrderID=1234567890&SessionID=...`

Request and Response examples

Request

{
  "method": "Deposit",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "NotificationURL": "https://URL_to_your_notification_service/dajskldjakls123",
      "EndUserID": "12345",
      "MessageID": "your_unique_deposit_id",
      "Attributes": {
        "Country": "SE",
        "Locale": "sv_SE",
        "Currency": "SEK",
        "Amount": "103.00",
        "IP": "123.123.123.123",
        "MobilePhone": "+46709876543",
        "Firstname": "John",
        "Lastname": "Doe",
        "Email": "[email protected]",
        "NationalIdentificationNumber": "790131-1234",
        "SuccessURL": "https://yourpage.com/success",
        "FailURL": "https://yourpage.com/fail"
      }
    }
  },
  "version": "1.1"
}

{
  "method": "Deposit",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "NotificationURL": "https://URL_to_your_notification_service/dajskldjakls123",
      "EndUserID": "12345",
      "MessageID": "your_unique_deposit_id",
      "Attributes": {
        "Country": "SE",
        "Locale": "sv_SE",
        "Currency": "SEK",
        "Amount": "103.00",
        "IP": "123.123.123.123",
        "MobilePhone": "+46709876543",
        "Firstname": "John",
        "Lastname": "Doe",
        "Email": "[email protected]",
        "NationalIdentificationNumber": "790131-1234",
        "SuccessURL": "https://yourpage.com/success",
        "FailURL": "https://yourpage.com/fail",
        "RecipientInformation": {
          "Partytype": "PERSON",
          "Firstname": "Mark",
          "Lastname": "Smith",
          "CountryCode": "ES",
          "CustomerID": "123456789",
          "Address": "Main street 1, 12345, Barcelona",
          "DateOfBirth": "1980-01-30"
        }
      }
    }
  },
  "version": "1.1"
}

{
  "method": "Deposit",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "NotificationURL": "https://URL_to_your_notification_service/dajskldjakls123",
      "EndUserID": "12345",
      "MessageID": "your_unique_deposit_id",
      "Attributes": {
        "Country": "SE",
        "Locale": "sv_SE",
        "Currency": "SEK",
        "Amount": "103.00",
        "IP": "123.123.123.123",
        "MobilePhone": "+46709876543",
        "Firstname": "John",
        "Lastname": "Doe",
        "Email": "[email protected]",
        "NationalIdentificationNumber": "790131-1234",
        "SuccessURL": "https://yourpage.com/success",
        "FailURL": "https://yourpage.com/fail",
        "PSPMerchant": "merchant_name",
        "PSPMerchantURL": "https://merchantURL.com/",
        "MerchantCategoryCode": "1234",
        "RecipientInformation": {
          "Address": "Merchant Road 101",
          "CountryCode": "SE",
          "CustomerID": "merch_001",
          "DateOfBirth": "5563427391",
          "Firstname": "Merchant Ltd",
          "Lastname": null,
          "Partytype": "ORGANISATION"
        }
      }
    }
  },
  "version": "1.1"
}

Response

{
  "result": {
    "signature": "4F8hjuMqbsH0Ku ... S16VbzRsw==",
    "uuid": "258a2184-2842-b485-25ca-293525152425",
    "method": "Deposit",
    "data": {
      "orderid": "2190971587",
      "url": "https://checkout.trustly.com/checkout?OrderID=1234567890&SessionID=..."
    }
  },
  "version": "1.1"
}

Failed deposits

If a credit notification has been sent, but Trustly never receives the funds, a debit notification will be sent to the merchant's NotificationURL. If you receive a debit after credit you should try to stop the order. If you are successfully able to stop the order before sending it to the end-user (or in case the user holds a balance on your side and you are able to lower the amount from their balance), you should respond with status "OK" to the debit notification. If you have already processed the order and are unable to recover the money you should respond with status "FAILED".

If you reply “OK” to the debit notification and the deposit still settles after that (which is not expected, but possible), Trustly's system will make an automatic refund to the end-user's bank account.

If you reply “FAILED” to the debit notification and the deposit settles after that, no automatic refund will be made.

You can trigger a debit notification in our test environment by running the D1 test case (see Acceptance testing.

API error codes

A list of the possible error codes can be found here.