Overview
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.
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.
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.
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 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:
data: {
...
"orderid":"3473567567",
"accountid":"1111111111",
"attributes":
{
"directdebitmandate":"0",
...
}
}
Example Activation notification:
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 supported 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.
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.
Notification example
{
"method": "cancel",
"params": {
"signature":"RI1PTmjTgr5Ig1p....AF7ejFUGxwKQ==",
"uuid": "258a2184-2842-b485-25ca-293525152425",
"data": {
"orderid":"3473567567",
"messageid":"453455465",
"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:
The reason for why a mandate was failed or cancelled can be found in the details.
Format for cancel notification detail:
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)