Core Concepts

Redirect URLs

View as Markdown

Redirect URLs return users back to your application after they interact with the Trustly UI. When a user completes or cancels a workflow, the SDK redirects them to your specified returnUrl or cancelUrl, respectively. These URLs capture critical transaction data through query parameters, which you can use to verify status, call Trustly APIs, or guide the user to the next step.

Receive the redirect

Trustly returns the user to your application using a GET request, appending several fields to the URL. You can parse this data in your backend to handle the transition.

Preventing tampered redirects

To ensure the redirect is secure and authentic, perform the following checks:

  • Verify that the merchantReference on the return URL matches the unique value you sent in the establishData Object for this session.
  • Validate the request payload by verifying the Redirect Signature in your backend.
  • Alternatively, instead of signature validation, call the Get Transaction API to confirm that the API response values match the parameters received in the redirect URL.

Example cancel URL

https://merchant.com/trustly.com/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D

Example return URL

“text https://merchant.com/trustly.com/return?transactionId=1002633191&transactionType=1&merchantReference=123123&status=2&payment.paymentType=2&payment.paymentProvider.type=1&payment.account.verified=false&panel=1&requestSignature=b7yr%2F3qOupPa1B7VeI32PhGQ7C8%3D

## Process the return URL
Upon receiving a successful redirect to your `returnUrl`, you should associate the account on file with the provided `transactionId`.
If you are using the Split Token flow, you must also verify the corresponding incoming `Authorize` webhook event associated with this `transactionId` and store the `splitToken` provided in that event alongside the account details.
## Parameters
The following table outlines the parameters appended to the redirect URL and provides their definitions.
| Parameter                                 | Definition                                                                                                                                                                                                                                                      |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId`                             | A unique Trustly transaction identifier. (15 characters)                                                                                                                                                                                                        |
| `transactionType`                           | See [Transaction Types](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-types) for a complete list of values and their definitions.                                                                                                                                        |
| `merchantReference`                         | A specific merchant reference for this cancellation. For example, this could be your order number or session ID.                                                                                                                                                |
| `status`                                    | See [Transaction Status Values](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-status-values) for a complete list of values and their definitions.                                                                                                                        |
| `payment.paymentType`                       | See [Payment Types](/integrate/api-fundamentals/status-codes-and-type-definitions#payment-types) for a complete list of values and their definitions.                                                                                                                                                |
| `payment.paymentProvider.type`              | See [Payment Provider Types](/integrate/api-fundamentals/status-codes-and-type-definitions#payment-provider-types).                                                                                                                                                                                   |
| `payment.account.verified`                  | Boolean status indicating if the bank account was verified during the flow.                                                                                                                                                                                     |
| `panel`                                     | Integer value representing the Trustly screen the user exited the flow on. Refer to [Panel Values](/integrate/api-fundamentals/status-codes-and-type-definitions#panel-values) for a complete list of values and their definitions.                                                                  |
| `payment.paymentProviderTransaction.status` | Integer value representing the Payment Provider Transaction Status of the transaction. Refer to [Payment Provider Transaction Status](/integrate/api-fundamentals/status-codes-and-type-definitions#payment-provider-transaction-status-values) for a complete list of values and their definitions. |
| `requestSignature`                          | This is a signature that you can calculate to ensure the request you receive is coming from Trustly. See [Verifying the Redirect Request](/integrate/api-fundamentals/secure-requests-and-signature-validation#validate-the-redirect-signature) for more information.                                          |