API integration

The intended audience for this document is the person responsible for the technical implementation of Trustly's API. Basic knowledge of network programming and monetary transactions are required. Any operating system and any programming language can be used to integrate this API.

General overview of the Trustly integration process:

1. Get a Trustly test account
First you need a Test environment account. Generate a private and public key pair as described on the Signature page.

2. Test credentials
Send your newly generated public key to your Trustly contact person. We will create your test account and provide you with the username and passwords for the API and backoffice.

3. Back end
Integrate Trustly's API with your system: Deposit, Refund, Withdraw etc (all available API methods are listed below and in the menu to the left. Also check out our Notifications process.

4. Front end
Adjust your checkout section according to our Service Presentation Guidelines. Provide Trustly with screenshots or access to your test environment for verification in step 6.

5. Acceptance testing
Successfully test all API methods that will be integrated, and perform build-in test cases via Trustly's checkout.

6. Verification by Trustly
Trustly runs front-end and back-end tests of your integration and service presentation, await approval.

7. Go live
After approval, generate a new key pair and send the public key to your contact person. We will reply with live credentials so you can launch Trustly in your webshop!

API overview

JSON-RPC

The API follows the JSON-RPC for requests and replies.

The API is invoked by sending a request using HTTPS POST to our API. The URL for the API can be found on the Live environment and Test environment pages.

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 are sent for Deposit, Withdraw or SelectAccount.

Reporting/ Reconciliation

  • 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 merchant's trustly account to their bank account)
  • 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

  • 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 for TDD to register a direct debit mandate and / or to collect KYC details of the end user.
  • Trustly Direct Debit - Enables convenient bank transfers and payments through Direct Debit schemes (e.g. Autogiro in Sweden). Both one-click payments and interaction-free payments (suitable for subscriptions) are supported. The service is based on a mandate from the consumer for Trustly to debit his/her bank account.
  • 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.
  • 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.

Notifications

Notifications are sent from Trustly's system to give the merchant updates on the status of an order. They are sent to the merchant's NotificationURL, which is a parameter that must be specified in the API-calls.

Settlements to the merchant's bank account

Settlements from the merchant's Trustly account to their own corporate bank account are done through the Trustly Backoffice (Accounting > Account Balances > Withdraw), or by asking Trustly to enable automatic settlements / transfers. Automatic settlements can be scheduled to run daily, on certain days of the week, weekly, or monthly.

Trustly's backoffice

Trustly has a full-featured back office, allowing monitoring of transactions and handling of support enquires. Please see Live environment and Test environment for the URL to the Backoffice (note - the password for the backoffice is not the same as the password for the API).

Paying with Trustly - how it works

When a consumer chooses to pay with Trustly in a merchant’s checkout, a list of available banks are displayed. After choosing their bank the consumer execute the payment using their credentials issued by the bank.

When consumers make payments with Trustly at your webshop, you receive an instant notification of the confirmed payment. Please see charts of the consumer and system interaction below.

Consumer interactionConsumer interaction

Consumer interaction

System interactionSystem interaction

System interaction

Example code

We have example implementations of the communication with the Trustly API. The examples are available in the following programming languages: PHP, Python and Java.

To see more you can go the the Examples and tools section.