Integration checklist

See Branding requirements

• Cancel flow: If a user clicks ‘Cancel’ in the Trustly Lightbox, ensure your application returns them to your checkout selection page, not an error page.
• Error messages: If Trustly declines a transaction, display a friendly message asking the user to try again or choose a different bank, rather than a generic ‘System Error’.
• Mobile responsiveness: Test the integration on a mobile device to ensure the Trustly Lightbox does not overlap with your site navigation bars or headers.

See Generate request signatures

• Request signatures: Ensure your backend generates a unique requestSignature for every Establish call. Never hardcode signatures or generate them on the client side.
• Webhook validation: Verify your webhook listener validates the signature in the header of every incoming notification to prevent spoofing.
• PII handling: Pass Personally Identifiable Information (Names, Emails) only in the customer object. Never pass PII in the description field.
• Script source: Load the Trustly SDK directly from trustly.one. Do not host the script file on your own servers.

See Manage transactions

• Establish Data parameters: Ensure your establishData payload includes all required customer and metadata fields before initiating a transaction.
• Transaction IDs: Ensure your database stores the Trustly transactionId returned in the redirect URL and webhook. You need this ID for all future refunds or support requests.
• Async fulfillment: Verify your system fulfills orders based on the COMPLETED webhook event, not just the user redirect to the success page.
• Split tokens (Trustly Pay): If using Trustly Pay, capture and store the splitToken to enable one-click payments for returning users.
• Duplicate handling: Ensure your webhook listener handles duplicate events idempotently. For example, if Trustly sends the same Success webhook twice, do not duplicate the payment.