Create a Bank Authorization

Creating a bank authorization is the foundational step in the Trustly Pay integration workflow because it establishes the secure connection between your application and the user's bank account without your organization ever handling their sensitive credentials. Calling the establish method generates the mandatory transactionId, which acts as the unique key you’ll use to execute all subsequent API requests, such as capturing funds or retrieving user data.

Trustly provides SDKs for JavaScript, iOS, and Android to streamline your integration. Regardless of the platform, you will primarily interact with two core methods: selectBankWidget and establish.

Both methods accept the following parameter objects:

establishData: This object is required. It passes the transaction parameters needed to establish the Bank Authorization.
options: This object is optional. It allows you to control specific aspects of the Lightbox experience.

The JavaScript SDK is used in the examples provided here.

Prerequisites

Sandbox Credentials: You need your accessId and accessKey. Contact Trustly Support if you do not have them.
Legal Agreement: Ensure your non-disclosure agreement (NDA) and commercial agreements are signed.

Integrate the SDK

Add the following <script> tag to your application page's <head> or immediately before the closing </body> tag.
```
<script src="https://sandbox.trustly.one/start/scripts/paywithmybank.js?accessId={accessId}"> </script>
```
To provide optional Trustly configuration options, create a TrustlyOptions object. For example:
```
var TrustlyOptions = {
  closeButton: false,
  dragAndDrop: false,
  widgetContainerId: "widget-container-id" //Page element container for the widget
};
```
For configuration information, see the specific SDK Specification.

Create an establishData object to provide the transaction details to the SDK. For example:

{
  "merchantId": "YOUR_MERCHANT_ID",
  "accessId":"YOUR_ACCESS_ID",
  "requestSignature": {requestSignature},
  "merchantReference": {unique_merchant_payment_identifier},
  "description": "any additional user-friendly descriptive information for the payment",
  "paymentType": "Deferred",
  "currency": "USD",
  "amount": "0.00",
  "customer": {
    "name": "Joe User",
    "email": "[email protected]",
    "address": {
      "address1": "2000 Broadway St",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
    }
  },
  returnUrl: "https://yourapp.com/path/return",
  cancelUrl: "https://yourapp.com/path/cancel"
}

See Securing Requests to learn how to calculate the requestSignature

Electronic Gaming clients are required to pass verifyCustomer as true and pass the customer object for verification. Do not pass customer PII (name, email address, etc.) in the description field; instead pass any customer PII in the customer object.

Set amount to 0.00 for an open-ended authorization or enter a value to define a limit on the amount authorized. Use displayAmount to show the final transaction total to the user.

Call the SDK establish or selectBankWidget function. For example:

Select Bank Widget
```
Trustly.selectBankWidget(establishData, TrustlyOptions);
```
Establish
```
Trustly.establish(establishData, TrustlyOptions);
```

Complete HTML example

The following is the complete HTML for previous procedure.

Replace the accessId, merchantId, and merchantReference 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>
   <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>
  </body>
</html>

Redirects

Redirect URLs are the endpoints where users are returned after completing or canceling a workflow within the Trustly UI. They are essential for continuity because they capture critical transaction data through query parameters, allowing your application to immediately verify the status and trigger the next step in your integration.

When a user successfully authorizes a request, Trustly directs them to the returnUrl you provided. If a user cancels a request, Trustly directs them to the cancelUrl you provided. For more information about redirect URLs, see Redirect URLs.