General
The e-Mandates service is used to create and modify electronic mandates for a merchant to use in a SEPA Direct Debit transaction. This service takes away the complexity of managing and creating your e-Mandates. The service is applicable for Dutch bank accounts only. This service is available for the B2C SEPA Direct Debit as well as the B2B SEPA Direct Debit.
Servicecodes and actions
For e-mandate, use the service code emandate. For e-mandate B2B, use the service code emandateb2b
The Emandate service supports the following actions: GetIssuerList, CreateMandate, GetStatus, ModifyMandate, CancelMandate. These are all data request calls, using the following endpoints: https://checkout.buckaroo.nl/json/DataRequest (for live) or https://testcheckout.buckaroo.nl/json/DataRequest (for testing).
Request
JSON gateway request
JSON
{
"Services": {
"ServiceList": [
{
"Name": "emandate",
"Action": "GetIssuerList",
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
DebtorBankId
string
|
This is the bank ID used to create a CreateMandate or ModifyMandate request. |
|
DebtorBankCountry
string
|
The country of the requested bank. |
|
DebtorBankName
string
|
The name of the bank that can be used to display to the consumer. |
JSON
{
"Key": "5414DEAAB1984AD49278126DC00AF837",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-08-03T08:57:14"
},
"RequiredAction": null,
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "issuer1_DebtorBankId",
"Value": "ABNANL2A"
},
{
"Name": "issuer1_DebtorBankName",
"Value": "ABN Amro Bank"
},
{
"Name": "issuer1_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer2_DebtorBankId",
"Value": "ASNBNL21"
},
{
"Name": "issuer2_DebtorBankName",
"Value": "ASN Bank"
},
{
"Name": "issuer2_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer3_DebtorBankId",
"Value": "INGBNL2A"
},
{
"Name": "issuer3_DebtorBankName",
"Value": "ING Bank"
},
{
"Name": "issuer3_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer4_DebtorBankId",
"Value": "KNABNL2H"
},
{
"Name": "issuer4_DebtorBankName",
"Value": "Knab"
},
{
"Name": "issuer4_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer5_DebtorBankId",
"Value": "RABONL2U"
},
{
"Name": "issuer5_DebtorBankName",
"Value": "Rabobank"
},
{
"Name": "issuer5_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer6_DebtorBankId",
"Value": "RBRBNL21"
},
{
"Name": "issuer6_DebtorBankName",
"Value": "RegioBank"
},
{
"Name": "issuer6_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer7_DebtorBankId",
"Value": "SNSBNL2A"
},
{
"Name": "issuer7_DebtorBankName",
"Value": "SNS Bank"
},
{
"Name": "issuer7_DebtorBankCountry",
"Value": "Nederland"
},
{
"Name": "issuer8_DebtorBankId",
"Value": "TRIONL2U"
},
{
"Name": "issuer8_DebtorBankName",
"Value": "Triodos Bank"
},
{
"Name": "issuer8_DebtorBankCountry",
"Value": "Nederland"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "emandate",
"IsTest": true,
"ConsumerMessage": null
}CreateMandate
This action creates an e-Mandate request and returns a URL where to the consumer can be redirected to approve the request.
Request
JSON gateway request
|
debtorbankid
string
|
The bank id of the consumer (BIC), the possible values can be retrieved with the GetIssuerList action. This information is required, but it is possible to let the customer fill it in on the Buckaroo checkout page. In that case, leave the debtorbankid parameter out and add the basic parameter "ContinueOnIncomplete" with a value of 1. |
|
debtorreference
string
|
Required
An ID that identifies the debtor to creditor, which is issued by the creditor. For example: a customer number/ID. Max. 35 characters. |
|
sequencetype
decimal
|
Required
Indicates type of eMandate: one-off or recurring direct debit. 0 = recurring, 1 = one off. |
|
purchaseid
string
|
Required
An ID that identifies the emandate with a purchase order. This will be shown in the emandate information of the customers' bank account. Max. 35 characters. |
|
mandateid
string
|
The mandateId or “mandate reference“ is the id used to perform the SEPA direct debit calls in the future. If not provided in the request, then Buckaroo will generate one and return in the response. If provided by merchant, then it has to start with a predetermined prefix. Go to plaza.buckaroo.nl -> abonnementen/subscriptions -> (simple) sepa direct debit -> click on the window that appears -> gegevens/credentials -> voorvoegsel mandaat/mandate prefix. |
|
language
string
|
Required
The consumer language code in lowercase letters. For example “nl”, not “NL” or “nl-NL”. This will be the language of the customer's bank page. |
|
emandatereason
string
|
A description of the (purpose) of the emandate. This will be shown in the emandate information of the customers' bank account. Max 70 characters. |
|
maxamount
decimal
|
This is the maximum amount per SEPA Direct Debit. Debtor can change this value during the authorization process. The (altered) value will be communicated in the push message to the Merchant. This parameter is for B2B only and required if that's the case. |
JSON
{
"Currency": "EUR",
"Services": {
"ServiceList": [
{
"Name": "emandate",
"Action": "CreateMandate",
"Parameters": [
{
"Name": "emandatereason",
"Value": "testing"
},
{
"Name": "sequencetype",
"Value": "1"
},
{
"Name": "purchaseid",
"Value": "purchaseid1234"
},
{
"Name": "debtorbankid",
"Value": "INGBNL2A"
},
{
"Name": "debtorreference",
"Value": "klant1234"
},
{
"Name": "language",
"Value": "nl"
},
{
"Name": "mandateid",
"Value": "02Q1234567890"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
The response contains a MandateID, that can be used as the MandateReference for (Simple) Sepa Direct Debits.
|
MandateId
string
|
The mandateId or “mandate reference” for the emandate, with this id you can retrieve the status from the GetStatus action and perform SEPA direct debit transactions. |
|
ErrorResponseMessage
string
|
The error response message, empty if no error has occurred. |
|
IsError
string
|
If an error has occurred. |
|
Accountname
string
|
Name of the bank account as it is registered at the bank. |
|
BankId
string
|
BIC code of the debtor’s bank. |
|
Iban
string
|
Debtor’s bank account number. |
|
OriginalMandateId
string
|
The mandateId or “mandate reference”. |
|
Reference
string
|
Reference ID that identifies the debtor to creditor, which is issued by the creditor. |
|
SignerName
string
|
Name of the person signing the eMandate. |
|
ValidationReference
string
|
The ValidationReference can be used in a (Simple) SEPA Direct Debit transaction as the Electronic Signature. It is advised to save this value somewhere. However, you can provide only the MandateId / MandateReference in your (Simple) SEPA Direct Debit request and Buckaroo will find the matching ValidationReference. Can be up to a maximum of 128 characters. |
|
Maxamount
decimal
|
The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount. |
JSON
{
"Key": "D9ED99F67C8D4BC8BC78E0BB9D16xxxx",
"Status": {
"Code": {
"Code": 791,
"Description": "Pending processing"
},
"SubCode": {
"Code": "S002",
"Description": "An additional action is required: RedirectToMandate"
},
"DateTime": "2018-12-19T12:08:30"
},
"RequiredAction": {
"RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=1208BEF39F63433CBD7394693A73xxx",
"RequestedInformation": null,
"Name": "Redirect",
"TypeDeprecated": 0
},
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "MandateId",
"Value": "02Q1234567890"
},
{
"Name": "IsError",
"Value": "False"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "emandate",
"IsTest": true,
"ConsumerMessage": {
"MustRead": false,
"CultureName": null,
"Title": null,
"PlainText": null,
"HtmlText": null
}
}Push
JSON push response
|
MandateId
string
|
The mandateId or “mandate reference“ is the id used to perform the SEPA direct debit calls in the future. |
|
IsError
string
|
If an error has occurred. |
|
EmandateStatus
string
|
Status of the emandate |
|
SignerName
string
|
Name of the person signing the eMandate. |
|
AccountName
string
|
Name of the bank account as it is registered at the bank. |
|
BankId
string
|
BIC code of the debtor’s bank. |
|
Iban
string
|
Debtor’s bank account number. |
|
Reference
string
|
Reference ID that identifies the debtor to creditor, which is issued by the creditor. |
|
ValidationReference
|
The ValidationReference can be used in a (Simple) SEPA Direct Debit transaction as the Electronic Signature. It is advised to save this value somewhere. However, you can provide only the MandateId / MandateReference in your (Simple) SEPA Direct Debit request and Buckaroo will find the matching ValidationReference. |
|
OriginalMandateId
string
|
The mandateId or “mandate reference”. |
|
MaxAmount
string
|
The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount. |
|
EmandateStatus
string
|
Status of the emandate |
JSON
{
"DataRequest": {
"Key": "D9ED99F67C8D4BC8BC78E0BB9D16xxxx",
"Invoice": null,
"ServiceCode": "emandate",
"ActionCode": "CreateMandate",
"Status": {
"Code": {
"Code": 190,
"Description": "Transactie succesvol uitgevoerd"
},
"SubCode": null,
"DateTime": "2018-12-19T12:09:09"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 0,
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "MandateId",
"Value": "02Q1234567890"
},
{
"Name": "IsError",
"Value": "False"
},
{
"Name": "EmandateStatus",
"Value": "Success"
},
{
"Name": "SignerName",
"Value": "J. de Tester"
},
{
"Name": "AccountName",
"Value": "J. de Tester"
},
{
"Name": "BankId",
"Value": "INGBNL2A"
},
{
"Name": "Iban",
"Value": "NL13TEST0123456789"
},
{
"Name": "Reference",
"Value": "klant1234"
},
{
"Name": "ValidationReference",
"Value": "TestValidation"
},
{
"Name": "OriginalMandateId",
"Value": "02Q1234567890"
},
{
"Name": "MaxAmount",
"Value": "0.00"
}
],
"VersionAsProperty": 1
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 0,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": null,
"PayerHash": null,
"PaymentKey": null
}
}GetStatus
This action returns the status of an e-Mandate. When the e-Mandate is successful, the response also contains the ValidationReference. The ValidationReference can be used in a (Simple) SEPA Direct Debit transaction as the Electronic Signature. It is advised to save this value somewhere. However, you can provide only the MandateId / MandateReference in your (Simple) SEPA Direct Debit request and Buckaroo will find the matching ValidationReference.
Request
JSON gateway request
|
mandateid
string
|
Required
The mandateId or “mandate reference“ is the id used to perform the SEPA direct debit calls in the future. |
JSON
{
"Services": {
"ServiceList": [
{
"Name": "emandate",
"Action": "GetStatus",
"Parameters": [
{
"Name": "mandateid",
"Value": "001234516BB5979412DB939BBE305D1xxxx"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
EmandateStatus
string
|
Status of emandate |
|
SignerName
string
|
Name of the person signing the eMandate. |
|
AccountName
string
|
Name of the bank account as it is registered at the bank. |
|
BankId
string
|
BIC code of the debtor’s bank. |
|
Iban
string
|
Debtor’s bank account number. |
|
Reference
string
|
Reference ID that identifies the debtor to creditor, which is issued by the creditor. |
|
ValidationReference
string
|
The ValidationReference can be used in a (Simple) SEPA Direct Debit transaction as the Electronic Signature. It is advised to save this value somewhere. However, you can provide only the MandateId / MandateReference in your (Simple) SEPA Direct Debit request and Buckaroo will find the matching ValidationReference. |
|
OriginalMandateId
string
|
The mandateId or “mandate reference”. |
|
MaxAmount
string
|
The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount. |
JSON
{
"Key": "BD6C0EF1CCF946C3AAB663CF2FAD1706",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-08-03T09:18:56"
},
"RequiredAction": null,
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "EmandateStatus",
"Value": "Success"
},
{
"Name": "SignerName",
"Value": "J. de Tester"
},
{
"Name": "AccountName",
"Value": "J. de Tester"
},
{
"Name": "BankId",
"Value": "TESTNL2A"
},
{
"Name": "Iban",
"Value": "NL13TEST0123456789"
},
{
"Name": "Reference",
"Value": "klant1234"
},
{
"Name": "ValidationReference",
"Value": "TestValidation"
},
{
"Name": "OriginalMandateId",
"Value": "001234516BB5979412DB939BBE305D1xxxx"
},
{
"Name": "MaxAmount",
"Value": "0.00"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "emandate",
"IsTest": true,
"ConsumerMessage": null
}ModifyMandate
This action can be used to modify a Customers’ E-mandate. You can change the customers’ bank account number without the need for a new e-Mandate.
Request
JSON gateway request
|
originalmandateid
string
|
Required
The mandateId or “mandate reference” of the original e-Mandate. This will not change after a successful amendment |
|
debtorbankid
string
|
BIC code of the customer's bank. |
JSON
{
"Currency": "EUR",
"Services": {
"ServiceList": [
{
"Name": "Emandate",
"Action": "ModifyMandate",
"Parameters": [
{
"Name": "OriginalMandateId",
"Value": "02QD7689C4575724CFFA5D71E1F9E38xxxx"
},
{
"Name": "Debtorbankid",
"Value": "ABNANL2A"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
The response contains a redirect URL that can be used to redirect the customer to the online environment where the request can be approved and completed.
|
MandateId
string
|
The mandateId or “mandate reference”, with this id you can retrieve the status from the GetStatus action and perform SEPA direct debit transactions |
|
IsError
string
|
If an error has occurred |
JSON
{
"Key": "A92C2228C65840D496107DE20B79xxxx",
"Status": {
"Code": {
"Code": 791,
"Description": "Pending processing"
},
"SubCode": {
"Code": "S002",
"Description": "An additional action is required: RedirectToModifyMandate"
},
"DateTime": "2018-12-19T11:59:03"
},
"RequiredAction": {
"RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=3E620DBD2F5D485386C8FEF856BCxxxx",
"RequestedInformation": null,
"Name": "Redirect",
"TypeDeprecated": 0
},
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "IsError",
"Value": "False"
},
{
"Name": "MandateId",
"Value": "02QD7689C4575724CFFA5D71E1F9E38xxxx"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "emandate",
"IsTest": true,
"ConsumerMessage": {
"MustRead": false,
"CultureName": null,
"Title": null,
"PlainText": null,
"HtmlText": null
}
}Push
JSON push response
|
EmandateStatus
string
|
Status of the e-mandate |
|
MandateId
string
|
The mandateId or “mandate reference”, with this id you can retrieve the status from the GetStatus action and perform SEPA direct debit transactions |
|
ErrorResponseMessage
string
|
The error response message, empty if no error has occurred |
|
IsError
string
|
If an error has occurred |
|
Accountname
string
|
Name of the bank account as it is registered at the bank |
|
BankId
|
BIC code of the debtor’s bank |
|
Iban
string
|
Debtor’s bank account number |
|
OriginalMandateId
string
|
The mandateId or “mandate reference” |
|
Reference
string
|
Reference ID that identifies the debtor to creditor, which is issued by the creditor |
|
SignerName
|
Name of the person signing the eMandate |
|
ValidationReference
string
|
The ValidationReference can be used in a (Simple) SEPA Direct Debit transaction as the Electronic Signature. It is advised to save this value somewhere. However, you can provide only the MandateId / MandateReference in your (Simple) SEPA Direct Debit request and Buckaroo will find the matching ValidationReference. |
|
Maxamount
decimal
|
The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount and is for B2B only |
JSON
{
"DataRequest": {
"Key": "A92C2228C65840D496107DE20B79xxxx",
"Invoice": null,
"ServiceCode": "emandate",
"ActionCode": "ModifyMandate",
"Status": {
"Code": {
"Code": 190,
"Description": "Transactie succesvol uitgevoerd"
},
"SubCode": null,
"DateTime": "2018-12-19T11:59:06"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 0,
"Services": [
{
"Name": "emandate",
"Action": null,
"Parameters": [
{
"Name": "IsError",
"Value": "False"
},
{
"Name": "MandateId",
"Value": "02QD7689C4575724CFFA5D71E1F9E38xxxx"
},
{
"Name": "EmandateStatus",
"Value": "Success"
},
{
"Name": "SignerName",
"Value": "J. de Tester"
},
{
"Name": "AccountName",
"Value": "J. de Tester"
},
{
"Name": "BankId",
"Value": "abnanl2a"
},
{
"Name": "Iban",
"Value": "NL13TEST0123456789"
},
{
"Name": "Reference",
"Value": "klant1234"
},
{
"Name": "ValidationReference",
"Value": "TestValidation"
},
{
"Name": "OriginalMandateId",
"Value": "02QD7689C4575724CFFA5D71E1F9E38xxxx"
},
{
"Name": "MaxAmount",
"Value": "0.00"
}
],
"VersionAsProperty": 1
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 0,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": null,
"PayerHash": null,
"PaymentKey": null
}
}CancelMandate
This action can be used to cancel a business E-mandate. This option is only available for the b2b service. In that case the Mandate can be blocked by the settings within the online banking environment of the consumer. Please note that you are legally required to offer this to your customers when you are making use of B2B e-mandates. Furthermore, the debtor has the option of canceling the mandate in his bank environment anyways. If you offer the option on your own website, you get the benefit of knowing when the customer cancels the mandate.
Request
JSON gateway request
|
MandateId
string
|
Required
The mandateId or “mandate reference” of the original e-Mandate. |
|
Purchaseid
string
|
Required
An ID that identifies the emandate with a purchase order. This will be shown in the emandate information of the customers' bank account. Max. 35 characters. |
JSON
{
"Currency": "EUR",
"Services": {
"ServiceList": [
{
"Name": "emandateb2b",
"Action": "CancelMandate",
"Parameters": [
{
"Name": "mandateid",
"Value": "00122B82DA08C5F41A4B3A01B8EEF35xxxx"
},
{
"Name": "Emandatereason",
"Value": "test cancellation"
},
{
"Name": "Purchaseid",
"Value": "purchaseid 123"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
|
MandateId
string
|
The mandateId or “mandate reference” |
|
ErrorResponseMessage
string
|
The error response message, empty if no error has occurred |
|
IsError
string
|
If an error has occurred |
JSON
{
"Key": "CC821C9C83E84AE9AB261B436713FD3D",
"Status": {
"Code": {
"Code": 791,
"Description": "Pending processing"
},
"SubCode": {
"Code": "S002",
"Description": "An additional action is required: RedirectToCancelMandate"
},
"DateTime": "2017-08-03T17:27:18"
},
"RequiredAction": {
"RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=C62C997A6AE3456AA04E32C8CA66xxxx",
"RequestedInformation": null,
"Name": "Redirect",
"TypeDeprecated": 0
},
"Services": [
{
"Name": "emandateb2b",
"Action": null,
"Parameters": [
{
"Name": "IsError",
"Value": "False"
},
{
"Name": "MandateId",
"Value": "00122B82DA08C5F41A4B3A01B8EEF35xxxx"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "emandateb2b",
"IsTest": true,
"ConsumerMessage": {
"MustRead": false,
"CultureName": null,
"Title": null,
"PlainText": null,
"HtmlText": null
}
}Push
JSON push response
|
MandateId
string
|
The mandateId or “mandate reference” |
|
ErrorResponseMessage
string
|
The error response message, empty if no error has occurred |
|
IsError
string
|
If an error has occurred |
JSON
{
"DataRequest": {
"Key": "CC821C9C83E84AE9AB261B436713xxxx",
"Invoice": null,
"ServiceCode": "emandateb2b",
"ActionCode": "CancelMandate",
"Status": {
"Code": {
"Code": 190,
"Description": "Transaction successfully processed"
},
"SubCode": null,
"DateTime": "2017-08-03T17:28:34+02:00"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 0,
"Services": [
{
"Name": "emandateb2b",
"Action": null,
"Parameters": [
{
"Name": "IsError",
"Value": "False"
},
{
"Name": "MandateId",
"Value": "00122B82DA08C5F41A4B3A01B8EEF35xxxx"
},
{
"Name": "EmandateStatus",
"Value": "Cancelled"
}
],
"VersionAsProperty": 1
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 0,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": null,
"PayerHash": null,
"PaymentKey": null
}
}