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 parameters
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": "test@trustly.com",
"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": "test@trustly.com",
"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": "test@trustly.com",
"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 attributes
The result returned is an object with the following elements:
{
"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.
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. The expected format is explained in Deposit with KYC attributes. |