Trustly
Trustly is a digital payment provider that offers a bank-independent payment service allowing users to pay directly from their bank account.
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 theredirecturl
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 theaccountId
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
toideal
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 apaymentInstrument.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
.
TheaccountId
will be sent via apaymentInstrument.accountSelection
notification. - If you have the customers bank account details, use the /v1/payment-instrument-registrations endpoint to obtain an
accountId
.
TheaccountId
will be sent via apaymentInstrument.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 thecustomerId
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
Scenario | Event | BR-DGE Notification Type | Notification Reason |
---|---|---|---|
Deposits | Account Selection | paymentInstrument.accountSelection | The accountId of a Bank Account used for a Trustly payment |
Payment Captured | Payment | The funds for an authorized payment have been successfully requested for transfer. | |
Payment Capture Failed | Payment | An attempt to finalize the payment capture was unsuccessful. | |
Refunds | Refund Succeeded | Refund | The funds for an authorized refund have been successfully requested for transfer. |
Refund Failed | Refund | An attempt to finalize the refund was unsuccessful. | |
Payouts | Payout Succeeded | Payout | The funds for an authorized payout have been successfully requested for transfer. |
Payout Failed | Payout | An attempt to finalize the payout was unsuccessful. | |
Account Verification | Account Verified | paymentInstrument.accountSelection | A Trustly Payment Instrument has been verified |
Account registration | Account Registered | paymentInstrument.accountRegistration | A Trustly Payment Instrument has been registered |
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.
Updated about 10 hours ago