Server-Side Establish
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:
- 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.
- 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. - 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
: Iftrue
, Trustly will notify the user. Otherwise, you can use the URL in the response in your own notification.channel
: Ifnotify
istrue
, specifies the channel(s) to use to notify the user that a request needs to be completed. Values can either meemail
orsms
(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 onechannel
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¬ify=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. 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.
Password | Use Case |
---|---|
NoEligibleAccounts | No eligible accounts found |
LoginError | Wrong username or password |
Unavailable | Bank Site cannot be reached. |
AccountLocked | Userβs account is locked. |
BankAction | The bank requires the user to login and perform some action on their site. |
ConnectError | There was a connection problem when accessing bank site |
ConnectionError | There was a connection problem when accessing bank site |
BlockedIpError | The bank indicates the caller IP was blocked |
ChallengeError | Simulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry |
ValidRouteCodeExtra | Connector 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 |
InvalidRouteCodeExtra | Connector 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 |
TimeoutError | In order to simulate a timeout, connector sleeps for at least a minute before actually doing anything. |
TestPrompts | This is not an error. This is to test the prompts on next page, including (Checkbox, radio, text, password, date, description and so on) |
NotEnoughFunds | Connector returns a single account with zero balance. This is similar to having no eligible accounts, but with different reason. |
NotEnoughFundsExtra | Connector returns two accounts. One with zero balance, the other with a valid balance. |
InvalidAccountNumberSize | Connector returns a single account, but with account number shorter than the required. This is to test how the screen filters invalid accounts |
InvalidAccountNumberSizeExtra | Connector returns two accounts. One with account number shorter (3 characters) than the required, the other with valid account number. |
PartialAccountNumbers | Connector 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. |
OnlyPartials | PartialAccountNumbers + NoRouteCode |
NoCustomer | Simulates as if FIC was not able to retrieve customer information |
NoRouteCode | Regular 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) |
InvalidRouteCode | Regular flow but simulates an invalid routing code (will simulate if ProfitStars returns invalid routing code) |
2FA | Simulates 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. |
WrongCredentials | Simulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry |
SiteRequestError | Simulates as if the bank couldn't process a particular request, allowing user to retry it |
SessionTimeout | Simulates as if the user took too long to provide the requested information, since the bank session is already expired |
PreLoginError | Simulates an error before the user gets authenticated |
NotSupported | Simulates an user with no supported accounts |
AccountsWithNameAndAddress | Simulates an User with 2 accounts and each one with different names and addresses. |
ManyInformation | Simulates an User with until 10 accounts. |
AccountNotSupported | Simulates an User with an account not supported by our service (Chase Liquid, etc) |
AmountNull | Simulates the Demo Checking Account returning an amount with null value. |
AccNumberNull | Simulates the Demo Checking Account returning null value in the account number and routing number |
AccFromUsername | Returns 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. |
RandomBalance | Returns account with a random balance |
RandomAccounts | Returns an account with the random account number |
LargeCustomerInfo | Returns account with very large customer information |
FICWarning | It simply add to log engine fic-warning one example message to simulate the FIC Warning flow |
EmailMFA | Simulates as the bank requested the user to select an email address to send him an MFA token. |
MixedMFA | Simulates as the bank requested the user to select an email address or a phone number to send him an MFA token. |
CreditCardsOnly | Returns an account only with a credit card |
TCKAccounts | Returns an account that is valid on TeleCheck test environment |
AccountProfile | Returns 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. |
RandomAccWithSleep | Returns random accounts with random account numbers and sleeps (in seconds) during the number passed in the password field |
ExpiredSplitToken | Allows the transaction to be authorized but every refresh API call fails because of an expired split token. |
NotEnoughFundsOnRefresh | Allows the transaction to be authorized but every refresh API call returns 0.00 as the 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 Status | Code | Suggested Action |
---|---|---|
400 Bad Request | 200 | Check the request parameters and retry the request. |
401 Unauthorized | 300 | Check your API Credentials and Merchant Id and try the request again. |
401 Unauthorized | 375 | Check your API Credentials and Merchant Id and try the request again. |
500 Server Error | 100 | Retry the request and notify Trustly if the issue persists. |
Further Reading
Updated 29 days ago