Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Trustly payouts

Use Trustly to send payouts your suppliers or users.

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:

Parameters Description
amount The value (in minor units) and currency. Set the value to the payment value if you want to tokenize payment details while accepting a payment, or to 0 if you just want to tokenize and save Trustly details for future payouts.
enablePayout Set this to true to tokenize the details for payout.
shopperReference Your unique identifier for the supplier or user.

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

POST /payments request
{
   "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:

Parameters Description
merchantAccount The merchant account identifier you want to process this payout transaction request with.
amount The value (in minor units) and currency of the payout.
shopperReference The unique identifier for the supplier or user, which matches what you sent when you tokenized their details in the /payments request.
shopperEmail Email address of the supplier or user you're paying out to.
recurring Set this to PAYOUT.
reference Your identifier for this payout request.
selectedRecurringDetailReference Set this to LATEST.
POST /submitThirdParty request
{
"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.
Response
{
  "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:

POST /confirmThirdParty request
{
  "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.
Response
{
  "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:

    Notification webhook
    {
        "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"
                }
            }
        ]
    }