ViewAutomaticSettlementDetailsCSV

Overview

API method ViewAutomaticSettlementDetailsCSV
Trustly provides an option for automatic, periodical settlements. This is an optional feature available on request.

Settlement processing

Automatic settlements can be scheduled to run in one of the following ways:

1. Every day.
2. One or several days per week. For example every Wednesday, or every Monday and Thursday
3. The first day of every month.

The exact time at which settlements are processed may vary, but it should normally be no more than twelve hours after midnight UTC. A single settlement will include all transactions from the midnight (UTC) prior to the last settlement (inclusive) until midnight UTC of the day before the settlement is executed (exclusive).

For example: if settlements are executed once per week and the last settlement was executed on the morning of January 1, the next settlement will be executed on January 8 and include transactions from January 1 00:00 until January 7 23:59:59 (UTC).

There are a number of requirements which must be met for a settlement to be executed. The list of requirements is currently as follows:

1. Executing the settlement must not overdraw the Trustly account in that currency, and the Trustly account in that currency must not already be overdrawn.
2. The calculated total for the settlement must not be negative.
3. Executing the settlement must not leave the account’s balance under the minimum amount configured by the merchant. See more details under "Float-to-keep" below.
4. A settlement account for every currency with an above-zero total must have been configured. Settlement accounts cannot currently be configured via Back Office, and must be configured by Trustly.

If a settlement could not be executed due to any of the reasons above, the next settlement will include the transactions from the failed settlement batch. In the above example, if the settlement could not be executed on the 8th of January, the next attempt would be done on the 15th of January, and it would include all transactions executed between the 1st of January and the 14th of January. In the generated report, the transactions’ datestamp can be used to detect these cases.

Retrieving the settlement report through API

To view which transactions were part of a specific automatic settlement batch, the API method ViewAutomaticSettlementDetailsCSV should be used.

Request parameters

📘

APIversion

Note the APIVersion attribute which distinguishes this call from previous versions of the ViewAutomaticSettlementDetailsCSV method.

Response

If the call succeeded, the JSON RPC response will contain a Comma- Separated Values (CSV) format value in the "view_automatic_settlement_details" field. Fields in the CSV format are separated by a single comma (','). Records are separated by a single newline. The first record is always a ”header”, containing a list of field names.

The columns returned in the response hash are:

New columns might be added without notice. The order of the columns might change without notice.

Ordertypes

Below is the list of the different ordertypes that could show up in the report. The ordertypes that you will see in your own report depends on which Trustly API methods you have implemented.

Code example

{
  "method": "ViewAutomaticSettlementDetailsCSV",
  "params": {
    "Data": {
      "Attributes": {
        "APIVersion": "1.2"
      },
      "Currency": "EUR",
      "Password": "password",
      "SettlementDate": "2018-11-17",
      "Username": "merchant1"
    },
    "Signature": "3G5d1dR[...]iy0o+ww==",
    "UUID": "747bdc18-6b19-aed9-ee5c-61d16b93b944"
  },
  "version": "1.1"
}

{
  "version": "1.1",
  "result": {
    "method": "ViewAutomaticSettlementDetailsCSV",
    "uuid": "747bdc18-6b19-aed9-ee5c-61d16b93b944",
    "data": {
      "view_automatic_settlement_details": "datestamp,accountname,currency,amount,total,orderid,ordertype,messageid,username,fxpaymentamount,fxpaymentcurrency,settlementbankwithdrawalid,extraref\n
      \"2018-11-16 12:52:22.293626+00\",SUSPENSE_ACCOUNT_CLIENT_FUNDS_FINLAND_OKOY,EUR,100.00,145.00,1288208729,Deposit,9567705,merchant1,,,1434179572,\n
      \"2018-11-16 12:52:22.293626+00\",TRANSACTION_FEE_BANK_DEPOSIT,EUR,-1.00,145.00,1288208729,\"Deposit Fee\",9567705,merchant1,,,1434179572,\n
      \"2018-11-16 12:53:21.019497+00\",BANK_WITHDRAWAL_QUEUED,EUR,-100.00,145.00,1288208729,Refund,\"Refund 2018-11-16 13:53:21.019497+01 9567705\",merchant1,,,1434179572,\n
      \"2018-11-16 12:53:21.019497+00\",TRANSACTION_FEE_BANK_WITHDRAWAL,EUR,-1.00,145.00,1288208729,\"Refund Fee\",\"Refund 2018-11-16 13:53:21.019497+01 9567705\",merchant1,,,1434179572,\n
      \"2018-11-16 12:02:43.235847+00\",BANK_WITHDRAWAL_QUEUED,EUR,-100.00,145.00,1134212451,AccountPayout,275852136,merchant1,,,1434179572,\n
      \"2018-11-16 12:02:43.235847+00\",TRANSACTION_FEE_BANK_WITHDRAWAL,EUR,-1.00,145.00,1134212451,\"AccountPayout Fee\",275852136,merchant1,,,1434179572,\n
      \"2018-11-16 11:04:01.702755+00\",TRANSACTION_FEE_BANK_DEPOSIT,EUR,-1.00,145.00,2590840341,\"Deposit Fee\",1560785,merchant1,,,1434179572,\n
      \"2018-11-16 11:04:01.702755+00\",SUSPENSE_ACCOUNT_CLIENT_FUNDS_SWEDEN_SWED,EUR,150.00,145.00,2590840341,Deposit,1560785,merchant1,1500.00,SEK,1434179572,\n
      \"2018-11-16 10:48:19.142018+00\",FOREIGN_EXCHANGE_SPREAD,EUR,100.00,145.00,3061625784,FX,f6ee4ec7-3bb7-4182-8368-317b4ea28cc2,merchant1,1000,SEK,1434179572,\n
      \"2018-11-16 05:30:43.235847+00\",TRANSACTION_FEE_BANK_WITHDRAWAL,EUR,-1.00,145.00,,\"Settlement Fee\",\"Automatic EUR settlement 83942 for 1231459251 on 2018-11-16 05:30:43.225447+01  \",merchant1,,,1434179572,\n"
    },
    "signature": "XtQOBLxsn9cNh5NZGUHwoODunCpRDYPBvL[...]jpMWwImQvlOiZhogeV5I3DUHZxKHmPd+aHOA=="
  }
}

📘

Note that the literal newlines in the "view_automatic_settlement_details" field have been added to make the example easier to read. The actual value as returned by the API will not contain any literal newlines.

Float-to-keep

As described above, the amount to be settled is calculated at UTC midnight. This amount needs to be available on the merchant's Trustly account balance when the settlement is processed (usually not more than 12 hours after UTC midnight). If the full amount is not available due to an outflow of funds (refunds, payouts, or fees) during that period, the settlement processing will fail. 

To prevent this from happening, the merchant can add a "float to keep" (or just "float") which is an amount that will be left on the merchant's Trustly account after an automatic settlement has been processed. 

If the float (or parts of it) is reduced due to a refund, payout, or fee, the system will not make any more settlements until the total balance on the account is once again above the float amount.

Merchants can set the float by making a manual funding of their Trustly account. To do this, just log in to Trustly's backoffice and select Accounting > Account balances. Then choose "Deposit" for the currency that you would like to fund the account with. Instructions will appear to tell you how to make a manual bank transfer to your Trustly account.

If you wish to lower or remove the float, you can contact Trustly's support team.

📘

Float recommendations

Trustly recommands all merchants and Trustly Partners who are using automatic settlements to keep a "float" in order to prevent automatic settlements from failing. The recommended float amount depends on the expected outflow of funds during the night.

Example:

A merchant has configured a float of EUR 100. At UTC midnight, Trustly's automatic settlement system calculates that 2000 EUR should be transferred to the merchant's bank account.

At 01.30 AM, a refund of 50 EUR is processed. Since the merchant has a float of EUR 100 configured, the refunds does not cause any settlement failure. The settlement batch is processed as usual in the morning and sent to the merchant's bank account.

Later that same day, a deposit of 200 EUR is received on the merchant's Trustly account and no other transactions are done that day. The next morning, 150 EUR is transferred to the merchant's bank account.

The amount that is left on the merchant's Trustly account is 100 EUR since the float was configured to be 100 EUR. 50 EUR was taken from the 200 EUR deposit to "fill up" the float that was consumed by the last refund.

Information to Trustly Partners

The information below is only relevant to you if you are a collecting Trustly partner / PSP with a child/parent processing account setup.

Partner parent processing account setup

In order to enable Partner Merchants to benefit from different Trustly functionality and pricing, Partner Merchants are each set up with their own processing accounts. However, in order to enable Collecting Partners to regularly receive a single, consolidated settlement and reconciliation from Trustly covering all of their Merchants, (i.e. one settlement transfer per currency rather than individual settlement transfers per Partner Merchant, per currency), Trustly has introduced the concept of parent and child processing accounts.

Partners will have one parent processing account and several child processing accounts - one for each merchant. When calling Trustly’s API, e.g. with a Deposit call, the Username attribute will specify which Partner Merchant has generated each individual transaction. It is recommended to use the same public key for each child account but this is up to the Partner.

Funds that are deposited by end-users (“pay-ins”) will end up on the Trustly-held balance of the child processing account. Each day at midnight UTC, Trustly’s system will do a daily automatic sweep of funds from the Partners’ child processing accounts to the Partners’ parent account, after which time the funds are ready for automatic settlement to Partners’ own bank accounts. The sweep from child to parent accounts will happen each night, but Partners may choose their preferred settlement frequency from their Trustly parent accounts to their settlement bank accounts (e.g., daily, weekly, monthly).

When making the API call to ViewAutomaticSettlementDetailsCSV the username and password of the parent account should be used, not the username of any specific merchant.

Refunds

It may happen that a Partner Merchant wants to do a refund right after the funds from the child accounts have been transferred to the parent account. In that case, Trustly will check if there is enough balance on the parent account to execute the refund. If so, funds will be deducted from the parent account in order to execute the refund.

Example of automatic settlement with parent and child accounts

As an example, let’s assume a Collecting Partner has 2 Merchant processing accounts (Merchant A and B). Every night at midnight UTC, Trustly will transfer all available funds from Merchant A and B to the parent processing account, and then settle that consolidated amount to the Collecting Partner’s bank account (assuming the Partner has selected daily settlement).

Float-to-keep

The partner can decide if all available funds should be transferred from the parent account when the automatic settlements are processed, or if any funds should be left on the parent account to allow refunds to be made immediately after the sweep. The amount that is left in the account is called the "float-to-keep", or just "float".

If the float (or parts of it) is reduced due to a refund, the system will not make any more settlements until the total balance on the parent account is once again above the float amount.

Example:

A partner has 2 merchants A and B, and has configured a float of EUR 100. At midnight UTC all available funds are transferred from merchant A and B's child accounts to the partner's parent account. At 3.30 AM the funds are sent to the partner's bank account.

At 3.31 AM, merchant A requests a refund of 50 EUR. Since the partner has a float of EUR 100 configured, the refund can still be processed. If the partner would not have any float configured, the refund would have been denied.

Later that same day, merchant A receives a deposit of 200 EUR. Merchant B does not process any transactions that day. At UTC midnight, 200 EUR is transferred from Merchant A's child account to the parent account. At 3.30 AM, 150 EUR is transferred to the partner's bank account.

The amount that is left on the parent account is 100 EUR since the float was configured to be 100 EUR. 50 EUR was taken from Merchant A's deposit to "fill up" the float that was consumed by the last refund.

Partners can set the float by making a manual funding of their parent accounts. To do this Partners should log on to Trustly's backoffice and select Accounting > Account balances. Then choose "Deposit" for the currency that you would like to fund the account with. Instructions will appear to tell you how to make a manual bank transfer to your Trustly parent account.

If Partners wish to lower or remove their float, they need to contact Trustly's support team.

Automatic float adjustments (only with float-to-keep)

Automatic settlements are usually executed around 3:30 AM UTC and include all finalized transactions (i.e., money from a Deposit has arrived on Trustly’s account or been paid out for a Refund) from the day before. This means any transactions made between 0:00 AM and 3:30 AM the current day will not be included in the settlement for that day. This period, between 00:00 AM UTC and settlement time can be referred to as the 'yellow period'.

If the net amount is negative during the yellow period (i.e., if the total amount of refunds exceeds the total amount of deposits) the child account would end up with a negative balance after settlement. To accommodate for this and avoid failure of settlements, Trustly adjusts the amount to settle with the net balance change in the yellow period.

An example to clarify:

Day 1: Deposit EUR 50.

Day 2: Refund of EUR 10 during the yellow period.

To avoid failure of settlement, when Trustly settles Merchant funds to the Partner for Day 1, we will only settle EUR 40 so that the balance will not end up below 0.

When viewing the detailed settlement report for settlement date day 1 (ViewAutomaticSettlementDetailsCSV, referred to above), the Partner will see two rows, one with the deposit of 50 EUR and one 'Automatic Float Adjustment' of -10 EUR.

Additionally, in the detailed settlement report for settlement date day 2, the Partner will see two rows, one with the refund of -10 EUR and one 'Automatic Float Adjustment' of +10 EUR.

Error codes

These error codes can be returned for ViewAutomaticSettlementDetailsCSV calls. To handle errors, see Error handling.