Server-Side Establish

Trustly can initiate the Online Banking flow via server-side calls. 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 API's 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 API's. Depending on your use case, you can use the Trustly API's 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 API's.

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. 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, you can use the phrases below in the password field to generate errors.

PasswordUse Case
NoEligibleAccountsNo eligible accounts found
LoginErrorWrong username or password
NotRecognizedMain Error that users see when using an ACA
NoSuchFieldThis error ultimately ends up as a PageNotRec error. It happens when an item cannot be found on the page. ACA will try to execute another page. If there is no another page, “page not recognized” error will be returned. Customers shouldn’t see this error.
PostErrorHTTP connection error using GET. Customer shouldn’t see this error. In real ACA, this will result in a Site not available” error.
GetErrorHTTP connection error using POST. Customer shouldn’t see this error. In real ACA, this will result in a Site not available” error.
PromptTypeErrorWhen an ACA fails to create a prompt, this error is returned. If this error appears, it means the ACA has a bug.
JsErrorWhen ACA tries to run javascript code and there are any errors during running, this error will be thrown.
UnavailableBank Site cannot be reached.
AccountLockedUser’s account is locked.
UnclassifiedThere are some run time exceptions that not captured by ACA, like NPE(null pointer exception), array out of bounds exception and so on.
BankActionThe bank requires the user to login and perform some action on their site.
ConnectErrorThere was a connection problem when accessing bank site
ConnectionErrorThere was a connection problem when accessing bank site
BlockedIpErrorThe bank indicates the caller IP was blocked
ChallengeErrorSimulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry
ValidRouteCodeExtraConnector returns 2 accounts whose route codes are larger than 9 digits: one of them has a valid route code as substring, so both accounts use the same valid code
InvalidRouteCodeExtraConnector returns a single account whose route code is larger than 9 digits, but no valid route code is found as substring. Hence, the account is ignored
TimeoutErrorIn order to simulate a timeout, connector sleeps for at least a minute before actually doing anything.
TestPromptsThis is not an error. This is to test the prompts on next page, including (Checkbox, radio, text, password, date, description and so on)
NotEnoughFundsConnector returns a single account with zero balance. This is similar to having no eligible accounts, but with different reason.
NotEnoughFundsExtraConnector returns two accounts. One with zero balance, the other with a valid balance.
InvalidAccountNumberSizeConnector returns a single account, but with account number shorter than the required. This is to test how the screen filters invalid accounts
InvalidAccountNumberSizeExtraConnector returns two accounts. One with account number shorter (3 characters) than the required, the other with valid account number.
PartialAccountNumbersConnector returns two accounts, however only with partial numbers. Simulating when for example the account is new and we still don't have statements to get full account number.
OnlyPartialsPartialAccountNumbers + NoRouteCode
NoCustomerSimulates as if FIC was not able to retrieve customer information
NoRouteCodeRegular flow with 2 accounts, but none with route code. This prompts a question for account location, where user must select where the account was open (from the given options)
InvalidRouteCodeRegular flow but simulates an invalid routing code (will simulate if ProfitStars returns invalid routing code)
2FASimulates as the bank requested a challenge question to the user. The question should be answered with the word 'error' if it's necessary to simulate a wrong credential. Otherwise, it should be anything to have a successful access.
WrongCredentialsSimulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry
SiteRequestErrorSimulates as if the bank couldn't process a particular request, allowing user to retry it
SessionTimeoutSimulates as if the user took too long to provide the requested information, since the bank session is already expired
PreLoginErrorSimulates an error before the user gets authenticated
NotSupportedSimulates an user with no supported accounts
AccountsWithNameAndAddressSimulates an User with 2 accounts and each one with different names and addresses.
ManyInformationSimulates an User with until 10 accounts.
AccountNotSupportedSimulates an User with an account not supported by our service (Chase Liquid, etc)
AmountNullSimulates the Demo Checking Account returning an amount with null value.
AccNumberNullSimulates the Demo Checking Account returning null value in the account number and routing number
AccFromUsernameReturns the account number from the pattern {prefix}_{accountnumber} on the username. Ex: To return an account with number 1234445 you can enter the username user1_1234445 or anotheruser_1234445.
RandomBalanceReturns account with random balance
RandomAccountsReturns an account with random account number
LargeCustomerInfoReturns account with very large customer information
FICWarningIt simply add to log engine fic-warning one example message to simulate the FIC Warning flow
EmailMFASimulates as the bank requested the user to select an email address to send him a MFA token.
MixedMFASimulates as the bank requested the user to select an email address or a phone number to send him a MFA token.
CreditCardsOnlyReturns an account only with credit card
TCKAccountsReturns an account that is valid on TeleCheck test environment
AccountProfileReturns accounts with Business, Personal, Other, Unknown and Null profiles.
Balance{xxx}Configures the account to have a balance of {xxx}. For example, Balance1000 will set the account balance to $1000. This is useful when testing transactions of larger dollar amounts.
RandomAccWithSleepReturns random accounts with random account numbers and sleeps (in seconds) during the number passed in the password field
ExpiredSplitTokenAllows the transaction to be authorized but every refresh API call fails because of an expired split token.
NotEnoughFundsOnRefreshAllows the transaction to be authorized but every refresh API call returns 0.00 as balance for all accounts.

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.

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.

HTTP StatusCodeSuggested Action
400 Bad Request200Check the request parameters and retry the request.
401 Unauthorized300Check your API Credentials and Merchant Id and try the request again.
401 Unauthorized375Check your API Credentials and Merchant Id and try the request again.
500 Server Error100Retry the request and notify Trustly if the issue persists.

Further Reading


Did this page help you?