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.

​
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
        }
    }
}