For non-US payments please use the Trustly Europe connector.

​
Sign-up

A Trustly account can be requested by contacting their sales team via the Trustly website.

​
Credentials

When setting up Trustly in the dashboard, you will need to configure the following credentials, which can all be obtained from Trustly after your 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.

​
Limitations

  • Most API calls in Trustly are asynchronous and therefore captures and refunds will be in a pending state until we receive a notification. It’s important to set up webhooks from our 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.

​
Webview integrations

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 we have added support to pass the urlScheme required for this integration. When passing this value, we will forward this to Trustly, as well as the integrationContext, allowing for your 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 our API.
  • In your application, load the approval_url provided from our API into your applications webview.
  • We pass your urlScheme as well as the right integrationContext to the establishData as defined in the Trustly guide.
  • Your application listens to all the various callbacks from Trustly as defined in the Trustly guide.
  • When the transaction completes, your app invokes window.Trustly.proceedToChooseAccount(); on the webview as defined in the guide.
  • Our hosted page gets notified by the Trustly lightbox and completes the payment

​
Recurring payments

This connector supports recurring payments via the API and via Embed. If you are using Embed, we will handle most of the complexity for you, but for direct API integrations it’s important to ensure the right recurring payment flags are sent on the initial and subsequent payments.

​
Initial 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 will ensure a customer-present flow is triggered and a payment method is created that keeps track of Trustly’s “split token”. 
{
    "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
}

​
Recurring payments

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 will ensure a customer-not-present flow is triggered with the stored split token. 
{
    "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 an expired 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, you will need to reach out to your 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 your 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
        }
    }
}