Refresh bank authorization

If a user's bank authorization expires or is invalidated (for example, due to a password change or a security update at the bank), you must re-authenticate the user to continue processing payments.

Trustly provides a mechanism to detect these scenarios and relaunch the Lightbox to restore connectivity without requiring the user to select their bank or their preferred bank account again.

Prerequisites

Original transaction ID: The ID of the transaction that requires re-authentication. If you're missing the ID, use the List transactions endpoint to search for the original transaction using your merchantReference.

Detect a required refresh

When you attempt a capture or a data refresh request, you may receive a failure response indicating that the session is no longer valid.

Common indicators

Monitor your API responses and event notifications for the following error codes:

Error Code: SW057 (Expired Split Token)
Error Code: SW051 (Invalid or corrupt Split Token)

When you encounter these errors, you must prompt the user to re-authenticate.

Relaunch the Lightbox

To refresh the authorization, you must launch the Trustly Lightbox again using the specific parameters associated with the original transaction. This flow differs slightly from the initial setup because you are updating an existing connection rather than creating a new one.

Required parameters

The following table lists the parameters required to relaunch the Lightbox for a refresh flow.

Parameter	Description
`paymentType`	The type of payment originally established. For example, `Verfication`.
`transactionId`	The ID of the original transaction you are attempting to refresh.
`authtoken`	A secure token generated during a successful authorization. You store this token to identify returning users, allowing them to skip the bank login step for future payments. Enter `new`.

Implementation example

Call the establish method with the required parameters to trigger the refresh flow.

var refreshData = {
  accessId: 'YOUR_ACCESS_ID',
  merchantId: 'YOUR_MERCHANT_ID',
  merchantReference: 'refresh-order-123',
  paymentType: 'Verification', 
  transactionId: '1002636615', // The original transaction ID
  authToken: 'new'
};

Trustly.establish(refreshData, {
  closeButton: true,
  dragAndDrop: false,
  widgetContainerId: 'widget-container'
});

Once the user successfully completes the workflow, Trustly issues a new Authorize event with a fresh splitToken. You must update your system with this new token for future requests.