Partner integrations

Introduction

The purpose of this page is to provide Trustly’s Partners with a high-level overview of the Integration Process in order to ensure an optimal, speedy, “first-time-right” integration between the Partner’s platform and Trustly’s platform.

Code libraries for integrating Trustly's API can be found here.

Please note that unless you are using the Express Merchant On-boarding (see below), every merchant should have a separate Trustly processing account, meaning that the username and password parameters that are used in the API calls will be unique to each merchant. The public/private key can be the same for all merchants as long as the private key is only stored on the Partner's side, and the merchants themselves don't have access to it.

Bank payments (Pay-ins)

Trustly supports two ways to receive payments from end users:

• Deposit - allows an end user to make a deposit (pay-in) from their bank account. The merchant makes a deposit call, and our API returns a URL that the merchant should display in an iframe on their site where the end user can then log in to their bank account and approve the payment.
• Charge - For Trustly Direct Debit (TDD) – See below under “Other Products”. Charge / pull money from an account that has previously been registered with a direct debit mandate.

Pay-outs

There are 3 different API methods that can be used to make a pay-out to an end user's bank account.

• Refund - used when a merchant wants to make a refund for a previous Deposit. Partial refunds are supported, and also multiple refunds on a single deposit as long as the total refund amount does not exceed the original deposit amount.
• Withdraw - allows an end user to make a withdrawal by selecting their bank account in the Trustly iframe. Mostly used by gaming merchants and e-wallets.
• AccountPayout - Triggers a payout to a bank account using API calls only (no end user interaction like Withdrawals). Requires an AccountID, which is a unique identifier generated by Trustly for the receiving bank account. Merchants can receive the AccountID in account notification that is sent for Deposit, Withdraw or SelectAccount.

Reporting/ Reconciliation

1. ViewAutomaticSettlementDetailsCSV - returns the ViewAutomaticSettlementDetailsCSV report, which contains information about all transactions that are included in an automatic settlement for a specified date. Should be implemented by merchants who are using automatic settlements (meaning automated daily/weekly/monthly transfers from the Partner's or merchant's trustly account to their bank account)
2. AccountLedger - returns the Account Ledger report which contains all transactions on the merchant's Trustly account. Useful for reconciliation. This report can also be downloaded manually through our backoffice.

Other products

1. SelectAccount - Allows an end user to log in to their bank and select their bank account. The merchant will then receive an account notification containing an AccountID which can be used in the AccountPayout method. Can also be used to collect KYC details of the end user.
2. Merchant Direct Debit - Enables convenient payments through Direct Debit schemes (Autogiro in Sweden, SEPA Direct Debit in Euro Countries and BACS in UK).
3. iDEAL - Allows Dutch end users to make deposits using iDEAL. Technically the same integration as regular Deposit (see above) with one additional attribute in the API call.
4. Lean KYC - Supports merchants in fulfilling their regulatory KYC (Know Your Customer) requirements and preventing fraud. Data is retrieved from the end user’s banking facility and is instantly presented to the merchant in Back Office or via the account notification.

Express Merchant Onboarding

For Collecting Partners, we strongly recommend implementing Trustly’s Express Merchant Onboarding functionality. This functionality uses a "Master Processing Account" for low-risk ( E-commerce, Travel, and Digital Goods) SME merchant processing. Under this set-up, all transactions for merchants within the same industry are aggregated under a single Trustly Processing Account. So the Parter just needs one set of API credentials (Username/Password) for each merchant vertical, instead of separate ones for every merchant, and Partners can then board merchants themselves, without needing to send Trustly the Online Merchant Boarding form for each Merchant.

Merchant Acceptance via Express Merchant Onboarding

Trustly’s Express Merchant Onboarding setup is only allowed for Collecting Partners, and only for merchants classified as low-risk General Retail/eCommerce, Digital Goods (excluding Gambling) and Travel Merchants.

For merchants in all other verticals (Financial Services, Gambling, other high-risk, such as NGOs, Charities, etc.), each merchant will need to have their own Trustly processing account, which means that the Username and Password parameters that are used in the API calls will be unique to each merchant. But even when separate Trustly processing accounts are required, the public/private key can be the same for all merchants as long as the private key is only stored on the Partner's side, and the merchants themselves don't have access to it.

Note that since merchants boarded via Express Merchant Onboarding will all share the same Processing Account, it is not possible to have bespoke pricing between Trustly and the Partner for these merchants. Any Merchants requiring bespoke pricing that differs from Trustly’s standard buy-rates will need to be set up on their own individual processing account. Similarly, risk settings (exposure limits) will be identical for all merchants boarded via Express Merchant Onboarding, as they will share a single Master Processing Account.

Technical Requirements

In order to take advantage of Trustly’s Express Merchant Onboarding, some extra attributes must be sent in every API call (Deposit, Withdraw, SelectAccount and AccountPayout) so that Trustly can easily identify information about the merchant behind each transaction. The additional required API attributes are as follows:

The Collecting Partner also needs to provide additional details about the merchant in the RecipientInformation{} attributes for Deposit and SenderInformation{} for the AccountPayout and Withdraw method.

Note: If the PSPMerchant is acting as a PSP of the Payer / Payee or as an Intermediary PSP, then SenderInformation{} and RecipientInformation{} attributes must contain details of the Payer / Payee and not of the PSPMerchant.

Below is a Deposit example with the RecipientInformation{} attributes included:

{
  "method": "Deposit",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Attributes": {
        "Amount": "100.00",
        "Country": "SE",
        "Currency": "SEK",
        "Email": "[email protected]",
        "FailURL": "https://example.com/fail",
        "Firstname": "Steve",
        "Lastname": "Smith",
        "Locale": "sv_SE",
        "MerchantCategoryCode": "5499",
        "PSPMerchant": "Merchant Ltd",
        "PSPMerchantURL": "www.merchant.com",
        "RecipientInformation": {
             "Address": "Merchant Road 101",
             "CountryCode": "SE",
             "CustomerID": "merch_001",
             "DateOfBirth": "5563427391",
             "Firstname": "Merchant Ltd",
             "Lastname": null,
             "Partytype": "ORGANISATION"
          },
        "SuccessURL": "https://example.com/success"
      },
      "EndUserID": "349058342902",
      "MessageID": "7717834",
      "NotificationURL": "https://www.test.com/Trustly/a2b63f1h1",
      "Password": "*******",
      "Username": "partner_001"
    }
  },
  "version": "1.1"
}

Frequently asked questions

How long will the integration take?

A typical integration to the Trustly platform takes approximately eight weeks (including acceptance testing), depending upon the amount of functionality to be implemented and the dedicated focus of resources on the Partner’s side.

What functionality do I need to implement?

As part of the kick-off call to launch the integration, Trustly’s Integration team will discuss each element of Trustly functionality, and in light of your merchant and market focus, we will recommend the functionality and configuration settings that you need.

We strongly recommend that you take advantage of this integration project to implement as much Trustly functionality and geographical coverage as you might need in the next 3-4 years. As such, our standard integration includes both pay-ins (deposits) and pay-outs (withdrawals, refunds), Lean KYC, multi-currency functionality, and the full range of settlement and reporting options.

How does the acceptance testing work?

Acceptance Testing requirements and instructions can be found on Trustly’s Developer Portal by clicking here.

What is the merchant boarding process?

Unless you are using the Express Merchant On-boarding (see above), Trustly collects merchant information for boarding via an online merchant boarding form.

For non-gambling merchants signed up by collecting Partners, Partners need simply to fill in the information requested in the online boarding form, and we will configure the merchant’s account for live processing.

For gambling merchants, we will require merchant acceptance of Trustly’s terms and conditions or merchant agreement, plus KYC information on the merchants, prior to enabling processing.

For those merchants where Trustly requires a direct merchant contract (gambling merchants, remittance merchants and all merchants boarded via technical (non-collecting) Partners), the online boarding form will return to the Partner a link to Trustly’s terms and conditions, which will simply need to be accepted by the merchant. Additionally, Trustly will require KYC documentation and approval for all merchants with whom we have a direct contract.