Skip to main content
For non-United States payments please use the Trustly Europe connector.

​
Setup

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.

​
Integration

​
Redirect integration

The default integration for Trustly is through a redirect to a hosted payments page.
  • Redirect
  • Webviews (mobile)
Start by creating a new transaction with the following required fields.
POST /transactions
{
    "amount": 100,
    "currency": "USD",
    "country": "US",
    "intent": "capture",
    "payment_method": {
        "method": "trustly",
        "redirect_url": "https://example.com/callback",
        "country": "US",
        "currency": "USD"
    }
}
After the transaction is created, the API response includes a payment_method.approval_url and the transaction is set to buyer_approval_pending.
{
    "type": "transaction",
    "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
    "payment_method": {
        "type": "payment-method",
        "approval_url": "https://cdn.sandbox.spider.gr4vy.app/connectors/trustly/trustly.html?token=...",
       ...
    },
    "method": "trustly",
   ...
}
Redirect the buyer to the approval_url (open in a browser or Webview) 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.

​
Direct integration

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. 
POST /transactions

{
    "amount": 100,
    "currency": "USD",
    "country": "US",
    "intent": "capture",
    "integration_client": "web",
    "payment_method": {
        "method": "trustly",
        "redirect_url": "https://example.com/callback",
        "country": "US",
        "currency": "USD"
    }
}
After the transaction is created, the API response includes a session_token which can be used to get the session data for that transaction. 
POST /transactions/:transaction_id/session?token=:session_token

{
    "session_data": {
        "baseUrl": "https://sandbox.trustly.one",
        "establishData": {
            "amount": "0.00",
            "accessId": "Ev6e2YzsthnCLEefTdYs",
            "currency": "USD",
            "customer": {},
            "cancelUrl": "https://api.sandbox.spider.gr4vy.app/transactions/approve/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.cj9hcFjrQh6fPVGFQ2KVtw.MXnZvx-h4H5uWucMDQSXoM0KhZb9n0rl-S3KwxaX_to?gr4vy_store=false&cancel=true",
            "returnUrl": "https://api.sandbox.spider.gr4vy.app/transactions/approve/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.cj9hcFjrQh6fPVGFQ2KVtw.MXnZvx-h4H5uWucMDQSXoM0KhZb9n0rl-S3KwxaX_to?gr4vy_store=false",
            "merchantId": "1019347005",
            "description": null,
            "paymentType": "Deferred",
            "notificationUrl": "https://api.sandbox.spider.gr4vy.app/i/hWmg8tTgTA6MzV_7mz7-QnRydXN0bHktdHJ1c3RseQ/7XRgAbqH5nMLp9Xhg5err3odYmF7_07HYKHNcg9nSaI",
            "requestSignature": "2T1o/igBnnjYMYIf9g5MBE4nIb8=",
            "merchantReference": "3Ta5b7GDKE83rCysLkfFbD"
        }
    },
    "default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/approve/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.cj9hcFjrQh6fPVGFQ2KVtw.MXnZvx-h4H5uWucMDQSXoM0KhZb9n0rl-S3KwxaX_to?gr4vy_store=false",
    "integration_client": "web"
}
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 SDK
const { establishData, baseUrl } = response.session_data
const method = establishData.paymentType === "Verification" ? 'establish' : 'selectBankWidget'
const url = `${baseUrl}/start/scripts/trustly.js?accessId=${establishData.accessId}`

// Dynamically load the script with the access ID
const 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.

​
Limitations

  • 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.

​
Recurring payments

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.

​
Initial payment

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.
POST /transactions
{
    "amount": 1299,
    "payment_method": {
        "method": "trustly",
        "redirect_url": "https://example.com/callback",
        "country": "US",
        "currency": "USD"
    },
    "country": "US",
    "currency": "USD",
    "intent": "capture",
    "buyer_id": "9cedaaea-68fe-4f07-bf94-55225be98d0f",
    "store": true,
    "payment_source": "recurring",
    "merchant_initiated": false,
    "is_subsequent_payment": false
}

​
Subsequent payment

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.
POST /transactions
{
    "amount": 1299,
    "payment_method": {
        "method": "id",
        "id": "c31a7f72-dac4-469b-a00a-5e3607f57b01"
    },
    "country": "US",
    "currency": "USD",
    "intent": "capture",
    "buyer_id": "9cedaaea-68fe-4f07-bf94-55225be98d0f",
    "payment_source": "recurring",
    "merchant_initiated": true,
    "is_subsequent_payment": true
}

​
Renewing split token

In some situations, a recurring payment may fail because the Trustly “split token” has expired. 
{
    "type": "transaction",
    "id": "285771d9-afc1-4beb-a368-06e2cb03ec3a",
    "status": "authorization_declined",
    "method": "trustly",
    "raw_response_code": "326",
    "raw_response_description": "Expired 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. 
{
    "amount": 1299,
    "payment_method": {
        "method": "id",
        "redirect_url": "https://example.com/callback",
        "id": "c31a7f72-dac4-469b-a00a-5e3607f57b01"
    },
    "country": "US",
    "currency": "USD",
    "intent": "authorize",
    "buyer_id": "9cedaaea-68fe-4f07-bf94-55225be98d0f",
    "payment_source": "recurring",
    "merchant_initiated": false,
    "is_subsequent_payment": true,
    "connection_options": {
        "trustly-trustly": {
            "refreshSplitToken": true
        }
    }
}