Trustly Introduction

Trustly is an open banking solution that allows users to make secure direct payments from their bank accounts to merchants. Trustly is a reliable alternative to traditional payment methods, supporting around 29 currencies ensuring instant payments, refunds and payouts.

Trustly via BR-DGE

Trustly as a payment solution offers a range of features including, iDEAL and Bancontact, recurring payments and payouts.

BR-DGE currently support the following features with Trustly:

• Payments & Deposits
  • Trustly
  • iDEAL
• Express Checkout
• Refunds
• Payouts
• Bank Account Tokenisation
  • SelectAccount
  • RegisterAccount
• Notifications

Onboarding for Trustly

When integrating Trustly via the BR-DGE platform, you are enabling BR-DGE to forward your request to Trustly on your behalf. To enable Trustly on your retail channel , please get in contact with support

Integration Methods

API

• Step 1 - Initiate Checkout
  Your customer proceeds to your checkout page
• Step 2 - Select Payment Method
  Your customer selects Trustly as payment method on your checkout page
• Step 3 - Backend Communication
  Your checkout page communicates with your server side system
• Step 4 - Payment Request to BR-DGE
  Your server side sends a Trustly payment request to BR-DGE

📘

Landing page URLs would need to be provided in this step

• Step 5 - Receive Trustly Response
  You will receive a BR-DGE payment response containing a redirect URL
• Step 6 - Redirect Customer to Trustly
  You redirect your customer to Trustly with the redirecturl returned from BR-DGE in step 5
• Step 7 - Customer Bank Account Selection
  Your customer selects their bank and then the account they wish to make the payment with

📘

Trustly will offer a list of accounts if your customer has several accounts

• Step 8 - Customer Approves Payment
  Your customer approves the payment
• Step 9 - Redirect to Landing Page
  You will redirect your customer to the appropriate landing page specified in Step 4 depending on the outcome of the deposit
  The payment should only be considered successful once you have received a notification confirming the payment has been captured. If you do not rely on notifications, once the state of the payment has moved to CAPTURED.
• Step 10 - Payment Confirmation Notification
  You will receive a BR-DGE notification confirming the outcome of the transaction
  Alternatively you can query the state of the payment to confirm the outcome of the transaction via the BR-DGE /v1/payments/{paymentId}/status endpoint.
• Step 11 - Payment Instrument Account Selection Notification
  You will receive a BR-DGE notification confirming the account used for the payment

Express Checkout

For returning customers, a streamlined Trustly payment can be made using an accountId obtained from the paymentInstrument.accountSelection in the response payload of an initial payment.

This flow provides an optimised experience for your customer by reducing the steps required to approve a payment in the redirect flow

You must ensure the payment.customerId is the same as the customerId from original Trustly payment.

📘

The steps to execute a Trustly Express Checkout are the same as a standard Trustly payment. The accountId should be included in the payment request to BR-DGE in Step 4.

Payouts via Trustly

• Step 1 - Payout request to BR-DGE
  Your server side sends a Trustly payout request to BR-DGE
• Step 2 - Receive Synchronous response
  You will receive a synchronous pending response from BR-DGE
• Step 3 - Payment Confirmation Notification
  You will receive a BR-DGE notification on the outcome of the payout

Hosted Payments Page

• Step 1 - Initiate Checkout
  Your customer proceeds to your checkout page
• Step 2 - Create HPP Order
  You create a BR-DGE HPP order
• Step 3 - Receive HPP Order response
  You will receive a BR-DGE HPP order response
• Step 4 - Redirect Customer to HPP
  Redirect your customer to the URL returned in step 4 to view the HPP
• Step 5 - Select Payment Method
  Your customer selects Trustly as the payment method
• Step 6 - HPP Redirects Customer to Trustly
  The HPP would redirect your customer to complete a Trustly redirect flow
• Step 7 - Customer Bank Account Selection
  Your customer would select the bank they wish to make the payment with
• Step 8 - Customer Approves Payment
  Your customer approves the payment
• Step 9 - Redirect to Landing Page
  Your customer is redirected to a landing page depending on the outcome of the payment
• Step 10 - Payment Confirmation Notification
  You will receive a BR-DGE notification confirming the outcome of the deposit
• Step 11 - Payment Instrument Account Selection Notification
  You will receive a BR-DGE notification with the accountId of the payment bank account

WebSDK

• Step 1 - Initiate Checkout
  Your customer proceeds to your checkout page
• Step 2 - Select Payment Method
  Your customer selects Trustly as a payment method on your checkout page using the BR-DGE webSDK
• Step 3 - Payment Request to BR-DGE Server
  Your server sends a Trustly payment request to BR-DGE
• Step 4 - Receive Trustly Response
  BR-DGE responds with a redirect action response
• Step 5 - Redirect Customer to Trustly
  The WebSDK will handle the redirect action and redirect your customer to complete the Trustly redirect flow
• Step 6 - Customer Bank Account Selection
  Your customer would select the bank they wish to make the payment with
• Step 7 - Customer Approves Payment
  Your customer approves the payment
• Step 8 - Payment Confirmation Notification
  You will receive a BR-DGE notification confirming the outcome of the deposit
• Step 9 - Payment Instrument Account Selection Notification
  You will receive a BR-DGE notification with the accountId of the payment bank account
• Step 10 - Redirect to Landing Page
  Your customer is redirected to a landing page depending on the outcome of the payment

Creating Trustly Transactions

Payment Request

To create a Trustly payment, send a /v1/payments request with its mandatory fields.

Example Trustly /v1/payments request

{
  "paymentInstrument": {
    "type": "trustly",
    "successUrl": "https://example.com/success",
    "errorUrl": "https://example.com/error"
  },
  "amount": 1000,
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "address1": "Flat 1",
    "address2": "Victoria House",
    "address3": "15 Apple Street",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB"
  },
  "currencyCode": "GBP",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerId": "Customer001",
  "customerLastName": "Smith",
  "customerOrderCode": "ABC123",
  "customerPhoneNumber": "+44 123 1110000",
  "orderDescription": "Taxi fare"
}

📘

It is possible to perform an iDEAL payment via Trustly. To perform an iDEAL payment via Trustly, set paymentInstrument.type to ideal

📘

A Trustly accountId can be passed in the payment request for an optimised user experience.

You should expect to receive a response similar to the following:

{
  "code": "2101",
  "message": "Pending",
  "id": "684fe672a1c518af6d4e087f1c704759",
  "paymentId": "99082428-491d-407b-b6d2-8559bc17f4b1",
  "actionRequired": true,
  "action": {
    "type": "REDIRECT",
    "paymentId": "99082428-491d-407b-b6d2-8559bc17f4b1",
    "data": {
      "providerTransactionId": "13082384720",
      "url": "https://checkout.test.trustly.com/checkout?OrderID=13082384720&SessionID=89f48989-c314-45dd-9a4f-5a65361f15b7"
    }
  },
  "psp": {
    "name": "Trustly",
    "transactionId": "13082384720"
  },
  "pspId": "TRUSTLY",
  "customerOrderCode": "ABC123"
}

The link returned in the action.data.url field should be used to redirect the payer to complete the payment.

Refund Request

To refund a Trustly payment, use the paymentId returned in the /v1/payments response.

Pass the paymentId as a path parameter to the /v1/payments/{paymentId}/refund endpoint to process a Trustly refund.

You should expect to receive a response similar to the following

{
  "code": 1000,
  "message": "Approved",
  "id": "4fad8e2e06a15656",
  "psp": {
    "name": "Trustly",
    "transactionId": "a83a53a2-dcc8-45be-bf70-2b1e4b719f7c"
  }
}

Payout Request

Payouts with Trustly can be performed via the BR-DGE /v1/payouts endpoint. You must provide a Trustly accountId when executing a Trustly payout.

A Trustly accountId can be obtained in different ways:

• The accountId will be sent after a payment via a paymentInstrument.accountSelection notification.
• The accountId can also be retrieved from a previous Trustly payment by querying the /v1/payments/{paymentId}/status endpoint
• If the customers bank account details are not available, use the /v1/payment-instrument-verifications endpoint to obtain an accountId.
  The accountId will be sent via a paymentInstrument.accountSelection notification.
• If you have the customers bank account details, use the /v1/payment-instrument-registrations endpoint to obtain an accountId.
  The accountId will be sent via a paymentInstrument.accountRegistration notification.

To perform a Trustly payout via BR-DGE, send a /v1/payouts request with the accountId specified in the paymentInstrument object

📘

The customerId from the Verify Account and Register Account steps should be the same passed as the customerId in the payout call..

{
    "psp": "trustly",
    "amount": 1,
    "paymentInstrument": {
        "type": "trustly",
        "accountId":"1891084940"
    },
    "currencyCode": "GBP",
    "recipient": {
        "firstName": "John",
        "ipAddress": "123.100.100.200",
        "lastName": "Smith",
        "customerId": "sampleId"
    },
    "reference": "reference",
    "purpose": "boats"
}

You should expect to receive a response similar to the following

{
    "code": "2101",
    "id": "6842ed46e4b3aee763ad9294ec1784ca",
    "message": "Pending",
    "paymentId": "1d64bed0-45e1-4669-854c-5e114fe72a93",
    "psp": {
        "name": "Trustly",
        "transactionId": "13019197993"
    }
}

📘

The synchronous response will always be “Pending”. The status of the payout will be updated asynchronously.

Register Account

Once you have the customers bank account details you want to make the payout to, send a request to the BR-DGE /v1/payment-instrument-registrations endpoint with the mandatory fields.

This step is used to register a bank account that is not already registered with Trustly.

Validation of the bank account details is your responsibility as the merchant.

{
  "type": "trustly",
  "customer": {
    "customerId": "customerId",
    "firstName": "Steve",
    "lastName": "Smith",
    "country": "GB",
    "postcode": "BH23 6AA",
    "town": "Edinburgh",
    "addressLine1": "Main street 1",
    "addressLine2": "Main street 2",
    "phoneNumber": "+46709876543",
    "email": "[email protected]",
    "dateOfBirth": "1990-02-19"
  },
  "bank": {
    "bankNumber": "200052",
    "clearingHouse": "UNITED_KINGDOM",
    "accountNumber": "75849855"
  }
}

You should expect to receive a response similar to the following.

{
    "type": "trustly",
    "code": "1004",
    "message": "Request succeeded",
    "id": "6842ecf2c7ca5e17718458b64fc12aab",
    "paymentInstrumentRegistrationId": "cc6bf638-7940-4a71-bc99-64e5426d5666",
    "accountId": "1891084940",
    "clearingHouse": "UNITED_KINGDOM",
    "bank": "Barclays Bank",
    "descriptor": "**849855"
}

Account Verification

Where the customers bank account details are not available and you want the customer to select the account the payout should be made to, send a request to the BR-DGE /v1/payment-instrument-verifications endpoint with the mandatory fields.

{
    "psp": "Trustly",
    "verificationDetails": {
        "type": "trustly",
        "firstName": "John",
        "lastName": "Smith",
        "customerId": "def456",
        "country": "GB",
        "locale": "en_GB",
        "email": "[email protected]",
        "ipAddress": "123.100.100.200",
        "documentId": "ABC-123456",
        "phoneNumber": "+44 123 1110000",
        "dateOfBirth": "2000-01-01"
    }
}

You should expect to receive a response similar to the following

{
    "id": "68498e0d66bc216d193e24b3b61bd5c0",
    "verificationId": "1affcb97-a71f-4714-aada-49e971d9aa13",
    "psp": "Trustly",
    "code": "2101",
    "message": "Pending: The operation has been accepted for processing and the outcome is not yet known",
    "verificationResult": {
        "type": "trustly",
        "actionRequired": true,
        "action": {
            "type": "REDIRECT",
            "data": {
                "url": "https://checkout.test.trustly.com/checkout?OrderID=13954400995&SessionID=3c764f4d-b611-4519-b8c8-f717ae300b4f"
            }
        }
    }
}

📘

The link returned in the redirectUrl field should be used to redirect the customer to select the account they wish to complete the payout with.

{
    "type": "trustly",
    "code": "1004",
    "message": "Request succeeded",
    "id": "6842ecf2c7ca5e17718458b64fc12aab",
    "paymentInstrumentRegistrationId": "cc6bf638-7940-4a71-bc99-64e5426d5666",
    "accountId": "1891084940",
    "clearingHouse": "UNITED_KINGDOM",
    "bank": "Barclays Bank",
    "descriptor": "**849855"
}

Notifications

A subset of Trustly notifications are supported on the BR-DGE platform. The following Trustly notification types are currently supported by BR-DGE:

• Account Notification
• Cancel Notification
• Credit Notification
• Debit Notification
• Payout Confirmation
• Payout Error

The table below indicates the notification you will receive according to a specific scenario

The following is an example of a Trustly “payout” notification via BR-DGE. Other BR-DGE notifications adopt the same format

{
  "type": "payout",
  "merchantAccountId": "trustlyOnly",
  "id": "09d4be51-1a21-4cc9-a81f-eefd7d075151",
  "code": "1000",
  "status": "APPROVED",
  "psp": {
    "name": "Trustly",
    "transactionId": "13440625218",
    "message": "{\"method\":\"payoutconfirmation\",\"params\":{\"data\":{\"amount\":\"1.00\",\"orderid\":\"13440625218\",\"currency\":\"GBP\",\"enduserid\":\"davidTestHappy\",\"messageid\":\"09d4be51-1a21-4cc9-a81f-eefd7d075151\",\"timestamp\":\"2025-06-06 14:25:23.799598+02\",\"notificationid\":\"11317584628\"},\"uuid\":\"44f644a6-54e0-4bbc-8999-1fded652603e\",\"signature\":\"cLybniT3AC6kFzvv3pgyO6K9pFCEgR4xuS5d+GVVLK0WCUJsxKlizitDqr2/S9u9tzRYBXpp05/Y6JfdMVaD7cPNxVrzdu8bqeynsxSf6fv8/iegBQmGqD8fzCm0gAvm8WW3hNdcTXpJfo0XCRwHWzGggfEl7PZQuwnetqzmukE7tERcKNYR9jdgRtZ1n497zo9mZ2FVFrZN4Z+/uQcEj9ZW5CKB5k+Teap4f0HaOGYORon6c5tEH+HTnQobkKseS61mnZoF08/Z2nFJGi1WD/AMQmdTmLmi/W4RYjucZVlP6D8PypnOYh4Kh5QoDQOsJhpk9w/1WeUVJcI8jfTBQA==\"},\"version\":\"1.1\"}"
  },
  "hashCode": "Ve6aEcQkYuZaTaLqK7iXzydcTMcl1VSu1eeh5D6m7k8="
}

Support

To get started with Trustly via BR-DGE, or if you have any questions, please get in contact with support.