Create a Bank Authorization
The Trustly Online Banking Payment service enables end-users to pay or be paid by signing in to their online banking interface within your website or app. The Trustly User interaction can be completed in 3 simple steps:
- The User selects Online Banking as a payment method on your website or app, which you link to the SDK selectBankWidget call to open the Trustly Widget (which then launches the Trustly Lightbox) or to the SDK establish call which launches the Trustly Lightbox directly.
- From the Trustly Lightbox, the user authenticates with their bank and selects the account they wish to use for the transaction.
- Once authorized, the User is then returned to the
returnUrl
passed to the appropriate SDK call, adding thetransactionId
, at which point you can continue to process the transaction.
Integrate the Trustly SDK into your flow.
As mentioned above, Trustly offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget
and establish
. Each method accept 2 parameter objects, options
and establishData
. The options
parameter is optional and can be used to control pieces of the Lightbox experience. The establishData
parameter is used to pass transaction parameters to Trustly that are used when establishing the Bank Authorization transaction.
The following examples are using the JavaScript SDK
1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId}
with the Access Id provided to you by Trustly):
<script src="https://sandbox.trustly.one/start/scripts/paywithmybank.js?accessId={accessId}"> </script>
2. To provide optional Trustly configuration options, create a TrustlyOptions
object:
var TrustlyOptions = {
closeButton: false,
dragAndDrop: false,
widgetContainerId: "widget-container-id" //Page element container for the widget
};
For details on the Trustly configuration options, refer to the SDK Specification.
3. To provide the transaction details to the SDK, create an establishData
object:
{
"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"
}
Note: see the Securing Requests reference for details on how to calculate the requestSignature
Warning
Electronic Gaming clients are required to pass
verifyCustomer
astrue
and pass thecustomer
object for verification.Do not pass customer PII (name, email address, etc.) in the
description
field; instead pass any customer PII in thecustomer
object.
Tip
If you will be sending the user back to some sort of review screen before completing their transaction, pass an amount of
0.00
in theestablishData
object. You will need to ensure you show the user the final transaction amount before they complete the transaction on your side. Otherwise, pass the final transaction amount in theamount
field of theestablishData
object. This will be shown throughout the Trustly Lightbox. The user will click the Pay button in the Trustly Lightbox before being returned to your site, where you will use the Capture API to complete the transaction.
4. Finally, call the Trustly SDK's establish
or selectBankWidget
function:
Select Bank Widget
Trustly.selectBankWidget(establishData, TrustlyOptions);
Establish
Trustly.establish(establishData, TrustlyOptions);
The following is a full HTML page using the above example.
Info
Replace the
{accessId}
and{merchantId}
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>
</body>
<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>
</html>
Handle the redirect
If the User cancels the request, Trustly will direct the User to your provided cancelUrl
. If the User successfully authorizes the request, Trustly will direct the User to your provided returnUrl
.
Once you get a successful redirect to your returnUrl
, add the account on file with the provided transactionId
. If applicable, also check the corresponding incoming Authorize
webhook event associated with this transactionId
and add the splitToken
provided in that event alongside the account on file.
Example Cancel URL
https://merchant.com/trustly.com/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D
Example Return URL
https://merchant.com/trustly.com/return?transactionId=1002633191&transactionType=1&merchantReference=123123&status=2&payment.paymentType=2&payment.paymentProvider.type=1&payment.account.verified=false&panel=1&requestSignature=b7yr%2F3qOupPa1B7VeI32PhGQ7C8%3D
Redirect URL Parameters
Trustly will append the following parameters to your returnUrl
or cancelUrl
:
Parameter | Definition |
---|---|
transactionId | A unique Trustly transaction identifier. (15 characters) |
transactionType | Will always be 1 in this use case. |
merchantReference | A specific merchant reference for this cancelation. For example, this could be your order number or session id. |
status | Integer value representing the Transaction Status. This will either be 2 (Authorized) or 7 (Cancelled). Refer to Transaction Status Values in the SDK Specification for a complete list of values and their definitions. |
payment.paymentType | Will always be 2 (Deferred) in this use case. |
payment.paymentProvider.type | Will always be 1 (Online Banking) in this use case. |
payment.account.verified | ... |
panel | Integer value representing the Trustly screen the user exited the flow on. Refer to Panel Values in the SDK Specification for a complete list of values and their definitions. |
payment.paymentProviderTransaction.status | Integer value representing the Payment Provider Transaction Status of the transaction. Refer to Payment Provider Transaction Status in the SDK Specification for a complete list of values and their definitions. |
requestSignature | This is a signature that you can calculate to ensure the request you receive is coming from Trustly. See Validate the Redirect Signature for more information. |
Next Steps
Now that you have a valid Authorization Transaction and an associated splitToken
you're ready to start making API calls to retrieve bank and user data to enhance the user experience and initiate payin or payout transactions for your users.
Updated 2 months ago