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).

GetIssuerList

This action returns the list of available banks that can be used by the consumer.

View in playground

Request


JSON gateway request

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "emandate",
            "Action": "GetIssuerList",
         }
      ]
   }
}

Response


JSON gateway response

DebtorBankId

This is the bank ID used to create a CreateMandate or ModifyMandate request.

DebtorBankCountry

The country of the requested bank.

DebtorBankName

The name of the bank that can be used to display to the consumer.

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

debtorbankid

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
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
Required

Indicates type of eMandate: one-off or recurring direct debit. 0 = recurring, 1 = one off.

purchaseid
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

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
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

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

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

copy
{
   "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


JSON gateway response

The response contains a MandateID, that can be used as the MandateReference for (Simple) Sepa Direct Debits.

MandateId

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

The error response message, empty if no error has occurred.

IsError

If an error has occurred.

Accountname

Name of the bank account as it is registered at the bank.

BankId

BIC code of the debtor’s bank.

Iban

Debtor’s bank account number.

OriginalMandateId

The mandateId or “mandate reference”.

Reference

Reference ID that identifies the debtor to creditor, which is issued by the creditor.

SignerName

Name of the person signing the eMandate.

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. Can be up to a maximum of 128 characters.

Maxamount

The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount.

JSON

copy
{
   "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

The mandateId or “mandate reference“ is the id used to perform the SEPA direct debit calls in the future.

IsError

If an error has occurred.

EmandateStatus

Status of the emandate

SignerName

Name of the person signing the eMandate.

AccountName

Name of the bank account as it is registered at the bank.

BankId

BIC code of the debtor’s bank.

Iban

Debtor’s bank account number.

Reference

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

The mandateId or “mandate reference”.

MaxAmount

The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount.

EmandateStatus

Status of the emandate

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

mandateid
Required

The mandateId or “mandate reference“ is the id used to perform the SEPA direct debit calls in the future.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "emandate",
            "Action": "GetStatus",
            "Parameters": [
               {
                  "Name": "mandateid",
                  "Value": "001234516BB5979412DB939BBE305D1xxxx"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

EmandateStatus

Status of emandate

SignerName

Name of the person signing the eMandate.

AccountName

Name of the bank account as it is registered at the bank.

BankId

BIC code of the debtor’s bank.

Iban

Debtor’s bank account number.

Reference

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

The mandateId or “mandate reference”.

MaxAmount

The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount.

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

originalmandateid
Required

The mandateId or “mandate reference” of the original e-Mandate. This will not change after a successful amendment

debtorbankid

BIC code of the customer's bank.

JSON

copy
{
   "Currency": "EUR",
   "Services": {
      "ServiceList": [
         {
            "Name": "Emandate",
            "Action": "ModifyMandate",
            "Parameters": [
               {
                  "Name": "OriginalMandateId",
                  "Value": "02QD7689C4575724CFFA5D71E1F9E38xxxx"
               },
               {
                  "Name": "Debtorbankid",
                  "Value": "ABNANL2A"
               }
            ]
         }
      ]
   }
}

Response


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

The mandateId or “mandate reference”, with this id you can retrieve the status from the GetStatus action and perform SEPA direct debit transactions

IsError

If an error has occurred

JSON

copy
{
   "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

Status of the e-mandate

MandateId

The mandateId or “mandate reference”, with this id you can retrieve the status from the GetStatus action and perform SEPA direct debit transactions

ErrorResponseMessage

The error response message, empty if no error has occurred

IsError

If an error has occurred

Accountname

Name of the bank account as it is registered at the bank

BankId

BIC code of the debtor’s bank

Iban

Debtor’s bank account number

OriginalMandateId

The mandateId or “mandate reference”

Reference

Reference ID that identifies the debtor to creditor, which is issued by the creditor

SignerName

Name of the person signing the eMandate

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.

Maxamount

The authorized maximum amount for a SEPA Direct Debit. This amount can be different from the requested amount and is for B2B only

JSON

copy
{
   "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.

View in playground

Request


JSON gateway request

MandateId
Required

The mandateId or “mandate reference” of the original e-Mandate.

Purchaseid
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

copy
{
   "Currency": "EUR",
   "Services": {
      "ServiceList": [
         {
            "Name": "emandateb2b",
            "Action": "CancelMandate",
            "Parameters": [
               {
                  "Name": "mandateid",
                  "Value": "00122B82DA08C5F41A4B3A01B8EEF35xxxx"
               },
               {
                  "Name": "Emandatereason",
                  "Value": "test cancellation"
               },
               {
                  "Name": "Purchaseid",
                  "Value": "purchaseid 123"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

MandateId

The mandateId or “mandate reference”

ErrorResponseMessage

The error response message, empty if no error has occurred

IsError

If an error has occurred

JSON

copy
{
   "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

The mandateId or “mandate reference”

ErrorResponseMessage

The error response message, empty if no error has occurred

IsError

If an error has occurred

JSON

copy
{
   "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
   }
}