When setting up Trustly in the dashboard, configure the
following credentials, which can all be obtained from Trustly after the account has been created.
Access ID - The identifier that acts as a username when connecting to the Trustly API.
Access Key - The key that acts as a password when connecting to the Trustly API.
Merchant ID - The ID that is used to target the specific merchant account to process payments for.
Redirect the buyer to the approval_url so they can complete authentication and approve the payment.
After approval the buyer is redirected to the redirect_url provided when creating the transaction.
Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example capture_succeeded or failure states).
In sandbox, use the Demo Bank and any credentials to simulate a successful flow.
For applications that use a multi-platform architecture, in which a web-based checkout experience is
embedded in a mobile app via a Webview, attention must be paid to ensure Trustly is integrated successfully.In addition to the Trustly guide on this topic,
support has been added to pass the urlScheme required for this integration. When passing this value, this is forwarded to Trustly, as well
as the integrationContext, allowing for the integration to listen to webhooks.In short, the flow would be as follows.
When creating a Trustly transaction, pass the urlScheme = "YOUR_APP://SOME_RESOURCE" property to the API.
In the application, load the approval_url provided from the API into the application’s webview.
The urlScheme as well as the right integrationContext are passed to the establishData as defined in the Trustly guide.
The application listens to all the various callbacks from Trustly as defined in the Trustly guide.
When the transaction completes, the app invokes window.Trustly.proceedToChooseAccount(); on the webview as defined in the guide.
The hosted page gets notified by the Trustly lightbox and completes the payment.
Trustly provides web and mobile SDKs for an in-context (direct) integration. For these flows, indicate the platform by setting an appropriate integration_client
when creating the transaction, and then build a client-side integration that uses the POST /transactions/:transaction_id/session API to initialize the Trustly SDK.To start, create a new transaction with the appropriate integration_client.
This session data provides the establishData required to load the Trustly SDK.
// Determine the URL of the script, and the method to invoke on the Trustly SDKconst { establishData, baseUrl } = response.session_dataconst method = establishData.paymentType === "Verification" ? 'establish' : 'selectBankWidget'const url = `${baseUrl}/start/scripts/trustly.js?accessId=${establishData.accessId}`// Dynamically load the script with the access IDconst script = document.createElement("script");script.src = url;script.onload = () => { // Initialize the Trustly SDK and attach it to the #component Trustly[method](establishData, { hideCloseButton: true, dragAndDrop: true, widgetContainerId: "component", });};document.head.appendChild(script);
Please refer to the Trustly documentation for the web and mobile SDKs for further guidance.
View a complete, ready-to-run example for direct Trustly Web SDK integration on GitHub. The repository includes setup instructions, session initialization, sample client code for loading the Trustly script, and guidance for handling redirects and webhooks.
RecommendedOn mobile integrations, after the buyer completes the payment flow, the Trustly SDK provides the developer with the transactionId and status.The system automatically syncs the status through webhooks, but to complete the transaction it is also recommended to send a GET request to the default_completion_url
provided in the session response with the transactionId and the status as query parameters to finalize the transaction. This also moves the transaction
to a completed status without waiting for the webhook to be sent.The call returns a 204 No Content response. After receiving this response, you can also optionally fetch the transaction to confirm final status.
// Define two functions to handle callbacks and pass them into the onReturn and onCancel parameters of the establish method.lightboxView.establish(establishData) .onReturn( (TrustlyCallback { lightboxView: Trustly, returnData: Map<String, String> -> val transactionId = returnData["transactionId"] val status = returnData["status"] // append transactionId and status to the `default_completion_url` val uri = Uri.parse(defaultCompletionUrl) .buildUpon() .appendQueryParameter("transactionId", transactionId) .appendQueryParameter("status", status) .build() val approvalUrl = URL(uri.toString()) // placeholder function to call the approval url makeRequest(approvalUrl) redirectToScreen(Callback.RETURN) }) ).onCancel( (TrustlyCallback { lightboxView: Trustly, cancelData: Map<String, String> -> redirectToScreen(Callback.CANCEL) }) )
For more information refer to the iOS and Android documentation.
Most API calls in Trustly are asynchronous and therefore captures and refunds are in a pending
state until a notification is received. It’s important to set up webhooks from the environment to yours in
order to be notified of these status changes.
Partial refunds are supported. However, another refund cannot be initiated while there is an
outstanding in-progress refund.
This connector supports recurring payments via the API and via Embed. If using Embed,
most of the complexity is handled, but for direct API integrations it’s important to ensure
the right recurring payment flags are sent on the initial and subsequent payments.
For an initial recurring payment, please make sure to use a suitable payment_source (either recurring or card_on_file)
and the merchant_initiated and is_subsequent_payment flags are set to false. This ensures a customer-present flow is
triggered and a payment method is created that keeps track of Trustly’s split token.
For a subsequent recurring payment, please make sure to use the same payment_source (either recurring or card_on_file)
and the merchant_initiated and is_subsequent_payment flags are set to true. This ensures a customer-not-present flow is
triggered with the stored split token.
In this situation, reach out to the customer to renew their agreement. This can be done by
setting the refreshSplitToken on a new customer-present transaction. It is important in this request to
set a redirect_url to redirect the user back to the site after they have approved the transaction.
