Trustly enables simple and secure direct bank payments. This is performed using a combination of User Interface flows established via the Trustly SDK and back-end API calls.

Trustly offers 3 SDK's to support the front-end user interactions. These SDKs support JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish, which support different user interfaces (so you only need to implement one).

Conceptually, there are two major steps:

1. Request a mandate from the consumer, allowing access to their bank account. This mandate is commonly referred to as an Authorization and is identified via a transactionId, and can thereafter be used for multiple payments.
2. Perform the specific payment or payments against that mandate. These may include funds capture preauthorization, funds capture, and/or funds deposit (payout).

In addition, you can ask for user and bank account information so you can represent it to the user as necessary.

There are several flows of interest.

1. Create a Bank Authorization using Online Banking. This step is initiated by calling the establish method of the SDK and launches the Trustly Online Banking interface which allows a User to authenticate with their Bank and authorizes you to use that bank for payment transactions. The successful call results in the mandate aka authorization represented by the returned transactionId. All subsequent API calls that result in the actual payment will be against this transactionId.
2. Display Bank or User PII from Trustly. With a valid transactionId, you can use the Trustly Get Transaction API and Get Financial Institution User API to retrieve information from the User's selected bank to display, verify, or pre-fill fields on your site or application.
3. Create a Transaction from the Bank Authorization. When the User requests to make a payment or requests a payment from you, you can use the Trustly Capture API or Deposit API, passing the previously obtained transactionId, amount, and a merchantReference that will be passed back to you in any event notifications, allowing you to manage the context associated with the payment request. You can also optionally first perform a capture preauth request, which performs the risk analysis and funds availability for the indicated amount, so that you can perform the actual Capture later.
4. Handle Event Notifications. The payment transaction returns a PENDING or ERROR response. Implement Trustly Event Notifications to receive transaction status updates in real time and message your customers accordingly.
5. Refresh a Bank Authorization using Online Banking. An authorization can become invalidated, for example, if the user cancels the mandate or it expires. If that happens, you'll want to send the User back to Online Banking to select a new Bank or refresh their Bank Authorization.

Integration Options and Branding Requirements

Trustly offers two types of user experiences for its Online Banking solution: Trustly Widget and Trustly Lightbox.

The Trustly Widget represents a bank-selection shortcut. It is shown in-line on your page and highlights the most popular bank while adding the capability to quickly search for a bank not expressly represented. Selecting one of the buttons on the Widget opens the Trustly Lightbox, where the User can sign in and authorize their account for use.

Alternatively, you can trigger the Trustly Lightbox using your own button. The Trustly Lightbox opens over your existing page in a mobile environment and presents a longer list of banks.

In addition to determining if the Select Bank Widget or opening the Trustly Lightbox directly is the best option for you, Trustly has a number of Branding Requirements to consider. If you have any questions or specific requirements, please work with your Trustly team or email [email protected].

Create a Bank Authorization (mandate) using Online Banking

The Trustly Online Banking Payment service enables end-users to pay or be paid by signing in to their online banking interface within your website or app. The Trustly User interaction can be completed in 3 simple steps:

1. The User selects Online Banking as a payment method on your website or app, which you link to the SDK selectBankWidget call to open the Trustly Widget (which then launches the Trustly Lightbox) or to the SDK establish call which launches the Trustly Lightbox directly.
2. From the Trustly Lightbox, the user authenticates with their bank and selects the account they wish to use for the transaction.
3. Once authorized, the User is then returned to the returnUrl passed to the appropriate SDK call, adding the transactionId, at which point you can continue to process the transaction.

Integrate the Trustly SDK into your flow.

As mentioned above, Trustly offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish. Each method accept 2 parameter objects, options and establishData. The options parameter is optional and can be used to control pieces of the Lightbox experience. The establishData parameter is used to pass transaction parameters to Trustly that are used when establishing the Bank Authorization transaction.

The following examples are using the JavaScript SDK

1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId} with the Access Id provided to you by Trustly):

<script src="https://sandbox.trustly.one/start/scripts/paywithmybank.js?accessId={accessId}"> </script>

2. To provide optional Trustly configuration options, create a TrustlyOptions object:

var TrustlyOptions = {
  closeButton: false,
  dragAndDrop: false,
  widgetContainerId: "widget-container-id" //Page element container for the widget
};

For details on the Trustly configuration options, refer to the SDK Specification.

3. To provide the transaction details to the SDK, create an establishData object:

var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: 'transaction description',
  currency: "USD|CAD",
  amount: "0.00",
  merchantReference: "merchant reference",
  paymentType: "Deferred",
  verification: {
    verifyCustomer: true,
  },
  customer: {
    externalId: "12345",
    name: "Joe User",
  },
  returnUrl: "https://merchant.com/trustly.com/return",
  cancelUrl: "https://merchant.com/trustly.com/cancel"		
};

🚧

Warning

Electronic Gaming clients are required to pass verifyCustomer as true and pass the customer object for verification.

🚧

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

📘

Tip

Ensure you're securing your call by including the requestSignature parameter.

📘

Tip

If you will be sending the user back to some sort of review screen before completing their transaction, pass an amount of 0.00 in the establishData object. You will need to ensure you show the user the final transaction amount before they complete the transaction on your side. Otherwise, pass the final transaction amount in the amount field of the establishData object. This will be shown throughout the Trustly Lightbox. The user will click the Pay button in the Trustly Lightbox before being returned to your site, where you will use the Capture API to complete the transaction.

4. Finally, call the Trustly SDK's establish or selectBankWidget function:

Select Bank Widget

Trustly.selectBankWidget(establishData, TrustlyOptions);

Establish

Trustly.establish(establishData, TrustlyOptions);

The following is a full HTML page using the above example.

📘

Info

Replace the {accessId} and {merchantId} with the values provided to you by Trustly.

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var TrustlyOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget',
      };
    </script>
    <script src="https://sandbox.trustly.one/start/scripts/paywithmybank.js?accessId={accessId}"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
  </body>
   <script>
    var establishData = {
      accessId: {accessId},
      merchantId: {merchantId},
      merchantReference: {merchantReference},
      description: 'transaction description',
      currency: 'USD',
      amount: '0.00',
      paymentType: 'Deferred',
      customer: {
            name: 'John Smith',
            address:{
                    country: 'US'
                },
            },
      returnUrl: 'https://merchant.com/trustly.com/return',
      cancelUrl: 'https://merchant.com/trustly.com/cancel'      
    };
    Trustly.selectBankWidget(establishData, TrustlyOptions);
  </script>
</html>

Handle the redirect

If the User cancels the request, Trustly will direct the User to your provided cancelUrl. If the User successfully authorizes the request, Trustly will direct the User to your provided returnUrl.

Once you get a successful redirect to your returnUrl, add the account on file with the provided transactionId. If applicable, also check the corresponding incoming Authorize webhook event associated with this transactionId and add the splitToken provided in that event alongside the account on file.

Example Cancel URL

https://merchant.com/trustly.com/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D

Example Return URL

https://merchant.com/trustly.com/return?transactionId=1002633191&transactionType=1&merchantReference=123123&status=2&payment.paymentType=2&payment.paymentProvider.type=1&payment.account.verified=false&panel=1&requestSignature=b7yr%2F3qOupPa1B7VeI32PhGQ7C8%3D

Redirect URL Parameters

Trustly will append the following parameters to your returnUrl or cancelUrl:

Display Bank or User PII from Trustly

With a valid Bank Authorization, use the Trustly Get Transaction API to retrieve information about the Users bank account that can be displayed in their account on your system. You can also use the Trustly Get User API to retrieve personal information (name, address, email, etc) that can be used to pre-fill fields on your flow or verify the information you have already collected from the User.

Use Get Transaction to display Bank information

Calling the Get Transaction API allows you to get transaction details and the current status of a transaction. You call the Get Transaction API by executing a GET request to the Get Transaction endpoint (/transactions/{transactionId}), where {transactionId} is the Bank Account Authorization transaction id.

Example Get Transaction request

https://sandbox.trustly.one/api/v1/transactions/1002548448

The Get Transaction call returns a JSON response with Bank Account data that you can use in your application. Relevant fields from the response include:

• payment.account.name: Name (friendly identifier) of the Users Bank Account.
• payment.account.type: Type of Account selected (Checking or Savings).
• payment.account.accountNumber: Last 4 digits of the Bank Account number selected.
• payment.paymentProvider.paymentProviderId: Trustly Identifier for the Bank selected. Use this identifier to display the Bank logo to the User.
• payment.paymentProvider.name: Name of the Bank the User selected.
• statusMessage: Status of the transaction. Should be Authorized.

You can then use this information to display the selected Payment Method to your user.

Example Get Transaction response (abbreviated)

{
  "transaction": {
    "transactionId": "1002580075",
    "payment": {
      "account": {
        "name": "Adv Plus Banking",
        "type": 1,
        "accountNumber": "3254",
      },
      "paymentProvider": {
        "paymentProviderId": "051000017",
        "name": "Bank of America"
      },
    },
    "statusMessage": "Authorized",
  }
}

Please refer to the Get Transaction definition in the API Reference for more information.

Use Get User Information to retrieve, validate, and display User information

🚧

Warning

This API is not available to Electronic Gaming clients.

Calling the Get User API allows you to get the personal information (Account Owner name, address, phone, and email) of the User from their selected Bank Account. Call the Get User API by executing a GET request to the Get Transaction endpoint (/transactions/{transactionId}/payment/paymentProvider/user), where {transactionId} is the Bank Account Authorization Transaction Id.

Example Get User request

https://sandbox.trustly.one/api/v1/transactions/1002548448/payment/paymentProvider/user

The Get User call returns a JSON response with User data that you can use in your application. Relevant fields from the response include:

• name: Name(s) associated with the User's Bank Account.
• address: Address(es) associated with the User's Bank Account.
• phone: Phone Number(s) associated with the User's Bank Account.
• email: Email Address(es) associated with the User's Bank Account.

You can then use this information to pre-fill or display the Users information in your flow. You can also use this information to validate the personal information the User may have previously provided in your flow.

Example Get User response (abbreviated)

{
  "user": {
    "name": [
      "John Smith",
      "Mary Smith"
    ],
    "address": [
      {
      "address1": "2000 Broadway Street",
      "address2": "",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
      },
      {
      "address1": "105 Alternate1 Street",
      "address2": "#401",
      "city": "Redmond",
      "state": "WA",
      "zip": "98052",
      "country": "US"
      },
    ],
    "phone": [
      "2145553434"
    ],
    "email": [
      "[email protected]"
    ],
  }
}

Please refer to the Get User definition in the API Reference for more information.

Create a Transaction from the Bank Authorization

Once you have a valid Bank Authorization, use the Trustly Transaction APIs to initiate Payments and Withdrawals.

Use the Capture Preauth API to validate Payments

The capture preauth API enables the merchant to pre-check payment approval. The ‘PreAuth’ is valid for a pre-authorized window interval in hours (default of 6 hours and up to 72 hours). Captures after the pre-authorized window interval are treated as normal Captures (will need to pass the full balance and risk analysis to be guaranteed).

Example Capture Preauth request

https://sandbox.trustly.one/api/v1/transactions/1001001894/capture/preauth/

passing the form parameters

{
  amount: 10.00,
  period: 4,
  merchantReference:  "BE3C26BC3F713AF8"
}

The response might be:

{
    "transaction": {
    "transactionId": "1001001894",
    "transactionType": 2,
    "currency": "USD",
    "amount": "10.0",
    "status": 2,
    "statusMessage": "Authorized",
    "ip": "192.168.100.147",
    "createdAt": 1449176555750,
    "updatedAt": 1449176576137,
    "merchantReference": "BE3C26BC3F713AF8",
    "recordVersion": 3,
    "payment": {
    "paymentId": "1001001891",
    "paymentType": 1,
    "merchant": {
    "merchantId": "110005502"
    },
    "merchantReference": "BE3C26BC3F713AF8",
    "fingerprint": "eaGRmtHdk23hA7U2zB5TmDAJjDE=",
    "verification": {
        "status": 3,
        "mode": 3,
        "verifyCustomer": false
        },
        "account": {
        "name": "Demo Checking Account",
        "type": -1,
        "profile": -1,
        "accountNumber": "6576",
        "token": "KSDF23KL6576",
        "verified": true,
        "verification": {
        "type": 2
        },
        "source": 1
        },
        "description": "Merchant.com purchase #BE3C26BC3F713AF8",
        "returnUrl": "https://merchant.com/instant/receipt",
        "cancelUrl": "https://merchant.com/instant/cancel",
        "currency": "USD",
        "amount": "2.10",
        "paymentProvider": {
        "paymentProviderId": "200005501",
        "type": 1,
        "name": "Demo Bank"
        },
        "auth": {
        "token": "1001000020",
        "status": 2,
        "message": "Authorized"
        },
        "createdAt": 1449176555744,
        "updatedAt": 1449176576159,
        "recordVersion": 5,
        "paymentFlow": 59
        }
    }
}

Use the Capture API to initiate Payments

The Capture API allows the merchant to request the transfer of a specific amount from the Users Bank Account given a Bank Account Authorization. You call the Capture API by executing a POST request to the Capture endpoint (/transactions/{transactionId}/capture), where {transactionId} is the Bank Account Authorization transaction id. This API returns one of the following 3 responses:

• PENDING: The transaction was accepted and is in progress. You will be notified via Event Notification of the final disposition of the transaction. For Guaranteed Payments, that will happen within 3-10 seconds. For non-Guaranteed Payments, that will happen within 3 banking days.
• DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
• ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

If the transaction was accepted for processing, the Capture API returns a PENDING transaction. You should create a PENDING transaction in your system and message the User appropriately.

📘

Info

A PENDING transaction will trigger an Authorized event notification. Additional event notifications will be triggered as the transaction is processed. For a complete list of transaction statuses and their transitions, refer to the State Transition Diagram below.

In order to execute the Capture API request, ensure you pass in the following fields:

• amount: Amount to be captured.
• merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

📘

Info

To avoid duplicate transactions, Trustly supports idempotency. If you are unable to support this requirement, please contact support. To learn more, see Idempotency.

Example Capture request

amount=10.00&merchantReference=9ce392f7-f99b-41e9-9028-3f33c8b0a46e

📘

Tip

If you wish to have the User wait while the transaction with Trustly processes, you should create the pending transaction in your system, display an appropriate processing message to the user, and periodically check the status of the Users transaction in your system. Once the Event Notification is received and you update the status of the Users transaction, you can display the appropriate message. Set a timeout of 10 seconds in your application. If you don't receive an Event Notification in your system in 10 seconds, execute a Cancel API and attempt the request again.

Example Capture response (abbreviated)

{
  "transaction": {
    "transactionId": "1002636615",
    "transactionType": 3,
    "originalTransactionId": "1002636593",
    "payment": {
      "paymentId": "1002636591",
      "paymentType": 2,
      "merchantReference": "123123",
      "account": {
        "name": "Demo Checking Account",
        "type": 1,
        "profile": 1,
        "accountNumber": "6576",
      },
      "description": "Order",
      "paymentProvider": {
        "paymentProviderId": "200005501",
        "type": 1,
        "name": "Demo Bank"
      },
      "auth": {
        "token": "15LDRA3ENERD",
        "status": 2,
        "message": "Authorized"
      },
      "authorization": "15LDRA3ENERD",
      "authorizationStatus": 2,
      "authorizationStatusMessage": "Authorized",
    },
    "currency": "USD|CAD",
    "amount": "10.00",
    "pending": "10.00",
    "paymentProviderTransaction": {
      "paymentProviderTransactionId": "ptx-ynFSa0oAiaIruwksqTtasJOX-sbx",
      "status": 10,
      "statusMessage": "Established",
      "paymentProcessor": {
        "paymentProcessorId": "100000001"
      }
    },
    "status": 1,
    "statusMessage": "Pending",
    "merchantReference": "4160903e-4ef6-49c3-a186-69b51787e638",
    "statusCode": "SW010",
  }
}

Please refer to the Capture Transaction definition in the API Reference for more information.

Use the Deposit API to initiate Withdrawals

The Deposit API allows the merchant to request the transfer of a specific amount to the Users Bank Account given a Bank Account Authorization. You call the Deposit API by executing a POST request to the Capture endpoint (/transactions/{transactionId}/deposit), where {transactionId} is the Bank Account Authorization transaction id. This API returns one of the following 3 responses:

• AUTHORIZED: The transaction was accepted and is in progress. You will be notified via Event Notifications of the final disposition of the transaction, usually within 3 banking days.
• DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
• ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

If the transaction was accepted for processing, the Deposit API returns an AUTHORIZED transaction. You should create a PENDING transaction in your system and message the User appropriately.

📘

Info

A PENDING transaction will trigger an Authorized event notification. Additional event notifications will be triggered as the transaction is processed. For a complete list of transaction statuses and their transitions, refer to the State Transition Diagram below.

In order to execute the Deposit API request, ensure you pass in the following fields:

• amount: Amount to be captured.
• merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

Example Deposit request

amount=25.00&merchantReference=5b83cfe7-b43c-4a6a-aec3-e483876a908a

Example Deposit response (abbreviated)

{
    "transaction": {
        "transactionId": "1002636638",
        "transactionType": 6,
        "originalTransactionId": "1002636593",
        "payment": {
            "paymentId": "1002636591",
            "paymentType": 2,
            "merchantReference": "123123",
            "account": {
                "name": "Demo Checking Account",
                "type": 1,
                "profile": 1,
                "accountNumber": "6576",
            },
            "description": "Order",
            "paymentProvider": {
                "paymentProviderId": "200005501",
                "type": 1,
                "name": "Demo Bank"
            },
            "auth": {
                "token": "15LDRA3ENERD",
                "status": 2,
                "message": "Authorized"
            },
            "authorization": "15LDRA3ENERD",
            "authorizationStatus": 2,
            "authorizationStatusMessage": "Authorized",
        },
        "currency": "USD|CAD",
       "amount": "25.00",
        "pending": "25.00",
        "paymentProviderTransaction": {
            "paymentProviderTransactionId": "ptx-6ygGA5gI7smyLVx52DY9D5oH-sbx",
            "status": 100,
            "statusMessage": "Pending",
            "paymentProcessor": {
                "paymentProcessorId": "100000001"
            }
        },
        "status": 2,
        "statusMessage": "Authorized",
        "merchantReference": "2534256c-634f-4ac6-a0dd-75d502cb1c3c",
        "statusCode": "AC100",
    }
}

Please refer to the Deposit API definition in the API Reference for more information.

Other Transaction APIs

Trustly offers a number of other APIs that can be used to process Payment Transactions as needed.

• Refund Transaction: Use to refund a previously completed Capture transaction.
• Reclaim Transaction: Use to refund a previously completed Deposit transaction.
• Cancel Transaction: Use to cancel a previously authorized Bank Authorization or unsettled Capture transaction.

Common Failure Scenarios

Common failure scenarios are outlined in the table below.

Handle Event Notifications

For more information on Event Notifications, refer to Event Notifications.

Capture and Deposit Transactions

The following diagram shows the Transaction State of a Capture or Deposit transaction. Transaction status updates are sent via Event Notification and can also be retrieved via the Trustly Transactions Report.

1. The Capture and Deposit API creates a transaction with the initial status of Authorized.
2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

Refund and Reclaim Transactions

The following diagram shows the Transaction State of a Refund or Reclaim transaction. Transaction status updates are sent via Event Notification and can also be retrieved via the Trustly Transactions Report.

1. The Refund and Reclaim API creates a transaction with the initial status of Authorized.
2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

Testing

Trustly offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. You access the Demo Bank, search for "Demo Bank" in the 'Select your bank' screen of the Trustly Lightbox. To simulate errors when using the Demo Bank, use the phrases below in the password field to generate errors.

To simulate a delay, just enter Sleep as username and the number of seconds as the password, The connector will wait for at least the given number of seconds before presenting any results.

Handling an Adverse Action decline

If you receive a Capture API or Deposit API response or receive an Event Notification with a Payment Provider Transaction Status of SW055 - Fraud analysis (Negative Data) and the response also contains a thirdPartyDeclineCode value, it means the user has an item on file with TeleCheck that needs to be resolved, and the user must contact TeleCheck directly. In this instance, you must provide this message to your user, replacing {{ thirdPartyDeclineCode }} with the thirdPartyDeclineCode value that was provided in the response or notification.

📘

Note

This use case can be tested using Demo Bank and the tckerror password in our Sandbox environment. Select the SW055 account and execute your Capture call as normal to trigger the Adverse Action SW055 decline via webhook.

🚧

Warning

Due to FCRA requirements, you MUST use this exact language:

The decision not to accept your payment was based, in whole or in part, on information provided by TeleCheck Services, Inc. To learn more, please visit https://getassistance.telecheck.com/index.html.
TeleCheck is located at 5565 Glenridge Connector, NE, Atlanta, GA 30342.
The mailing address is P.O. Box 6806 Hagerstown, MD 21741-6806.
The toll-free number is 1-800-366-2425. Please reference {{ thirdPartyDeclineCode }} when you call.

Under the Fair Credit Reporting Act: Consumers have the right to a free copy of their information held in TeleCheck’s files for a period of 60 days following an adverse action. Consumers also may dispute the accuracy or completeness of any information in TeleCheck’s consumer report.

Refresh a Bank Authorization using Online Banking

Handling invalidated Transaction IDs

If you receive a Capture API response or receive an Event Notification with an error code of 330 and a Payment Provider Transaction Status of SW056, simply follow these steps:

• Remove the Account from the User's profile.
• Message the User with an appropriate message, such as Sorry, we are unable to process your request at this time. Please choose a different payment method.. Allow the User to select another method of payment.
• Create a new Bank Authorization using Online Banking. Save the new Authorization on the User's Profile.

📘

Note

This use case can be tested using Demo Bank and the tckerror password in our Sandbox environment. Select the SW056 account and execute your Capture call as normal to trigger the SW056 decline via webhook.

Handling expired Split Tokens

If you receive a Capture API response or receive an Event Notification with an error code of 326 and a Payment Provider Transaction Status of SW057, or an error code of 380 and a Payment Provider Transaction Status of SW051, or an error code of 397 within an HTTP400 response, simply follow these steps:

• Prompt the User to refresh their Bank Authorization using Online Banking.
• Once you receive the refreshed Split Token via Event Notification, update the User's Profile, storing the updated Split Token.
• Attempt to process the Capture API call again.

📘

Note

This use case can be tested using Demo Bank and the ExpiredSplitToken password in our Sandbox environment. Once you successfully create your bank authorization, use the Capture API to trigger the SW057 response.

Refresh an expired Bank Authorization using Online Banking

In the event a User's Split Token expires or becomes invalidated, you can use the Refresh flow to request a new one.

1. You call the Trustly SDK's establish function, passing in parameters to launch the Refresh flow.
2. From the Trustly Lightbox, the user authenticates with their bank and is immediately returned to your returnUrl.
3. Before returning the User to your returnUrl, we will send an Event Notification to your listener with the transactionId and splitToken. You'll update the User's account on file at this point and attempt to process the Capture transaction again.

To integrate the Trustly Refresh flow into your website or app, you will need to do the following:

Integrate the Trustly SDK into your flow.

Trustly offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish. The methods accept 2 parameters, options and establishData. The options parameter is optional and can be used to control pieces of the Lightbox experience. The establishData parameter is used to pass transaction parameters to Trustly that are used when establishing the Bank Authorization transaction.

The following examples are using the JavaScript SDK

1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId} with the Access Id provided to you by Trustly):

<script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId={accessId}"> </script>

2. To provide optional Trustly configuration options, create a TrustlyOptions object:

var TrustlyOptions = {
  closeButton: false,
  dragAndDrop: false,
};

For details on the Trustly configuration options, refer to the SDK Specification.

3. To provide the transaction details to the SDK, create an establishData object:

var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: "transaction description",
  currency: "USD|CAD",
  amount: "0.00",
  merchantReference: "merchant reference",
  paymentType: "Verification",
  authToken: "new",
  transactionId: {transactionId},
  returnUrl: "https://merchant.com/trustly/return",
  cancelUrl: "https://merchant.com/trustly/cancel"		
};

📘

Info

Ensure you are passing in the transactionId that you have stored on file. This transactionId will not change.

🚧

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

📘

Tip

Ensure you're securing your call by including the requestSignature parameter.

4. Finally, call the Trustly SDK's establish function:

Trustly.establish(establishData, TrustlyOptions);

The following is a full HTML page using the above example.

📘

Info

You'll want to replace {accessId} and {merchantId} with the values provided to you by Trustly. You'll want to replace {transactionId} with your stored transaction id.

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var TrustlyOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget',
      };
    </script>
    <script src="https://{environmentURL}.one/start/scripts/trustly.js?accessId={accessId}"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
  </body>
   <script>
    var establishData = {
      accessId: {accessId},
    	merchantId: {merchantId},
    	description: 'transaction description',
      currency: "USD|CAD",
      amount: "0.00",
    	merchantReference: "merchant reference",
      paymentType: "Verification",
      authToken: "new",
      transactionId: {transactionId},
    	returnUrl: "https://merchant.com/trustly/return",
    	cancelUrl: "https://merchant.com/trustly/cancel"		
    };
    Trustly.establish(establishData, TrustlyOptions);
  </script>
</html>

Receive the refreshed Split Token

Before the User is returned via the returnUrl, Trustly will send you an Event Notification that contains the parentObjectId (transactionId), splitToken, and other related fields. Once you receive the Notification, save the payment method to the User's account and return a 200 OK response to the Notification server.

📘

Info

Trustly will not redirect the User to your returnUrl until we either receive a response (success or failure) or until the request times out after 3 seconds.

🚧

Warning

If you fail to receive or store the splitToken, it can not be resent. You can (and should) attempt a Capture API call without it.

Example Verification notification

merchantId=1002463580&merchantReference=123123&paymentType=5&transactionType=1&parentObjectId=1002596444&parentMerchantReference=123123&eventId=1002642360&eventType=Authorize&objectId=1002642325&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1557803299069&accessId=ASs345fldAHJPTHXcaK&accountVerified=true&fiCode=200005501&paymentProviderType=PWMB&status=2&statusMessage=Authorized&splitToken=CLvfv6KrLRABGGAgACowusCukkxmQ%2B%2BQseknVvMke5bDORHYSXZbLnPtCEPvL24Uae2XF7%2BcaSgIW%2BVC19J%2B

Please refer to Event Notifications for more information on handling Event Notifications.

Handle the redirect

If the User cancels the request, Trustly will direct the User to your provided cancelUrl. If the User successfully authorizes the request, Trustly will direct the User to your provided returnUrl.

Once you get a successful redirect to your returnUrl, check to ensure you've received the Split Token and added the account on file. If you have not, add the account on file with the provided transactionId and a blank or null splitToken.

Example Cancel URL

https://merchant.com/trustly/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D

Example Return URL

https://merchant.com/trustly/return?merchantReference=123123&payment.account.verified=true&payment.paymentProvider.type=1&payment.paymentType=5&requestSignature=2yBF8Hlrte2yXttLEI934MfOiG4%3D&status=2&transactionId=1002642325&transactionType=1

Redirect URL Parameters

Trustly will append the following parameters to your returnUrl or cancelUrl:

Error Handling

Trustly uses conventional HTTP response codes to indicate the success or failure of an API request.

Not all errors map cleanly onto HTTP response codes, however. In addition to the HTTP response code, Trustly returns an array of error objects that describes the errors as a JSON string such as the example below.

{
  "errors": [
    {
      "domain" : "com.paywithmybank.merchantgateway.v1.exception.InvalidParameterException",
      "code" : 200,
      "message" : "Could not find a transaction using Id 10000021"
    }
  ]
}