Integrate Trustly Pay

Integrate Trustly Pay into your application to allow consumers to authenticate with their bank and authorize transactions. The information provided here guides you through the process of creating a bank authorization, retrieving bank account information, initiating payment transactions, and handling event notifications to offer your consumers a secure and efficient payment experience.

Complete these topics to implement Trustly Pay.

About Trustly Pay

Learn how Trustly Pay enables secure, direct-to-bank transactions with online banking authentication to reduce fraud and costs.

Instant payments

Enable real-time money movement usning Real-Time Payments (RTP) and the FedNow networks for immediate fund availability.

Create a bank authorization

Walkthrough on initiating the Trustly Lightbox.

Process payments

Initiate funds movement using the Capture or Deposit APIs, including optional pre-authorization requests.

Handle event notifications

Implement event notifications to receive real-time transaction status updates and manage authorization validity.

Refresh bank authorization

Detect when an authorization needs to be refreshed and relaunch the Trsutly Lightbox to re-authenticate users.

Retry payment with a lower amount (optional)

Leverage actionable data from failure events to help users retry transactions with a lower amount.

Implementation checklist

Use this checklist to confirm that all required tasks are complete for your Trustly Pay integration.

Environment setup

Obtain sandbox credentials (accessId, merchantId, and accessKey) from your Trustly integration team.
Sign all required NDA and commercial agreements.
Configure your firewall to allow Trustly IP ranges (if applicable).

Create a bank authorization (Frontend)

Load or include the Trustly SDK (JavaScript, iOS, or Android).
Initialize the SDK with your accessId.
Implement the establish (recommended) or selectBankWidget method with the required establishData.
Configure the returnUrl and cancelUrl to handle user redirects.

See Create a Bank Authorization.

Process payments

Implement the Capture API to debit funds (Payin) from the user.
Implement the Deposit API to credit funds (Payout) to the user (if applicable).
Handle PENDING and AUTHORIZED response statuses correctly (do not treat them as final settlement).

See Process Payments.

Instant payments (Optional)

Verify that your commercial contract includes RTP/FedNow processing.
Implement logic to check if the user's account is eligible for real-time networks.
Set the required paymentType or delivery parameters in your API request.

See Implement Instant Payments.

Handle event notifications (Webhooks)

Confirm your Trustly integration team has configured your notificationUrl.
Implement a listener to handle events.
Validate the cryptographic signature on all incoming webhooks.
Return a 200 OK status to Trustly upon successful receipt and processing of an event.

See Handle Event Notifications.

Maintenance and error handling

Implement logic to handle expired Split Tokens (Error SW057).
Build the Refresh flow to relaunch the Lightbox without requiring bank and account selection.
Handle Denied events (such as Insufficient Funds) with appropriate user messaging.

See Refresh Bank Authorization.

Retry payment with a lower amount (Optional)

Enable the feature with your Trustly account manager.
Handle SW021 and SW054 errors by checking the suggestedRetryAmount.
Prompt users to retry with a lower amount.

See Recover Insufficient Funds.