Trustly (US)

​

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 Gr4vy to your environment 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.

​

New Beta experience

A new Trustly (US) - Beta connector is currently available in some sandbox environments under the trustlyncf-trusly ID. This connector supports recurring payments, delayed capture, and uses the latest Trustly experience.

​

Usage

To use the new connector, select the Trustly (US) - Beta connector in the connections catalog and enable it with the same credentials as you currently use for the existing connector. Once enabled, you can either disable the old connector or use a Flow rule to route payments to this new connector.

​

Recurring payments

This new Beta release supports recurring payments via the API and via Embed. If you are using Gr4vy 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": {
        "trustlyncf-trustly": {
            "refreshSplitToken": true
        }
    }
}

​

Migration

Once you’ve tested the new Beta connector and ensured everything is working accordingly, please notify our support team and we will migrate the existing connector (trustly-trustly) to the new release. At that point the Beta connector (trustlyncf-trustly) may stop working.