Overview

MDD is our pan European Direct Debit offering that can be used for billers, subscriptions, payment-plans etc.
Direct debit combines the creation of mandates that are approved by the consumer and the pull payment performed by the merchant. In eg the Eurozone, the mandate is an abstraction while in SE/UK there exists a mandate in the scheme, however using our api the abstraction of the mandate is represented with an accountId (see futher down the docs for the description).

Concepts and back-ground

Rails like BACS, Bankgiro, Sepa DD have been around for quite a long time. Trustly combines these rails with open-banking to make the consumer journey as seamless and safe as one can onboarding onto these schemes.

Direct debit combines the creation of mandates that are approved by the consumer and the pull payment performed by the merchant. It also includes push, but with push, no mandate is required.

While integrating Trustly’s MDD service, it’s important to understand how to handle the notifications (link to notifications overview) and how they correlate to the order. If this is the first integration, please read the overview, cancel, pending, account notifications. There are a few additional attributes that MDD introduces, but in general an account notification is the same with all products.

A few important parameters are UUID which is how Trustly manages idempotency, if you reuse it you may get strange error messages if you change the content of the payload, please only re-use it if you didn’t get a response (timeout or a 500). MessageID which must be unique for each order, this can be seen as your own transaction id(sent in notifications along with the orderId). You either identify the notification based on the MessageID or on the OrderID. EndUserID should be your representation of the consumer in your system, can be an email, UUID or similar, but this is the consumer you will be charging.

Typically, you will have an order for a successfully setup mandate, when the mandate changes or if e.g. it fails to set up, a notification is sent by Trustly. This notification will refer to the order that you as a merchant received when creating the order. It’s important to note that in some rare cases, a notification may not be received by you in the same order as it was sent (e.g. retries due to network issues, being sent almost simultaneously etc). Please read this section carefully around how to manage this in the MDD service.
It’s also important to understand that the type of notification and the order is of importance, e.g. a cancel notification may mean different things for a debit or a mandate setup order.

The MDD service is using the following notifications which must be implemented: cancel, account, pending, batch, credit and debit. Please note that for credit and debit, it's referring to the merchant's side of things, eg when merchant's balance is increased a credit notification is sent and when the merchants balance is decreased a debit notification is sent.

Scheme details

This is just a short description of how the different schemes work and it's of importance of knowing the differences even though it's one api for all of them. For futher info, please contact your bank or

Cut-off times

As with the nature of direct debit, or all payments where there is no instant scheme, cut-off times are of importance to understand when the funds get's pulled from the consumers account and when one can expect the funds to arrive, it's not always the same day.

See the table below for the cut-off times, note that only banking days are accounted for.

BACS

In UK, we're acting as a bureau which means that the funds will land on an account owned by you as a merchant and Trustly acts as a technical provider. You will need to provide us with your SUN number and we'll provide you with a Bureau number. Please speak to your account manager for more on this.

The bacs payment scheme has been around since the 1970:s and has its peculiar properties. In the scheme, there's no information about successful instructions, only the failed ones are reported back. The scheme is aware of the mandate, eg it's registered within the scheme. It's also important to know about the Advanced notification period, and typically it's 10 days but can be negotiated with the bank. If it's 10 days, this means that one will have to wait 10 days after the mandate has been setup before a debit instruction can be sent.

It's important to understand the BACS 1-2-3 schedule and how it also works for non successful instructions taking it to a BACS 1-2-3-4-5 schedule.

For the normal, happy case

1. Submission day - this is the day that the file with instructions are submitted into the scheme.
2. Instruction day - this is the day that bacs informs the debtor and creditor bank about the instruction
3. Payment day - this is the day that the payment takes place, your bank account get's credited and the end-user's account gets debited.

For the case where there is an error, there's still the 1-2-3 going on, but day-3 also becomes day-1 for the reversal.

1. Submission day
2. Instruction day
3. Payment day, but also submission day for the reversal. Reason here is that your account will be credited in the lump-sum, but a separate debit will also take place.
4. Instruction day, informing debtor and creditor bank about the transfer
5. Payment day, the funds are taken from your account and end-user's account get's credited.

As of this long schedule, and also as some banks are slower on reporting, finding out that the instruction was really successful, one must wait 7 days to be sure. However, this can be configured on behalf of your need and eg sending the credit notification on day-3 you must be aware that the debit notification may arrive on day-7.

Bankgiro

Most of the times when we refer to bankgiro, we're actually referring to Autogiro but as we're also using other parts, bankgiro is the umbrella for the different services bankgirot provides. Sometimes also Autogirot is mentioned like bg Autogiro.

In SE, we're acting as a bureau which means that the funds will land on an account owned by you as a merchant and Trustly acts as a technical provider. You will need to provide us with your BankGiro number and we'll provide you with a Service Bureau Number. Please speak to your account manager for more on this.

Bankgiro is also an old scheme but works a bit different from BACS. The scheme sends information both around the successful and unsuccessful instructions and it's faster. Mandates are also registered within the scheme and a similar thing as the advance notification period exists, after the mandate is registered it have to pass 5 days before a debit instruction can be sent using the mandate. There may be other timelines that your bank will apply to you as a merchant.

Sepa DirectDebit

In the euro-zone, we're not a service bureau in the same way, and collection of funds happen via Slimpay. You will need to be onboarded with Slimpay and have your own CID. Please speak to your account manager for more on this.

In the Sepa DirectDebit, there's actually no real mandate registered within the scheme and hence not really an advanced notification period. After setting up the mandate, a debit instruction may be sent right away.

As an equivalent mechanism however, there's a "No questions asked" mechanism available meaning that the end-user can revert the payment within the bank without any interference from the banks hence it becomes important that the end-user is aware of why the funds where deducted and also to whom. This we solve by making sure the end-user has access to the account when setting it up, the CID is merchant specific and the virtual account is used for collecting the funds.

General notification information

Notifications are very central to the service and without handling them properly, your service will malfunction. Please make sure to handle the different notifications and also note the differences in parameters based on which context they are used from, eg a credit notification for a refund contains information to distinguish it from the credit notification for the direct-debit.

Please also note that when validating the signatures for notifications, you need to validate it with Trustly's public key as it's signed by Trustly's private key. This is in a way the other way around as when it comes to the requests you make. When signing the response, you use your own private key and Trustly is using your public key to validate the response.

If you are not able to handle the notification (not sending a valid response), Trustly will re-trigger the notifications for a period of time.

📘

Valid response to all notifications

The only valid response allowed to notification calls is "OK" and with a signature

Status	Description
OK	The only valid response to notification, if you couldn't handle the notification you may respond with anything else, eg failure or even a http-500 status.

Example

JSON

{
    "result": {
        "signature": "D5FjuMqf3H0Ku ... S16VbzR5v==",
        "uuid": "<the uuid for the notification received>",
        "method": "<the method of the notification>",
        "data": {
            "status": "OK"
        }
    },
    "version":"1.1"
}

Process overview

Below is a generic diagram on how direct debit works.

Mandates, enabling direct debits

A mandate is a representation of an agreement between the end-user and the merchant for pulling funds out of the end-user's account based on the agreement for the service.

DirectDebitMandate

Create a direct debit mandate. This will return a url that the end-user should be redirected to. Once the end-user completes the flow, the end-user will be redirected to the success-url and notifications will be sent accordingly. If done in a physical environment, an operator can collect the details on an iPad and start the setup process which the consumer can finish by reading the QR-Code with the camera on their mobile device to complete the setup of the mandate.

Request parameters

Response parameters

Please note that for native app integrations, append the query parameter "IsNative=true" to the url before launching it to make the application aware that it lives within a native app. Also, it's important that you do use the ReturnToAppUrl when creating the order and intend to use it in a native app.

Example request

{
  "method": "DirectDebitMandate",
  "params": {
    "Data": {
      "Username": "merchant_username",      
      "Password": "merchant_password",
      "MessageID": "your_unique_order_id",
      “EndUserID”: "unique_end_user_id",
      "NotificationURL": "https://URL_to_your_notification_service",
      "Attributes": {
        "AccountID": "12345678",
        "MerchantReference": "1234567890123",
        "Country": "GB",
        "Firstname": "Steve",
        "Lastname": "Smith",
        "Locale": "en_GB",
        "Email": "[email protected]",
        "MobilePhone": "+46709876543",
        "SuccessURL": "https://example.com/success",
        "FailURL": "https://example.com/fail",
        "AddressLine1": "74 Oxford Rd",
        "AddressLine2": "",
        "AddressCity": "Drighlington",
        "AddressPostalCode": "BD11 2YJ",
        "AddressCountry": "GB",
        "ReturnToAppURL": "yourCustomURLScheme://"
      }
    },
    "Signature": "Hh+sfaUnbtMKW[...]9YngA9bTpiqxw==",
    "UUID": "258a2184-2842-b485-25ca-293525152425"
  },
  "version": "1.1"
}

Example response

{
    "result": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "DirectDebitMandate",
        "data": {
            "orderid": "2190971587",
            "url": "https://checkout.trustly.com/mdd/checkout?sessionId=3f9.....377&orderId=8365631872"
        }
    },
    "version": "1.1"
}

CancelDirectDebitMandate

Cancels a direct debit mandate.

Request parameters

Response parameters

Example request

{
  "method": "CancelDirectDebitMandate",
  "params": {
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "OrderID": "123456789"
    },
    "Signature": "Hh+sfaUnbtMKW[...]9YngA9bTpiqxw==",
    "UUID": "258a2184-2842-b485-25ca-293525152425"
  },
  "version": "1.1"
}

Example response

{
    "result": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "CancelDirectDebitMandate",
        "data": {
            "result": "0" | "1",
            "rejected": "",
        }
    },
    "version": "1.1"
}

ImportDirectDebitMandate

Importing mandates is usually done when switching from one provider to Trustly and there are currently two scenarios supported, CREATE and REGISTER. The CREATE is used to get the information imported into Trustly's system which does not involve registering the mandate within the scheme. The REGISTER import is used when the mandate is to be re-registered within the scheme.

Notifications are sent in the same way as for creating mandates, eg account notifications and cancel notifications will/can be emitted for the order.

Please note that before importing mandates, you must speak to your account manager as this feature is only available when moving from one provider to another and by default this feature is not enabled.

Request parameters

Response parameters

Example request

{
  "method": "ImportDirectDebitMandate",
  "params": {
    "Data": {
      "Username": "merchant_username",      
      "Password": "merchant_password",
      "MessageID": "your_unique_order_id",
      “EndUserID”: "unique_end_user_id",
      "NotificationURL": "https://URL_to_your_notification_service",
      "Attributes": {
        "AccountID": "12345678",
        "MerchantReference": "1234567890123",
        "ImportType": "CREATE",
        "Country": "GB",
        "Firstname": "Steve",
        "Lastname": "Smith",
        "Email": "[email protected]",
        "MobilePhone": "+46709876543",
        "AddressLine1": "74 Oxford Rd",
        "AddressLine2": "",
        "AddressCity": "Drighlington",
        "AddressPostalCode": "BD11 2YJ",
        "AddressCountry": "GB",
      }
    },
    "Signature": "Hh+sfaUnbtMKW[...]9YngA9bTpiqxw==",
    "UUID": "258a2184-2842-b485-25ca-293525152425"
  },
  "version": "1.1"
}

Example response

{
    "result": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "ImportDirectDebitMandate",
        "data": {
            "result": "0" | "1",
            "rejected": "",
        }
    },
    "version": "1.1"
}

Mandate notifications

When status of the direct debit mandate changes, ie. when it becomes active, declined, changed or cancelled this is communicated through the account and cancel notification to the NotificationURL submitted when setting up the mandate. Make sure the NotificationURL can receive calls for a long time since mandates lives for a long time.

📘

Activation of mandates

When a consumer has signed the mandate Trustly will send an account notification containing the AccountID and directdebitmandate = 0 that indicates that the mandate is sent for approval. When the mandate is activated Trustly will send a new account notification with the same AccountID and directdebitmandate = 1. The mandate is now active and can be used to send charge. If the mandate for some reason is not approved Trustly will send a cancel notification with a reason.

📘

Deactivation of mandates

If a consumer cancels the mandate in the bank Trustly will send a cancel notification with a reason. In the case where consumer is setting up a new mandate, and the account is configured for only allowing one mandate per account, then the cancel notification will contain the accountId that is already in use.

📘

When consumer change bank

When a consumer changes bank account this is notified via account notification for the mandate order: An account notification is sent with directdebitmandate = 0 with the original accountid indicating deactivation of the mandate. Another account notification with directdebitmandate = 1 with a new accountid indicating activation of the mandate. The orderid is the same for both notifications. The order of the notifications can not be guaranteed.

Please note that this is enabled for UK/Bacs only. In sweden, there is basically no deactivation/activation sent, but the mandate will still be valid even if the consumer switches bank. For SepaDD, there's no mechanism for this.

Example Deactivation notification:

JSON

data: {
  ...
	 "orderid":"3473567567",
   "accountid":"1111111111",
   "attributes":
   {
   	"directdebitmandate":"0",
     ...
   }
}

Example Activation notification:

json

data: {
  ...
	"orderid":"3473567567",
   "accountid":"2222222222",
   "attributes":
   {
   	"directdebitmandate":"1",
     ...
   }
}

Please note that as these notifications may be received in reversed order, hence you must handle the deactivation of accountId and activation of the accountId independently of the order. By this, basically you need to be able to handle multiple accountId's for one order. Please also note that this is only applicable in the UK market, in SE this does not trigger any notifications and with Sepa it's not suppoted at all.

Mandate notification: account

The account notification is used to send information about the mandate and what account information the mandate is afflicted with. Please note that the notification is sent multiple times, eg once mandate is created and then later when it's activated.

Request parameters

Notification example

{
    "method": "account",
    "params": {
        "signature":"RI1PTmjTgr5Ig1p....AF7ejFUGxwKQ==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "notificationid":"35673567",
            "messageid":"453455465",
            "orderid":"3473567567",
            "accountid":"1234567890",
            "verified":"1",
            "attributes":
            {
                "directdebitmandate":"1",
                "country":"GB",
                "bankcode":"HSBC",
                "bank":"HSBC Bank",
                "clearinghouse":"United Kingdom",
                "name":"John Doe",
                "accountname":"Salary account",
                "descriptor":"**** ***4057",
                "lastdigits":"4057"
            }
        }
    },
    "version": "1.1"
}

Mandate notification: cancel

When a mandate has been cancelled/failed an account cancel notification is sent. Regardless if the consumer cancels the mandate in their bank or if the mandate is cancelled by the merchant. A cancel notification is also sent if the consumer would abort during the mandate setup.

Request parameters

Notification example

{
    "method": "cancel",
    "params": {
        "signature":"RI1PTmjTgr5Ig1p....AF7ejFUGxwKQ==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid":"3473567567",
            "messageid":"453455465",
            "enduserid": "[email protected]",
            "notificationid":"35673567",
            "attributes":
            {
                "reason":"FAILED",
                "details":"BACS ADDACS_1(INSTRUCTION CANCELLED BY PAYER)",
                "accountid":"1234567890",
                "merchantreference":"TRLY86492",
            }
        }
    },
    "version": "1.1"
}

Description of details, eg failure details

📘

Descripton of detail in cancel notfications

The reason for why a mandate was failed or cancelled can be found in the details.

Format for cancel notification detail:
[SCHEME] [CATEGORY]_[CODE](DESCRIPTION)
BANKGIROT SE
BANKGIROT TK73_02(MANDATE_CANCELLED_BY_PAYER_OR_PAYERS_BANK)
BANKGIROT TK73_04(MANDATE_NOT_FOUND_IN_BANKGIROTS_MANDATE_DIRECTORY)
BANKGIROT TK73_10(MANDATE_ALREADY_REGISTERED_IN_BANKGIROTS_DIRECTORY_OR_INQUIRY_PENDING)


BACS UK
BACS ADDACS_0(INSTRUCTION CANCELLED - REFER TO PAYER)
BACS ADDACS_1(INSTRUCTION CANCELLED BY PAYER)
BACS ADDACS_2(PAYER DECEASED)
BACS ADDACS_3(INSTRUCTION CANCELLED, ACCOUNT TRANSFERRED)
BACS ADDACS_B(ACCOUNT CLOSED)
BACS ADDACS_C(ACCOUNT TRANSFERRED TO A DIFFERENT BRANCH)
BACS ADDACS_D(ADVANCE NOTICE DISPUTED)
BACS ADDACS_E(INSTRUCTION AMENDED)
BACS ADDACS_R(INSTRUCTION REINSTATED)

BACS AUDDIS_1(INSTRUCTION CANCELLED BY PAYER)
BACS AUDDIS_2(PAYER DECEASED)
BACS AUDDIS_3(ACCOUNT TRANSFERRED)
BACS AUDDIS_5(NO ACCOUNT)
BACS AUDDIS_6(NO INSTRUCTION)
BACS AUDDIS_B(ACCOUNT CLOSED)
BACS AUDDIS_C(ACCOUNT TRANSFERRED TO A DIFFERENT BRANCH OF BANK…)
BACS AUDDIS_F(INVALID ACCOUNT TYPE)
BACS AUDDIS_G(BANK WILL NOT ACCEPT DIRECT DEBITS ON ACCOUNT)
BACS AUDDIS_H(INSTRUCTION HAS EXPIRED)
BACS AUDDIS_I(PAYER REFERENCE IS NOT UNIQUE)
BACS AUDDIS_K(INSTRUCTION CANCELLED BY BANK)
BACS AUDDIS_L(INCORRECT PAYERS ACCOUNT DETAILS)
BACS AUDDIS_M(TRANSACTION CODE/USER STATUS INCOMPATIBLE)
BACS AUDDIS_N(TRANSACTION DISALLOWED AT PAYERS BRANCH)
BACS AUDDIS_O(INVALID REFERENCE)
BACS AUDDIS_P(PAYERS NAME NOT PRESENT)
BACS AUDDIS_Q(SERVICE USER NAME IS BLANK)

Debiting end-user

Debiting the end-user is done with the DirectDebit instruction.

DirectDebit

This method is used to debit the end-user, please note that an active mandate is mandatory for this operation. Once the end-user has been debited a credit notification is sent, eg merchant account is credited.

Request parameters

Response parameters

Example request

{  
   "method":"DirectDebit",
   "params":{  
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Username":"merchant_username",
         "Password":"merchant_password",
         "MessageID":"your_unique_order_id",
         "NotificationURL":"https://URL_to_your_notification_service",
         "AccountID":"1234567890",
         "Amount":"25.00",
         "Currency":"GBP",
         "Attributes":{  
            "PaymentDate":"2022-11-17"
         }
      }
   },
   "version":"1.1"
}

Example response

{
  "result": {
     "method":"DirectDebit",
     "uuid":"258a2184-2842-b485-25ca-293525152425",
     "data":{  
        "result":"1",
        "rejected":"",
        "orderid":"1234512345"
     },
     "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA=="
  },
  "version": "1.1"
}

CancelDirectDebit

Cancels a direct-debit instruction. Please note that canceling a future debit must be submitted 1-2 banking-days ahead of the payment date.

Request parameters

Response parameters

Example request

{  
   "method":"CancelDirectDebit",
   "params":{  
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Username":"merchant_username",
         "Password":"merchant_password",
         "OrderID":"1234512345",
      },
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h=="     
   },
   "version":"1.1"
}

Example response

{  
  result: {
    "method":"CancelDirectDebit",
    "uuid":"258a2184-2842-b485-25ca-293525152425",
    "data":{  
       "result":"1",
       "rejected":"",
    },
    "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA=="
  },
  "version":"1.1"
}

Notifications for DirectDebit

Pending

Immediately after the request has been accepted for processing, a pending notification is sent to the NotificationURL.

Request parameters

Example request

{
    "method": "pending",
    "params": {
        "uuid": "258a2184-2842-b485-23ca-293425152415",
        "data": {
            "orderid": "87654567",
            "accountid": "1234567890",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "amount": "98.02",
            "currency": "GBP",
            "paymentdate": "2024-01-05",
						"timestamp": "2010-01-20 14:42:04.675645+01"
        },
        "signature": "fVhjuMqbsH0Ku ... S16VbzRsw=="      
    },
    "version": "1.1"
}

cancel

If the direct-debit could not be processed, a cancel notification is sent.

Request parameters

Example request

{
    "method": "cancel",
    "params": {
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "attributes": {
            	"reason": "ERROR_CHARGE_NOT_APPROVED",
            	"detail": "BACS ARUDD_1(INSTRUCTION CANCELLED BY PAYER)",
            }
        },
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

credit

When funds have credited the account, a credit notification is sent.

Request parameters

Example request

{
    "method": "credit",
    "params": {
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001"
            }
        }
    },
    "version": "1.1"
}

debit

If a previously credited direct-debit is revesed, a debit notification is sent for the same order. This basically means that the funds where sent to the merchant account and later sent back to the end-user account.

Request parameters

Example request

{
    "method": "debit",
    "params": {
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "asdfasdasdf",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "messageid": "98348932",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001",
            	"reason": "ERROR_CHARGE_NOT_APPROVED",
            	"detail": "BACS ARUDD_1(INSTRUCTION CANCELLED BY PAYER)"              
            }
        },
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

Crediting end-user

Crediting the end-user is done with the DirectCredit instruction. Note that credit is not available in the SEPA region, instead a refund will have to be used.

DirectCredit

This method is used to credit the end-user, eg transferring funds from your account to the consumer. As this feature is a bit different depending on market, please check the differences below

[BACS] - Crediting the user can be archived either by specifying the accountId or the full account number (sort-code and account number). If you know the accountId for the consumer, it’s a convenient way to send funds to the account behind that account number.
[Bankgiro] - Crediting the user can be done in two ways, either via Autogiro or via “Leverantörsutbetalningar”. Using Autogiro, you must use the merchantReference as that is mapped to the payerNumber in Autogiro which is to whom the credit is sent. Please note that for this, the mandate must be active. For this, there must be an active mandate. With “Leverantörsutbetalningar”, you may send funds to another bankgiro-number or any other swedish bank account. You will however need to have this enabled with your bank.
[SepaDD] - Credit is not available using the direct debit rails, however, if needed, you may use the Trustly AccountPayout functionality but that will require your Trustly account to be funded.

For Bankgiro, it's important to use the merchantReference if accountId is used, as it's basically the merchantReference that is mapping to the correct account number. If just AccountNumber/BankIdentifier fields are used, then the merchantReference is not in use at all.

Request parameters

Response parameters

Example request

{  
   "method":"DirectCredit",
   "params":{  
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Username":"merchant_username",
         "Password":"merchant_password",
         "MessageID":"your_unique_order_id",
         "EndUserID":"unique_end_user_id",
         "NotificationURL":"https://URL_to_your_notification_service",
         "AccountID":"1234567890",
         "Amount":"25.00",
         "Currency":"GBP",
         "Country": "GB",
         "Attributes":{  
            "PaymentDate":"2022-11-17",
            "MerchantReference": "AAADESF0F1"
         }
      },
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",     
   },
   "version":"1.1"
}

Example response

{  
  "result": {
     "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA==",
     "uuid":"258a2184-2842-b485-25ca-293525152425",
     "method":"DirectCredit",
     "data":{  
        "result":"1",
        "rejected":"",
        "orderid":"1234512345"
     }
   },
   "version":"1.1"
}

Notifications for DirectCredit

Notifications for the direct credit. Please note that the debit/credit notifications should be treated differently than for direct-debit. For a successful credit, a debit notification is sent. If the funds would come back, the credit notification will be emitted for the direct credit order.

Pending

Immediately after the direct-credit has been accepted for processing, a pending notification is sent to the NotificationURL.

Request parameters

Example request

{
    "method": "pending",
    "params": {
        "uuid": "258a2184-2842-b485-23ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "amount": "98.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01"
        },
        "signature": "fVhjuMqbsH0Ku ... S16VbzRsw=="      
    },
    "version": "1.1"
}

cancel

If the direct-credit could not be processed, a cancel notification is sent.

Request parameters

Example request

{
    "method": "cancel",
    "params": {
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "attributes": {
            	"reason": "",
            	"detail": "",
            }
        },
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

debit

Once the direct-credit has been successfully processed, a debit notification is sent for the same order. This basically means that the funds where deducted from the merchants account.

Request parameters

Example request

{
    "method": "debit",
    "params": {
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "asdfasdasdf",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "messageid": "98348932",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001",
            	"reason": "FAILED",
            	"detail": ""              
            }
        },
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

credit

If the funds where sent, but later returned, a credit notification is sent for the order.

Request parameters

Example request

{
    "method": "credit",
    "params": {
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001"
            }
        }
    },
    "version": "1.1"
}

Refunding end-user

Refunding a previous executed DirectDebit instruction is similar to DirectCredit, but with some restrictions. A refund can only be executed once and the maximum amount is the same as for the original debit. Refunds are available for all schemes.

RefundDirectDebit

This method is used to credit the end-user, please note that an active mandate is NOT mandatory for this operation, but the mandate must not have been inactive for more than 2 years.

Request parameters

Response parameters

Example request

{  
   "method":"RefundDirectDebit",
   "params":{  
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Username":"merchant_username",
         "Password":"merchant_password",
				 "OrderID": 123123123,
         "MessageID":"your_unique_order_id",
         "Amount":"25.00",
         "Currency":"GBP",
      },
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",     
   },
   "version":"1.1"
}

Example response

{
  "result": {
     "method":"RefundDirectDebit",
     "uuid":"258a2184-2842-b485-25ca-293525152425",
     "data":{  
        "result":"1",
        "rejected":""
     },
     "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA=="
  },
  "version":"1.1"
}

Notifications for Refunds

Notifications for the refund are handled differently from the DirectCredit/DirectDebit, especially as there's no orderId for the refund, all notifications will refer to the original direct debit order, but you can distinguish the notifications by checking if the refund flag is available or not.

Pending

Immediately after the refund has been accepted for processing, a pending notification is sent to the NotificationURL for the original DirectDebit order.

Example notification

{
    "method": "pending",
    "params": {
        "uuid": "258a2184-2842-b485-23ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "amount": "98.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "refund": "1"
        },
        "signature": "fVhjuMqbsH0Ku ... S16VbzRsw=="      
    },
    "version": "1.1"
}

Cancel

If the refund fails for some reason, a cancel notification will be sent. Note that this will only be sent if no money have been deducted on the account and treat this notification differently than a debit followed by a credit. Please make sure to check the refund flag on the notification.

Example notification

{
    "method": "cancel",
    "params": {
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "4876513450",
            "refund":"1",
            "attributes": {
            	"reason": "",
            	"detail": "",
            }
        },
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

debit

The debit notification for the refund is sent when a confirmation that the funds have left your account.

Example notification

{
    "method": "debit",
    "params": {
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "asdfasdasdf",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "refund": "1",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001"
            }
        },
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

credit

If funds left the account, but later bank returned the funds, a credit notification is sent.

Example notification

{
    "method": "credit",
    "params": {
        "signature": "D67hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "enduserid": "[email protected]",
            "notificationid": "9876543456",
            "amount": "90.02",
            "currency": "GBP",
            "timestamp": "2010-01-20 14:42:04.675645+01",
            "refund": "1",
            "attributes": {
            	"reference": "TRLY80494-1001",
            	"statement": "TRLY80494-1001"
            }
        }
    },
    "version": "1.1"
}

Payment batch

DirectPaymentBatch

Sends multiple payment instructions for directdebit for already existing mandates or credits(no need for a mandate). You connect to the sftp server with the username provided by Trustly and the same private key used to sign the requests. Please note that if the content of the file is rejected the response will be successful however you will receive a cancel notification.

Please see the SFTP section for how to connect and where to put/read files.

Request parameters

Response parameters

Request example

{  
   "method":"DirectPaymentBatch",
   "params":{  
      "Signature":"f4ThjuMqbsdG6u ... S16VbzD4h==",
      "UUID":"258a2184-2842-b485-25ca-293525152425",
      "Data":{  
         "Username":"merchant_username",
         "Password":"merchant_password",
         "MessageID":"your_unique_order_id",
         "NotificationURL":"https://URL_to_your_notification_service",
         "Currency":"GBP",
         "Country":"GB",
         "BatchFile":"batch-20230215.csv",
         "Checksum":"0cdf0945096283b9ba94e42150ba84d8",
         "Attributes":{  
            "PaymentDate":"2022-11-17"
         }
      }
   },
   "version":"1.1"
}

Response example

{
  "result": {
     "method":"DirectPaymentBatch",
     "uuid":"258a2184-2842-b485-25ca-293525152425",
     "data":{  
        "result":"1",
        "rejected":"",
        "orderid":"1234512345"
     },
     "signature":"QBuLx ... JDGM/GVq5EBaPnGmvxA=="
  },
  "version":"1.1"
}

Notifications for PaymentBatches

Notifications for batch behave a bit different as they always refer to the order and not each individual debit/credit.

Pending

Immediately after the batch has been accepted for processing, a pending notification is sent to the NotificationURL submitted when setting up the batch.

Request parameters

Example request

{
    "method": "pending",
    "params": {
        "signature": "fVhjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-23ca-293425152415",
        "data": {
            "amount": "98.02",
            "currency": "GBP",
            "messageid": "98348932",
            "orderid": "87654567",
            "notificationid": "4876513450"
        }
    },
    "version": "1.1"
}

Cancel

The cancel notification will be sent for a batch if it could not be processed.

Request parameters

Example request

{
    "method": "cancel",
    "params": {
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "orderid": "87654567",
            "messageid": "98348932",
            "notificationid": "4876513450",
            "attributes": {
            }
        },
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",      
    },
    "version": "1.1"
}

Batch

Sent when the batch has been processed and the result report is available for download on the SFTP server. Note that this file will be available after a couple of days and depends on the processing time for the scheme. If a change occurs after the first notification, subsequent notifications will be sent containing only the instructions affected. So, eg for UK, if the batch notification is sent after three days, a reversal happens on two instructions after 6 days, a new batch notification will be sent and the csv will ONLY contain those instructions and their state.

Request parameters

Example request

{
    "method": "batch",
    "params": {
        "signature": "F6+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-9021-b874-21ca-293425152415",
        "data": {
            "messageid": "98348932",
            "orderid": "87654567",
            "notificationid": "4876513450",
            "attributes": {
            	"batchfile": "batch.csv",
            	"reportchecksum": "0cdf0945096283b9ba94e42150ba84d8",
            	"reportfile": "batch.csv_20230215_report.csv",
            	"executed": 1231,
            	"failed": 0
            }
        }
    },
    "version": "1.1"
}

Transportation layer for batch

Transportation for batch is sftp and this part describes how/where you upload and download files over SFTP and how you should work with the flow. On the server, the files must be placed in a specific folder.

📘

/batch/

Note make sure to use the batch folder, there are also the reports folder where you will not be able to write.

📘

For the batch files, retention period is 4 weeks.

SFTP interaction

When uploading the batch file and downloading reports, SFTP is used. The API is not solely built upon SFTP rather a combination of JSON-RPC and then SFTP for transfering the data. It’s important to understand the flow, and it’s driven by the JSON-api, which instructs Trustly to look for a specific file on the SFTP server. Reporting status for the payments happens the same way, eg Trustly will upload the report file and once there send the notification that the report is available.

Sending batch file

1. Create the CSV-File according to the specification and name it to something unique, eg request-20230215.csv.
2. Calculate the MD5 checksum of the file (eg on osx/linux, ‘md5sum file’)
3. Upload the CSV-File to the SFTP server
4. Create the DirectDebitBatchCharge request and set the value of BatchFile and Checksum to the values from above (1 & 2)

Batch notification

1. When receiving the notification, respond back to Trustly that the notification has been received.
2. Download the report from the SFTP server based on the information in the batch notification
3. Process each row in the CSV and update your internal status for each payment.

Batch Process overview

Batch file format

The file-format used via SFTP is Comma Separated Values (CSV) which is a standard widely used. It’s however important to care about the character-set as well as separators etc, the table below describes what to use.

CSV format

Please note that Trustly may add more columns to the right of this.

"DEBIT","12312313",12.50,"345678901","12345678",INITIAL
"DEBIT","12312314",21.00,"345678902","12345679",
"DEBIT","12312315",39.70,"345678903","12345670",RECURRING
"DEBIT","12312316",9.10,"345678904","12345671",

CSV Report format

"DEBIT","12312313",12.50,"345678901","12345678","","","","2023-05-31T09:19:30.066773Z","DONE",""
"DEBIT","12312314",52.50,"345678902","12345678","","","","2023-05-31T09:19:30.066773Z","DONE",""
"DEBIT","12312315",32.50,"345678903","12345678","","","","2023-05-31T09:19:30.066773Z","DONE",""
"DEBIT","12312316",22.50,"345678904","12345678","","","","2023-05-31T09:19:30.066773Z","FAILED","Invalid mandate"

Reports

Reports for billing, mandates, debits and credits are available via SFTP. The reports are available for 12 month from creation and files have a naming convention according to below:

[username]_[scheme]_[day]_[type]_[category].csv.zip
eg for test, bacs, generated day dec-10, daily , debits -> 
test_bacs_2024-01-10_daily_direct_debit_transitions.csv.zip

There are daily reports, where from and to are the same, weekly and monthly reports. All files are reported in CSV format specified under batch csf-format.

Reports are located under the folder

📘

/reports/

Types

Billing report

Example file: trustly_bankgirot_2023-12-01_monthly_billing_items.csv.zip

"Order ID","Message ID","End user ID","Type","Count","Created","Transitioned"
4501293578,"6472c348-282f-4464-9ba9-58b9fdff134d","tester","Successful mandate",1,"2023-11-30T18:02:21.475995Z","2023-12-01T00:30:00.40995Z"
7296456249,"d8354110-6047-4de3-bbd2-6e1a850533e7","tester","Successful mandate",1,"2023-11-30T13:46:50.517494Z","2023-12-04T00:30:00.471891Z"
7140026006,"6f91f17f-193a-486e-8e57-29a642281b2f","tester","Successful mandate",1,"2023-12-04T17:35:58.278369Z","2023-12-05T00:30:00.415242Z"

Mandate report

Example file: trustly_bankgirot_2023-12-01_monthly_mandate_transitions.csv.zip

"Order ID","Message ID","End user ID","Reference","Status","Failure reason","Failure details","Account ID","Amount","Currency","Created","Transitioned","Transitions"
7472622143,"c53ed295-24c1-4eb3-863e-c7de72f5ded6","tester",,"Failed","CHECKOUT_TIMEOUT",,,"N/A",,"2023-12-11T06:03:42.532931Z","2023-12-11T06:34:28.092312Z",
5988131268,"72a9d463-6cac-45a9-b4c7-f5695e6ca752","tester","**********6665","Successful",,,"2672607922","N/A",,"2023-12-07T16:08:11.281118Z","2023-12-11T00:30:00.486905Z","[\"Activated\"]"
4883244788,"8105c922-8fc6-4910-b9cb-35640ef90a72","tester",,"Cancelled",,,,"N/A",,"2023-12-05T10:47:54.479135Z","2023-12-05T10:48:19.734216Z",
4397008398,"5991523a-0477-4bde-853a-70a274c8a17b","tester","**********28076","Successful",,,"1326674678","N/A",,"2023-12-04T17:29:19.779894Z","2023-12-05T00:30:00.48104Z","[\"Activated\"]"
7140026006,"6f91f17f-193a-486e-8e57-29a642281b2f","tester","***********1013","Successful",,,"3805670135","N/A",,"2023-12-04T17:35:58.278369Z","2023-12-05T00:30:00.426667Z","[\"Activated\"]"

Debit report

Example file: trustly_bankgirot_2023-12-01_monthly_debit_payment_transitions.csv.zip

"Order ID","Message ID","End user ID","Reference","Status","Failure reason","Failure details","Account ID","Amount","Currency","Created","Transitioned","Transitions"
4755295954,"ba1df3cf-b42c-4c0f-b664-cc2eb73c6aa2","tester","*********0001GA","Failed","FAILED","BANKGIROT INSUFFICIENT_FUNDS","1304686402","1.00","SEK","2023-09-11T12:12:12.706088Z","2023-09-19T12:30:00.336048Z","[""Failed""]"
4344666554,"4f17bce4-db14-43ef-b725-c32613741391","tester","*********00018Y","Successful",,,"2880023560","1.00","SEK","2023-08-29T07:35:42.639077Z","2023-09-01T12:17:00.382302Z","[\"Successful\"]"

Credit report

Example file: trustly_bankgirot_2023-12-01_monthly_credit_payment_transitions.csv.zip

"Order ID","Message ID","End user ID","Reference","Status","Failure reason","Failure details","Account ID","Amount","Currency","Created","Transitioned","Transitions"
6406872524,"02173724-29a4-43e7-b907-53cf26d80fcd","""[email protected]""","CREDIT000000000Y","Successful",,,"1964406719","1.00","SEK","2023-09-19T06:40:48.85847Z","2023-09-20T09:30:00.324763Z","[""Successful""]"

SFTP

The sftp server is available on the following locations for sandbox/test and production

📘

Sftp host's for the different environments

• Production: sftp.prd.trustly.cloud
• Test: sftp.sbx.trustly.cloud

It's used both for the batch processing as well as for reports.

Connecting to the server

Important: The private key is extremely secret and should only be kept by authorised personnel.

Then you connect to the SFTP server like this

sftp -i your_private_key.pem [email protected]
cd batch // or cd reports
get/put file

Once there, use the normal ftp commands to transfer files to and from the server. How long the files are kept on the server varies from folder to folder, see the different sections for retention periods.

Test Scenarios

The test scenarios can be selected by clicking on the Show Test Scenarios link in checkout.
The mandates and payments involved in test scenarios are never added to batches and are for mock purposes only.

Activate mandate 10s after confirmation

This will activate the mandate 10s after it has been confirmed in the checkout.

Fail mandate 10s after confirmation

This will deactivate the mandate 10s after it has been confirmed in the checkout.

Activate mandate 10s and simulate account transferred after 10s

This will activate the mandate 10s after it has been confirmed in the checkout and do an account transfer on the mandate.

Fail debit payment for this mandate after 10s

This will simulate a debit payment failure in 2 steps:

• Sign up for a mandate in the checkout, it will activated 10s after it has been confirmed.
• Do a direct debit charge on the activated mandate and it will be marked as failed.

Complete debit payment for this mandate after 10s

This will simulate a successful debit payment in 2 steps:

• Sign up for a mandate in the checkout, it will activated 10s after it has been confirmed.
• Do a direct debit charge on the activated mandate and it will be marked as successful.

Fail credit payment for this account after 10s

This will simulate a credit payment failure in 2 steps:

• Sign up for a mandate in the checkout, it will activated 10s after it has been confirmed.
• Do a direct credit charge on the activated mandate and it will be marked as failed.

Complete credit payment for this account after 10s

This will simulate a successful credit payment in 2 steps:

• Sign up for a mandate in the checkout, it will activated 10s after it has been confirmed.
• Do a direct credit charge on the activated mandate and it will be marked as successful.