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 further down the docs for the description).
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 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 article 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.
This brief overview provides a description of the functioning and differences of the various schemes supported by our unified API. For further in-depth details, we recommend contacting your financial institution or reaching out to our support team.
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.
| Scheme | Cut-off | PaymentDay |
|---|---|---|
| BACS(UK) | 19:00 UTC | T+2, meaning if you submit the instruction before cut-off, the funds will leave the end-user’s account on day-3. Submitting it at 18:00 UTC on a Friday, means that the funds leave end-user account on Tuesday. Your account will also be credited on Tuesday. |
| Bankgiro(SE) | 16:00 UTC | T+1, meaning if you submit the instruction before cut-off, the funds will leave the end-user’s account on day 2. Submitting it at 16:00 UTC on a Friday, means that the funds leave end-user account on Monday. Your account will also be credited on Monday. |
| SepaDD(€-zone) | 22:00 UTC | T+2, meaning if you submit the instruction before cut-off, the funds will leave the end-user’s account on day-2. Submitting it at 22:00 UTC on a Friday, means that the funds will leave the end-user account on Tuesday. Your virtual-account will also be credited the same day. |
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
Submission day - this is the day that the file with instructions are submitted into the scheme.
Instruction day - this is the day that bacs informs the debtor and creditor bank about the instruction
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.
Submission day
Instruction day
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.
Instruction day, informing debtor and creditor bank about the transfer
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.
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.
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.
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.
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. |
Missing blok resolver for blok type codeBlockGroup.{
"_uid": "i-7bacab41-ae75-4906-babb-0f811dcc5cc3",
"tabs": [
{
"_uid": "57733474-d99a-449f-acc3-ce16d04e94d6",
"code": {
"code": "{\n \"result\": {\n \"signature\": \"D5FjuMqf3H0Ku ... S16VbzR5v==\",\n \"uuid\": \"<the uuid for the notification received>\",\n \"method\": \"<the method of the notification>\",\n \"data\": {\n \"status\": \"OK\"\n }\n },\n \"version\":\"1.1\"\n}",
"title": "JSON",
"language": "JSON"
},
"component": "codeBlock"
}
]
}Below is a generic diagram on how direct debit works.
)