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 the necessary data, 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.

Create a bank authorization

Walkthrough on calling the establish method and handling the mandated transactionId for future use.

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 expired sessions and relaunch the Lightbox to re-authenticate users without requiring full re-entry.

Recover insufficient funds (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 and accessKey) from Trustly Support.
Sign all required NDA and commercial agreements.
Configure your firewall to allow Trustly IP ranges (if applicable).

Create a bank authorization (Frontend)

Install the Trustly SDK (JavaScript, iOS, or Android).
Initialize the SDK with your accessId.
Implement the establish 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.

Handle event notifications (Webhooks)

Configure your notificationUrl in the Merchant Portal or per-transaction.
Implement a listener to handle Authorize, Debited, Credit, and Failed events.
Validate the cryptographic signature on all incoming webhooks.
Return a 200 OK status to Trustly upon successful receipt 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 full re-login.
Handle Denied events (such as Insufficient Funds) with appropriate user messaging.

See Refresh Bank Authorization.

Recover insufficient funds (Optional)

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

See Recover Insufficient Funds.