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. 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.
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 about 1 year ago