Trustly can initiate the Online Banking flow via server-side calls for Data use cases only. This is typically used when you need to get a bank authorization in an offline flow. Trustly will initiate the process via SMS or email, or you can initiate the process yourself using the URL returned by Trustly. Once authorized, you can use additional Trustly APIs to act against the authorization. This is a three step process:

1. Create a Bank Authorization with the Establish API. Collect the customers Account and Routing Number in your flow. Pass this information to Trustly via the Establish a Transaction.
2. Handle Event Notifications. Once the authorization is completed, Trustly will send an Event Notification with a transactionId that can be used with the Trustly API.
3. Perform actions with the Trustly APIs. Depending on your use case, you can use the Trustly APIs to act upon the Bank Authorization.

Creating Bank Authorizations with the Establish API

Use the Trustly Establish API to create an Authorization Transaction that can be used with Deposit API.

To initiate the request, append the following parameters to the Establish API url:

• notify: If true, Trustly will notify the user. Otherwise, you can use the URL in the response in your own notification.
• channel: If notify is true, specifies the channel(s) to use to notify the user that a request needs to be completed. Values can either me email or sms (passed as a comma-separated list).

Additionally, pass in the following inputs:

• merchantId: A unique Trustly merchant identifier.
• merchantReference: A unique Merchant Reference identifier that represents your ID for the Authorization request.
• customer: Information about the Customer that will be completing the request. name is required. email is required if the customer is to be notified via email. phone is required if the customer is to be notified via SMS.

📘

Info

Ensure you pass a query string of notify=true and at least one channel parameter on the API Endpoint URL.

The response will be an Establish Data object. An example is shown below.

Example Request

POST /establish?channel=sms,email&notify=true

{
  "merchantId": "1002463580",
  "merchantReference": "e11166d2-f0ea-4215-a7b5-5f57a251481a",
  "customer": {
    "name": "Joe User",
    "phone": "+15551231234",
    "email": "[email protected]"
  }
 }

Example Response

{
    "establishData": {
        "merchantId": "1002463580",
        "paymentType": 6,
        "returnUrl": "https://sandbox.trustly.com/start/establish/rtn",
        "cancelUrl": "https://sandbox.trustly.com/start/establish",
        "data": "eNqTUjE3MEs1SE0y0DU1TE7TNUk1NdVNTE0x0E00NjY0SLJMTLUwMsrOKVbi981MzkhMzVFwyknMK8nPs+biNzMyVwgpSizLLM5XcM4skuL0ySxLLcrNL0pVYnJ21GK1NDE1NTBiCg22ceLRNrQ0MjWxMDcwMD",
        "accessId": "M8RaHgEjBE54zuFYMRQg",
        "requestSignature": "ZPomXHE9UW330XGSdqweY04U0E="
    },
    "url": "https://sandbox.trustly.com/start/establish?a=M8RaHgEjBE54zuFYMRQq&m=1002463580&p=6&g=43&d=eNqTUjE3MEs1SE0y0DU1TE7TNUk1NdVNTE0x0E00NjY0SLJMTLUwMsrOKVbi981MzkhMzVFwyknMK8nPs%2BbiNzMyVwgpSizLLM5XcM4skuL0ySxLLcrNL0pVYnJjiUJBYWZ5ZkpFbmZSYl62XnJ9bAgDCESsQ&u=0&r=ZPomXHE9UW330XGPLX01VY04U0E%3D"
}

Handling Event Notifications

Authorized Transaction

Once the user has authenticated with their bank and selected the account to use, Trustly will send you an event notification that includes an objectId (transactionId) that can be used with the Trustly APIs.

Example Event Notification

merchantId=1002463580&merchantReference=cc4275f6-9423-4f0d-8cbf-f78535742ea7&paymentType=6&transactionType=1&eventId=1002777467&eventType=Authorize&objectId=1002777451&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1560635095925&accountVerified=true&fiCode=200005501&paymentProviderType=PWMB&status=2&statusMessage=Authorized

Testing

Trustly offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. Read more in Testing.

Error Handling

The following table lists expected errors and suggested actions that are associated with this product. For more information on Error Handling, consult the API Reference.

Further Reading

• Event Notifications