Instant Payouts

Trustly can be used to allow a user to initiate a instant withdrawal from your application. There are 4 pieces required for this use case.

  1. Create a Bank Authorization using Online Banking. Implement the Trustly Online Banking interface to allow a User to authenticate with their Bank and authorize you to use that bank for payment transactions. This returns a transactionId that you will use to make API calls with Trustly to further process the transaction.
  2. Display Bank or User PII from Trustly. With a valid transactionId, you can use the Trustly Get Transaction API and Get Financial Institution User API to retrieve information from the Users selected bank to display, verify, or pre-fill fields on your site or application.
  3. Create a Transaction from the Bank Authorization. When the User requests to make a payment, you can use the Trustly Capture API or Deposit API, passing the previously obtained transactionId, amount, and merchantReference.
  4. Handle Event Notifications. The payment transaction returns a PENDING or ERROR response. Implement Trustly Event Notifications to receive transaction status updates in real time and message your customers accordingly.

Integration Options and Branding Requirements

Trustly offers two types of Integration Options for its Online Banking solution - Select Bank Widget and Trustly Lightbox.

The Select Bank Widget is show in-line on your page (outlined here in red) and shows the most popular bank accounts. Clicking one of the buttons on the Widget opens the Trustly Lightbox, where the User can sign in and authorize their account for use.

Alternately, you can trigger the Trustly Lightbox using your own button. The Trustly Lightbox opens over your existing page.

In addition to determining if the Select Bank Widget or opening the Trustly Lightbox directly is the best option for you, Trustly has a number of Branding Requirements to consider. If you have any questions or specific requirements, please work with your Trustly team or contact [email protected]

Create a Bank Authorization using Online Banking

The Trustly Online Banking Payment service enables end users to pay by signing into their online banking interface within your website. The Trustly User interaction can be completed in 3 simple steps.

  1. The User selects Online Banking as a payment method on your website, which either displays the Trustly Widget (which then launches the Trustly Lightbox) or launches the Trustly Lightbox directly.
  2. From the Trustly Lightbox, the user authenticates with their bank and selects they account they wish to use for the transaction.
  3. One authorized, the User is then returned to your returnUrl with the transactionId, at which point you can continue your flow as usual.

To integrate the Trustly Online Banking Payment service into your website or app, you will need to do the following:

Integrate the Trustly SDK into your flow.

Trustly offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish. The methods accept 2 parameters, options and establishData. The options parameter is optional and can be used to control pieces of the Lightbox experience. The establishData parameter is used 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.paywithmybank.com/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:

var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: 'transaction description',
  currency: 'USD',
  amount: '0.00',
  merchantReference: 'merchant reference',
  paymentType: 'Deferred',
  metadata: {
    flowType: '{configured flow type}' // e.g. payin
  },
  verification: {
    verifyCustomer: true,
  },
  customer: {
    externalId: '12345',
    name: 'Joe User',
  },
  returnUrl: 'https://merchant.com/trustly.com/return',
  cancelUrl: 'https://merchant.com/trustly.com/cancel'      
};

🚧

Warning

Electronic Gaming clients are required must pass verifyCustomer as true and pass the customer object for verification.

🚧

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

📘

Tip

Ensure you're securing your call by including the requestSignature parameter.

📘

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 the establishData 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 the amount field of the establishData 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

You'll want to replace {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.paywithmybank.com/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',
      merchantReference: 'merchant reference',
      paymentType: 'Deferred',
      metadata: {
            flowType: '{configured flow type}' // e.g. payin
        },
      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, check to ensure you've received the Split Token and added the account on file. If you have not, add the account on file with the provided transactionId and a blank or null splitToken.

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&instantPayoutAvail=true&requestSignature=b7yr%2F3qOupPa1B7VeI32PhGQ7C8%3D

Redirect URL Parameters

Trustly will append the following parameters to your returnUrl or cancelUrl:

ParameterDefinition
transactionIdA unique Trustly transaction identifier. (15 characters)
transactionTypeWill always be 1 in this use case.
merchantReferenceA specific merchant reference for this cancelation. For example, this could be your order number or session id.
statusInteger 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.paymentTypeWill always be 2 (Deferred) in this use case.
payment.paymentProvider.typeWill always be 1 (Online Banking) in this use case.
payment.account.verified...
panelInteger 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.statusInteger 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.
requestSignatureThis 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.

Display Bank or User PII from Trustly

With a valid Bank Authorization, you can use the Trustly Get Transaction API to retrieve information about the Users bank account that can be displayed in their account on your system. You can also use the Trustly Get User API to retrieve personal information (name, address, email, etc) that can be used to pre-fill fields on your flow or verify information you have already collected from the User.

Use Get Transaction to display Bank information

Calling the Get Transaction API allows you to get transaction details and current status of a transaction. You call the Get Transaction API by executing a GET request to the Get Transaction endpoint (/transactions/{transactionId}), where {transactionId} is the Bank Account Authorization transaction id.

Example Get Transaction request

https://sandbox.paywithmybank.com/api/v1/transactions/1002548448

The Get Transaction call returns a JSON response with Bank Account data that you can use in your application. Relevant fields from the response include:

  • payment.account.name: Name (friendly identifier) of the Users Bank Account.
  • payment.account.type: Type of Account selected (Checking or Savings).
  • payment.account.accountNumber: Last 4 digits of the Bank Account number selected.
  • payment.paymentProvider.paymentProviderId: Trustly Identifier for the Bank selected. You can use this identifier to display the Bank logo to the User.
  • payment.paymentProvider.name: Name of the Bank the User selected.
  • statusMessage: Status of the transaction. Should be Authorized.

You can then use this information to display the selected Payment Method to your user.

Example Get Transaction response (abbreviated)

{
  "transaction": {
    "transactionId": "1002580075",
    "payment": {
      "account": {
        "name": "Adv Plus Banking",
        "type": 1,
        "accountNumber": "3254",
      },
      "paymentProvider": {
        "paymentProviderId": "051000017",
        "name": "Bank with real-time payments"
        "instantPayoutAvail": true
      },
    },
    "statusMessage": "Authorized",
  }
}

Creating Disbursement Transactions with the Deposit API

With a valid transactionId from an Authorization request, you can use the Trustly Deposit Transaction to initiate a Disbursement or Payout transaction to a users bank account.

To initiate the request, pass in the following inputs:

  • transactionId: Authorization Transaction ID retrieved from a Trustly Deferred or Disbursement Authorization.
  • amount: The amount to be sent. Required if the Authorization Transaction amount was 0.00. If not passed, the full amount of the Authorization Transaction will be used.
  • merchantReference: A specific merchant reference for this deposit. For example, this could be an merchant order number or the same merchant reference value used in the original establish call.
  • instantPayoutRequest: Whether a instant withdrawal is requested for this transaction.

If successful, the response of this call will be an authorized Disbursement transaction. Updates to the status of the transaction will be sent via Event Notification.

Example Request

POST /transactions/1002613662/deposit

amount=25.00&merchantReference=f9c28cd0-bca1-47cb-a776-238b621e66cb&instantPayoutRequest=true

Example Response (Abbreviated)

{
    "transaction": {
        "transactionId": "1002613685",
        "transactionType": 6,
        "originalTransactionId": "1002613662",
        "payment": {
            "paymentId": "1002580220",
            "paymentType": 2,
        },
        "currency": "USD",
        "amount": "25.00",
        "status": 2,
        "statusMessage": "Authorized",
        "instantPayoutSettle": true
        "createdAt": 1556922524381,
        "processedAt": 1556922524393,
        "completedAt": 1556922524621,
        "updatedAt": 1556922524622,
        "ppTrxId": "ptx-CquvTsAaPDvaSB6ywZ2krXGS-sbx",
        "merchantReference": "f9c28cd0-bca1-47cb-a776-238b621e66cb",
        "statusCode": "AC100",
        "recordVersion": 1
    }
}

Handling Event Notifications

Disbursement Transactions

The following diagram shows the Transaction State of a Disbursement transaction. Transaction status updates are sent via Event Notification and can also be retrieved via the Trustly Transactions Report.

  1. The Deposit API returns a status of Authorized.
  2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
  3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
  4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

For more information on Event Notifications, refer to Event Notifications in this document or the Event Notifications .

Testing

The following table lists inputs and expected results that can be used for testing.

InputExpected result
accountNumber: 123456575
routingNumber: 124003116
Successful Authorization request.

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 Errors.

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

{
  "errors": [
    {
      "domain" : "com.paywithmybank.merchantgateway.v1.exception.InvalidParameterException",
      "code" : 200,
      "message" : "Could not find a transaction using Id 10000021"
    }
  ]
}
Error CodeDescription
100Internal error. An internal error (an internal database exception for example) occurred when trying to process the request.
150Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error.
200Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example).
300Security error. These are generic security errors that can happen when trying to process the request.
326Expired split token.
330Invalid account.
331Not enough balance.
375Access control error. These occur when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed.
390Fraud analysis. Suspicious transaction or negative data.

Further Reading


Did this page help you?