Accept payments from customers or deposits from players
Overview
You can use the Deposit API method to accept payments from customers in general or accept deposits from players in gaming. For example, in a gaming app, you can integrate with Trustly so that players can make deposit in the game.
If you plan to use Deposit in the Netherlands, see iDeal.
Request example
{
"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"
}
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. See Attributes. | Yes | Object | { "Locale": "sv_SE" } |
Attributes
The parameter Attributes is an object of attributes.
Note: New attributes may be added in future versions of the API, but existing attributes will never be removed.
| 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 |
| The email address of the end user. | Yes | Text | [email protected] | |
| MobilePhone | The mobile phone number of the end-user in international format. | No | 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:// |
| 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). Note: It is required for using Express Merchant Onboarding and aggregate traffic under a master processing account. It is also mandatory for E-wallets used directly in your checkout, where you use Trustly to transfer funds from the customer's e-money account ("funding stage") into your e-money account. | Yes* | Text | Merchant Ltd. |
| PSPMerchantURL | URL of the consumer-facing website where the order is initiated. Note: It is required for using Express Merchant Onboarding and aggregate traffic under a master processing account. It is also mandatory for E-wallets used directly in your checkout, where you use Trustly to transfer funds from the customer's e-money account ("funding stage") into your e-money account. | No | Text | www.merchant.com |
| MerchantCategoryCode | VISA category codes describing the merchant's nature of business. Note: It is required for using Express Merchant Onboarding and aggregate traffic under a master processing account. It is also mandatory for E-wallets used directly in your checkout, where you use Trustly to transfer funds from the customer's e-money account ("funding stage") into your e-money account. | No | 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 RecipientInformation attributes. | No | Object | {"Firstname": "Mark" ...} |
RecipientInformation attributes
| 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 |
Response example
{
"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"
}
Response attributes
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=... |
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.
Automatic refunds
If a Deposit is aborted during the payment process, a cancel notification is sent to the merchant. If Trustly for unknown reasons still receives the money for the Deposit, an automatic Refund is triggered and the end user will get the money back the the same bank account that they paid from.
If the settlement report (ViewAutomaticSettlementDetailsCSV) is used by the merchant, both the settled Deposit and the automatic Refund will appear on the report. The sum of those two transactions will always be zero.
Error codes
These error codes can be returned for Deposit calls. To handle errors, see Error handling.
| Error Num | Error Code | Description |
|---|---|---|
| 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 s 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, please reach out to your Trustly contact for details. |
| 622 | ERROR_INVALID_CURRENCY_CODE | The currency code is invalid. See this page for valid currencies. |
| 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 could not be verified using the merchant's public key. Either the wrong private key was used to generate the signature, or the the data object used to create the signature was serialized incorrectly. |
| 637 | ERROR_DUPLICATE_MESSAGE_ID | The MessageID has been used before. |
| 638 | ERROR_ENDUSER_IS_BLOCKED | The enduser that initiated the payment is blocked. |
| 639 | ERROR_NO_PUBLIC_KEY | No public key has been configured for the merchant on Trustly's side. |
| 642 | ERROR_INVALID_EMAIL | The email attribute is missing or invalid (this is a requirement when using Trustly Direct Debit). |
| 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 https address. |
| 706 | ERROR_MALFORMED_ENDUSERID | The EndUserID sent in the request is malformed. |
| 712 | ERROR_DIRECT_DEBIT_NOT_ALLOWED | Trustly Direct Debit (TDD) is not enabled on the merchant's user in Trusty's system. If you want to use TDD, please reach out to your Trustly contact. If you don't want to use TDD and still get this error message, you may need to remove the following attributes from the Deposit data: RequestDirectDebitMandate, QuickDeposit, ChargeAccountID. |
| 717 | ERROR_INVALID_ORDER_ATTRIBUTE | One or more attributes are sent with the incorrect value. Please reach out to your Trustly contact for more information. |
| 718 | ERROR_DISABLED_USER | The merchant's user is disabled in Trustly's system. |
| 732 | ERROR_PAY_AND_PLAY_NOT_ALLOWED | Trustly's Pay N Play product is not enabled on the merchant's user in Trustly's system. If you want to use Pay N Play, please reach out to your Trustly contact. |
| 734 | ERROR_NOT_SECURE_NOTIFICATIONURL | The NotificationURL must be using HTTPS, not plain HTTP. |
| 737 | ERROR_INVALID_COUNTRY | The Country code sent in the Deposit data is invalid. |