logo
Trustly Docs
BETA

Withdraw

Let customers make withdrawal
Updated 8 days ago
Please note - Withdraw is no longer offered to new merchants

Please see AccountPayout instead.

Overview

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

Request parameters

Request example

Request
{
  "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": "test@trustly.com",
        "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"
}

Response attributes

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

Response example

Response
{
    "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"
}

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.