Let customers make withdrawal

Overview

You can use the Withdraw API method to allow customers to withdraw money to their bank accounts.

Request example

{
  "method": "Withdraw",
  "params": {
    "Signature": "S9+hjuMqbsH0Ku ... S16VbzRsw==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "NotificationURL": "https://URL_to_your_notification_service",
      "EndUserID": "12345",
      "MessageID": "your_unique_withdrawal_id",
      "Currency": "SEK",
      "Attributes": {
        "Country": "SE",
        "Locale": "sv_SE",
        "IP": "83.140.44.184",
        "MobilePhone": "+46709876543",
        "Firstname": "Steve",
        "Lastname": "Smith",
        "Email": "[email protected]",
        "DateOfBirth": "1990-01-20",
        "NationalIdentificationNumber": "790131-1234",
        "SuccessURL": "https://yourpage.com/success",
        "FailURL": "https://yourpage.com/fail",
        "AddressCountry": "SE",
        "AddressPostalCode": "SE-11253",
        "AddressCity": "Stockholm",
        "AddressLine1": "Main street 1"
      }
    }
  },
  "version": "1.1"
}

Request parameters

Parameter nameDescriptionRequiredTypeExample
UsernameThe username.YesTextjoe
PasswordThe password.YesTextsecret
NotificationURLThe URL to which notifications for this payment should be sent to. This URL should be hard to guess and not contain a ? ("question mark").YesTexthttps://www.joe.com/Trustly/>
Notify/a2b63j23d
EndUserIDID, username, hash or anything uniquely identifying the end-user requesting the withdrawal. 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 withdrawal.YesText12345678
CurrencyThe currency of the end-user's account in the merchant's system.YesTextSEK
AttributesOptional attributes for this method. See Attributes.YesObject{ "Locale": "sv_SE" }

Attributes

Attribute nameDescriptionRequiredTypeExample
FirstnameThe end-user's first name. Some banks require the recipients name.YesTextSteve
LastnameThe end-user's last name. Some banks require the recipients name.YesTextSmith
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. 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.YesTextSE
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. This will be used to pre-select the language in the trustly iframe.YesTexten_US
SuccessURLThe URL to which the end-user should be redirected after a successful withdrawal. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.YesTexthttps://trustly.com/
thank_you.html
FailURLThe URL to which the end-user should be redirected after a failed withdrawal. Do not put any logic on that page since it's not guaranteed that the end-user will in fact visit it.YesTexthttps://trustly.com/
payment_error.html
ShopperStatementThe 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.YesTextMyBrand.com
EmailThe email address of the end user.NoText[email protected]
DateOfBirthThe date of birth of the end user.NoText1990-01-20
SuggestedAmountSets a fixed withdrawal amount which cannot be changed by the end-user in the Trustly iframe. If this attribute is not sent, the end-user will be asked to select the withdrawal amount in the Trustly iframe. Do not use in combination with SuggestedMinAmount and SuggestedMaxAmount. Use dot (.) as decimal separator.NoText100.00
SuggestedMinAmountThe minimum amount the end-user is allowed to withdraw in the currency specified by Currency. Only digits. Use dot (.) as decimal separator.NoText5.00
SuggestedMaxAmountThe maximum amount the end-user is allowed to withdraw in the currency specified by Currency. Only digits. Use dot (.) as decimal separator.NoText500.00
IPThe IP-address of the end-user.NoText83.140.44.184
TemplateURLThe 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.NoTexthttps://example.org/
withdraw_trustly.html
URLTargetThe html target/framename of the SuccessURL. Only _top, _self and _parent are supported.NoText_top
MobilePhoneThe mobile phone number to the end-user in international format. This is used for KYC and AML routines.NoText+46709876543
NationalIdentification
Number
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.NoText790131-1234
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.NoText1
AddressCountryThe ISO 3166-1-alpha-2 code of the address country. Required attribute for merchants who are sending physical goods to customers.NoTextSE
AddressPostalCodePostal code of the end user.NoTextSE-11253
AddressCityCity of the end user.NoTextStockholm
AddressLine1Street address of the end user.NoTextMain street 1
AddressLine2Additional address information of the end user.NoTextApartment 123, 2 stairs up
AddressThe entire address of the end user. This attribute should only be used if you are unable to provide the address information in the 5 separate attributes above (AddressCountry, AddressPostalCode, AddressCity, AddressLine1 and AddressLine2).NoTextBirgerstreet 14, SE-11411 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 appNoTextyourCustomURLScheme://
ReturnToAppURLWhen 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.
NoTextyourCustomAppURL://
ExternalReferenceThe 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.NoText23423525234
PSPMerchantHuman-readable identifier of the consumer-facing merchant (e.g. legal name or trade name)Yes*TextMerchant Ltd.
PSPMerchantURLURL of the consumer-facing website where the order is initiatedYes*Textwww.merchant.com
MerchantCategoryCodeVISA category codes describing the merchant's nature of business.Yes*Text5499
SenderInformationInformation about the Payer (ultimate debtor). ** Mandatory for certain types of merchants and partners (see more information below).Yes**Object{"Firstname": "Steve"...}

🚧

* 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.

🚧

** SenderInformation

SenderInformation{} is mandatory to send in Attributes{} 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).

SenderInformation attributes

The parameters to SenderInformation{} are:

NameDescriptionRequiredTypeExample
PartytypePartytype can be "PERSON" or "ORGANISATION" (if the ultimate debtor is an organization/company).YesTextPERSON
AddressThe Payer's addressYesTextStreet 1, 12345 Barcelona
CountryCodeThe ISO 3166-1-alpha-2 code of the Payer's country.YesTextSE
FirstnameFirst name of the person (or the name of the organization)YesTextSteve
LastnameLast name of the person (empty for organization)YesTextSmith
CustomerIDPayment account number or an alternative consistent unique identifier which allows to identify the Payer in the system of the PSP of the Payer. Note: this is not a transaction ID or similar. This identifier must stay consistent across all transactions relating to this Payer.NoText123456789
DateOfBirthDate of birth for the person (YYYY-MM-DD) or organizational number for the organizationNoText1990-03-31

Response example

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

Response attributes

The result returned is a JSON object with the following elements:

Hash keyDescriptionTypeExample
orderidThe globally unique OrderID of the withdrawal that was assigned in our system.Text7653345123
urlThe Trustly URL to be displayed to the end-user.Texthttps://checkout.trustly.com/checkout?OrderID=1234567890&SessionID=...

Failed withdrawals

In case an error occurs when processing the withdrawal, a Credit notification will be sent to the provided NotificationURL so that the merchant can flag the withdrawal as failed in their system. And in case the end-user holds a balance on the merchant's system, the amount specified in the credit notification should be credited back to the end user's balance. Note that the credit notification will be sent AFTER the withdrawal has been successfully approved (either automatically or by sending ApproveWithdrawal.

There are 2 main reasons why a Withdrawal can fail after being approved:

  1. There are not enough funds on the merchant's Trustly account. In this case the credit notification will be sent immediately after the withdrawal has been approved.
  2. The funds are sent to the end user's bank account, but then later Trustly is notified by the bank that the transfer failed, for example if the recipient's bank account has been closed. This is usually very uncommon, but if it happens the credit notification can be sent several days after the Withdrawal has been approved.

Error codes

These error codes can be returned for Withdraw calls. To handle errors, see Error handling.

Error NumberError CodeDescription
602ERROR_FUNCTION_ACCESS_DENIEDThe merchant does not have access to this API method.
607ERROR_HOST_ACCESS_DENIEDThe IP address of the merchant has not been added to Trustly's IP-whitelist.
616ERROR_INVALID_CREDENTIALSThe username and/or password used in the API call is incorrect.
620ERROR_UNKNOWNThere could be several reasons for this error, please reach out to your Trustly contact for details.
636ERROR_UNABLE_TO_VERIFY_RSA_SIGNATUREThe 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 serialised incorrectly.
637ERROR_DUPLICATE_MESSAGE_IDThe MessageID has been used before.
638ERROR_ENDUSER_IS_BLOCKEDThe enduser that requested the withdrawal is blocked.
639ERROR_NO_PUBLIC_KEYNo public key has been configured for the merchant on Trustly's side.
645ERROR_INVALID_LOCALEThe Locale attribute is sent with an incorrect value.
696ERROR_ENDUSERID_IS_NULLThe EndUserID sent in the request is null
697ERROR_MESSAGEID_IS_NULLThe MessageID sent in the request is null
698ERROR_INVALID_IPThe IP attribute sent is invalid. Only one IP address can be sent.
700ERROR_MALFORMED_SUCCESSURLThe SuccessURL sent in the request is malformed. It must be a valid http(s) address.
701ERROR_MALFORMED_FAILURLThe FailURL sent in the request is malformed. It must be a valid http(s) address.
702ERROR_MALFORMED_TEMPLATEURLThe TemplateURL sent in the request is malformed. It must be a valid http(s) address.
703ERROR_MALFORMED_URLTARGETThe URLTarget sent in the request is malformed.
704ERROR_MALFORMED_MESSAGEIDThe MessageID sent in the request is malformed.
705ERROR_MALFORMED_NOTIFICATIONURLThe NotificationURL sent in the request is malformed. It must be a valid http(s) address.
706ERROR_MALFORMED_ENDUSERIDThe EndUserID sent in the request is malformed.
717ERROR_INVALID_ORDER_ATTRIBUTEOne or more attributes are sent with the incorrect value.
734ERROR_NOT_SECURE_NOTIFICATIONURLThe NotificationURL must be using HTTPS, not plain HTTP.