Trustly payouts

To use Trustly to pay out your suppliers or users, first you need to tokenize their bank account details, submit a payout request, and then confirm or decline the payout.

Before you begin

Before you can start sending payouts through Trustly, you need to:

1. Contact our Support Team to enable payouts. Using the Payout API requires additional approval and configuration on our end.
2. Have an existing integration that accepts Trustly payments. If you haven't integrated yet, refer to our integration guides.

Step 1: Tokenize Trustly payment details

To tokenize Trustly details for payouts, make a POST /payments request. In your request, additionally include:

In the example below, we send a request to tokenize the bank account details of a supplier with shopperReference Supplier_JaneSmith:

{
   "amount":{
      "value":0,
      "currency":"SEK"
   },
   "paymentMethod":{
      "type":"trustly"
   },
   "enablePayOut":true,
   "shopperReference":"Supplier_JaneSmith",
   "reference":"YOUR_ORDER_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}

When the supplier's bank account details has been saved and tokenized, you receive a notification webhook containing:

• eventCode: RECURRING_CONTRACT
• originalReference: The pspReference of the payment request.

Step 2: Submit a payout request

When you're ready to send a payout, make a POST /submitThirdParty request, specifying the following parameters:

{
"amount" : {
        "currency" : "EUR",
        "value" : "1000"
    },
    "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
    "recurring" : {
        "contract" : "PAYOUT"
    },
    "reference" : "YOUR_PAYOUT_REFERENCE",
    "shopperEmail" : "supplierjanesmith@email.com",
    "shopperReference" : "Supplier_JaneSmith",
    "selectedRecurringDetailReference" : "LATEST"
}

The response contains:

• pspReference - Unique identifier for this payout request. Save this, as you'll need this identifier to review the payout, and to know the payout result.
• resultCode [payout-submit-received] - Confirmation that the payout request has been received. The result of the payout will be sent in a notification webhook.

{
  "pspReference" : "9913140798220028",
  "resultCode" : "[payout-submit-received]"
}

Step 3: Confirm or decline the payout

Review the payout and make either a POST /confirmThirdParty or POST /declineThirdParty request, specifying:

• originalReference: The PSP reference of the payout request, which you received in the /submitThirdParty response.

In the example below, we confirm the payout request with PSP reference 9913140798220028:

{
  "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
  "originalReference" : "9913140798220028"
}

The response contains:

• pspReference - Unique identifier for this confirm or decline request.
• resultCode - Depending on the request that you made, you receive a [payout-confirm-received] or [payout-decline-received]. This is the confirmation that the payout confirm or decline request has been received.

{
  "pspReference" : "991169882599179B",
  "resultCode" : "[payout-confirm-received]"
}

Step 4: Confirm payout result

Wait for the notification webhook to confirm the payout result. The notification webhook contains:

• originalReference: The PSP reference of the payout request, which you received in the /submitThirdParty response.
• pspReference: The PSP reference of the confirm or decline request, which you received in the /confirmThirdParty or /declineThirdParty response.

• eventCode: Depending on the result of the payout request, you receive any of the following event codes.

  eventCode	Description
  PAYOUT_THIRDPARTY	The user reviewing the payout confirmed it. The success field indicates whether we received the payout request. Possible values of the success field: true - We received your payout request, and will send it to the financial institution. When approved, the funds are paid out within 2 business days. In case the financial institution rejects the request, you will receive a notification with eventCode: PAIDOUT_REVERSED. false - The request failed. The reason field includes a short description of the issue. Review the reason, fix the issue if possible, and resubmit the payout request.
  PAYOUT_DECLINE	The user reviewing the payout declined it. The success field of this notification is always set to true.
  PAYOUT_EXPIRE	7 days have passed since the payout was submitted, and the reviewer has neither confirmed nor declined it. The success field of this notification is always set to true.
  PAIDOUT_REVERSED	The financial institution rejected the payout. We will return the funds back to your account. Check with the supplier or user the status of their bank account.

Below is an example of a successful payout request notification, with eventCode PAYOUT_THIRDPARTY:

{
    "live" : "false",
    "notificationItems" : [
        {
            "notificationRequestItem" : {
                "amount" : {
                    "value" : 1000,
                    "currency" : "EUR"
                 },

                "eventCode" : "PAYOUT_THIRDPARTY",
                "eventDate" : "2020-04-24T12:59:53+02:00",
                "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
                "merchantReference" : "YOUR_PAYOUT_REFERENCE",
                "paymentMethod" : "trustly",
                "{hint: The PSP reference of the payout request in step 2}originalReference{/hint}" : "9913140798220028",
                "{hint:The PSP reference of the confirm payout request in step 3}pspReference{/hint}" : "9911698825991739B",
                "reason" : "Approved",
                "success" : "true"
            }
        }
    ]
}