Withdraw

Introduction

Initiates a new withdrawal, returning the URL where the end-user can complete the withdrawal process.

You can find more information about how to display the Trustly URL here.

A typical withdrawal flow is:

1. The merchant sends a Withdraw API call and receives a URL back from Trustly's API.
2. The merchant displays the Trustly URL to the end-user (you can find more information about how to display the Trustly URL here).
3. The end-user selects the amount to withdraw and provides his/her bank account details.
   1. If the Withdrawal process is not completed, a cancel notification is sent.
4. When the end-user has completed the withdrawal process using the Trustly URL, Trustly sends a debit notification to the merchant's NotificationURL . The merchant should try to deduct the specified amount from the end-user's balance in the merchant's system.
   1. If the merchant is able to deduct the amount from the user's balance, the debit notification response should be sent with "status" : "OK".
   2. If the merchant is NOT able to deduct the amount from the user's balance, the debit notification response should be sent with "status" : "FAILED". The withdrawal is then aborted on Trustly's side and an error message is shown to the end-user. A cancel notification is sent to the merchant.
5. (Optional) An account notification is sent to provide the merchant with more information about the account that was selected by the end user. This notification is not enabled by default, please reach out to your Trustly contact if you want to receive it. This information can be used by the merchant to determine if the Withdrawal should be approved or not (see next step).
6. If manual approval is required, Trustly does nothing with the withdrawal request until it has been approved or denied by the merchant with ApproveWithdrawal / DenyWithdrawal (it is also possible for the merchant to approve or deny the withdrawal in Trustly's backoffice). Auto-approval can be enabled if requested.
   1. If DenyWithdrawal is sent, the withdrawal is aborted on Trustly's side and a cancel and credit notification is sent to the merchant.
7. If the Withdrawal is approved, Trustly will process the withdrawal.
8. (Optional) A Payout confirmation notification is sent to the merchant when the transfer has been confirmed. Note: this notification is not enabled by default. Please speak to your Trustly contact if you want to have it enabled.
9. If the withdrawal fails, Trustly will send a credit notification and a cancel notification (see more details below under "Failed Withdrawals").

Request parameters

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

Attributes

🚧

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

Response

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

Request and Response examples

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

{
    "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.

In case something is wrong in the Withdrawal API call itself, you will receive a synchronous API error code. A list of the most common error codes can be found here.