Unzer Direct Debit

Unzer Direct Debit lets you accept payments in euro.

About Unzer Direct Debit

Unzer Direct Debit lets you collect payments in euro, from customers located in the SEPA countries.

The customer fills the Direct Debit mandate that is later used by the merchant for receiving payments. On the due date, your bank sends the mandate to the customer’s bank to collect the payment. The customers enjoy many benefits such as

  • not missing payments
  • avoiding late payment charges
Recommendation
For better payment security and to avoid the risk of fraud and payment defaults, we suggest that you use Unzer Direct Debit Secured.

Accept an Unzer Direct Debit payment

To accept an Unzer Direct Debit payment, follow the steps below.

When testing, do not use real customer data. Use the test data prepared by Unzer.

You can also use the Java SDK for integration.

Step 1: Create a sepa-direct-debit resource

Make a POST call to /types/sepa-direct-debit, with the following parameters in the request body:

Parameter Required Type Default Description
iban Yes String / The customer’s IBAN.
POST https://api.unzer.com/v1/types/sepa-direct-debit/

Body:
{
    "iban": "DE89370400440532013000"
}
{
  "id": "s-ddg-2xpazkjwdh9q",
  "method": "sepa-direct-debit-secured",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "VN"
  },
  "iban": "DE89370400440532013000",
  "bic": "",
  "holder": ""
}
Property Type Description
id String The ID of the resource that you just created.
method String The payment method.
recurring Boolean Indicates if this is a recurring payment.
clientIp String The IP address of the device used for the payment.
countryCode String The country associated with clientIp, displayed in the ISO 3166-1 alpha-2 format.
iban String The customer’s IBAN.
bic String The customer BIC.
holder String The account holder’s name.

Step 2: Make a charges call

Make a POST call to payments/charges with the following parameters in the request body:

Parameter Required Type Default Description
amount Yes Number / The transaction amount
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format.
typeId Yes String / The newly-created payment type ID that you received in response to creating a sepa-direct-debit resource (Step 1).
POST https://api.unzer.com/v1/payments/charges
   
Body:
{
       "amount":       "12.4500",
       "currency":     "EUR",
       "resources": {
           "typeId":        "s-sdd-23ashaor54"
       }
}

In the sample response, note the processing node, which is unique to Unzer Direct Debit calls:

{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "customer": "Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "amount": "50.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "date": "2018-09-26 07:24:20",
    "resources": {
        "customerId": "s-cst-e769ddae5686",
        "paymentId": "s-pay-7375",
        "metadataId": "",
        "typeId": "s-sdd-ybmqxouxjguc"
    },
    "processing": {
        "creatorId": "13213213344324324",
        "identification": "4018.7305.9890",
        "iban": "DE8937************3000",
        "bic": "COBADEFFXXX",
        "uniqueId": "31HA07BC8137E7B23DE95C94B808D48D",
        "shortId": "4018.7305.9890"
    }
}
Property Type Description
id String The transaction’s unique ID.
isSuccess Boolean Set to true if the transaction was successful.
isPending Boolean Set to true if the transaction is pending
(e.g. if a redirect to an external system is required).
isError Boolean Set to true if an error occurs.
code String A unique ID of the message.

For details, go to Error code structure.
customer String Message displayed to the customer.
amount Number The transaction amount.
currency String The transaction currency, in the ISO 4217 alpha-3 format.
returnUrl String The URL to redirect the customer to after the payment is completed.
date String Date and time of the transaction.
customerId String The ID of the customers resource.
paymentId String The ID of the related payment resource.
metadataId String The ID of the related metadata resource.
typeId String The newly-created payment type ID that you received in response to creating a sepa-direct-debit resource (Step 1).
creatorId String The ID of the request creator.
identification String The identification number.
iban String The customer’s IBAN.
bic String The customer BIC.
uniqueId String The ID of the transaction process.
shortId String The short ID of the transaction process.

Implement the Unzer Direct Debit UI on your website

Web integration
Before implementing the Unzer Direct Debit UI on your website, read the web integration topic.

When implementing the Unzer Direct Debit UI on your website, you can choose from three different UI solutions:

  • A standard IBAN input field
  • An IBAN input field already filled with the customer’s data
  • A customer input form to be filled with the customer’s IBAN and personal data manually

After you complete all steps, your website displays a short payment form, like this:

Step 1: Load our JS script and CSS stylesheet

Include Unzer’s script and stylesheet on your website.

Always load the script and stylesheet directly from https://static.unzer.com:

<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>
Faster load time
To make your website load faster, insert the script at the bottom of your HTML document.

Step 2: Create a heidelpayInstance

Create a heidelpayInstance with your public key:

var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

Step 3: Create your HTML form

Create an HTML form, into which the Unzer Direct Debit UI will be inserted:

<form id="payment-form-sepa" class="heidelpayUI form" novalidate>
  <div id="sepa-IBAN" class="field">
    <!-- The IBAN field UI Element will be inserted here -->
  </div>
  <div class="field">
    <button class="heidelpayUI primary button fluid" type="submit">Pay</button>
  </div>
</form>
Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create an Unzer Direct Debit resource

To create a new Unzer Direct Debit resource, call the heidelpayInstance.SepaDirectDebit() method:

// Creating an Unzer Direct Debit instance
var Sepa = heidelpayInstance.SepaDirectDebit()
// Rendering the input field
Sepa.create('sepa-direct-debit', {
  containerId: 'sepa-IBAN'
});
The IDs must match
Make sure that the IDs in your HTML and JavaScript files match. For more information on how to create your HTML form correctly, go to web integration.

Step 5: Create your resource ID and submit the form

Add the code that handles the form submission. These are the actions the code sample below performs:

  1. Gets the form element by its ID.
  2. Adds an event listener to the submit button.
  3. Creates a Promise with .createResource and submits the form.
// SEPA JavaScript
// Handling the form's submission
var form = document.getElementById('payment-form-sepa')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Sepa.createResource()
    .then(function(data) {
    // Success
    })
    .catch(function(error) {
    // Error
    })
});

Step 6: Review the code

View the complete code samples that you can use to implement the Unzer Direct Debit UI on your website:

Make sure to import your own JavaScript and CSS files, as well as unzer.js and unzer.css.


<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>
<form id="payment-form-sepa" class="heidelpayUI form" novalidate>
  <div id="sepa-IBAN" class="field">
    <!-- The IBAN field UI Element will be inserted here -->
  </div>
  <div class="field">
    <button class="heidelpayUI primary button fluid" type="submit">Pay</button>
  </div>
</form>


// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an Unzer Direct Debit instance
var Sepa = heidelpayInstance.SepaDirectDebit()
// Rendering the input field
Sepa.create('sepa-direct-debit', {
  containerId: 'sepa-IBAN'
});
// Handling the form's submission
var form = document.getElementById('payment-form-sepa')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Sepa.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

Optional: Update an Unzer Direct Debit resource

You can update the value of an existing Unzer Direct Debit resource. The update process is very similar to creating a new Unzer Direct Debit resource, with the following differences:

  • You need to pass the resourceId when calling create().
  • At the end, you need to run updateResource() instead of createResource().

The HTML is the same as during the create resource process.

// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an Unzer Direct Debit instance
var Sepa = heidelpayInstance.SepaDirectDebit()
// Rendering the input field and passing the resourceId
Sepa.create('sepa-direct-debit', {
  containerId: 'sepa-IBAN',
  resourceId: 's-sdd-invoiceid', // ID of the resource you want to update
});
// Handling the form's submission
var form = document.getElementById('payment-form-sepa')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Sepa.updateResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

UI reference

Constructors

Constructor Description
heidelpay.SepaDirectDebit() Initializes an Unzer Direct Debit object.

Methods

Method Type Description Returns
create(type, options) Promise Creates an input field for the Unzer Direct Debit payment method specified by the type parameter. Additionally, you can pass different options as key-value pairs inside the options parameter. An object containing success or error details.
createResource() Promise Creates a Promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass). An object containing success or error details.

Success:
{id: String,
method: String,
iban: String}

Error:
{input: String,
message: String}
updateResource() Promise Creates a Promise and submits the new data from the form. If resolved, the old IBAN data is updated. An object containing success or error details.

Success:
{id: String,
method: String,
iban: String}

Error:
{input: String,
message: String}
create properties
Property Type Description
type String Specifies the type of input field to be created.

Valid value: sepa-direct-debit
options Object A JSON with various options for the created input field.
containerId String The HTML id of the DOM element, where the UI component will be inserted.
Example:
containerId: 'sepa-dd-element'
resourceId String The id of the created resource you wish to update. You need to pass the resourceId before before using the updateResource method.
createResource response properties
Property Type Description
id String The ID of the returned /types/sepa-direct-debit resource.
method String The chosen payment method.
iban String Masked value of the passed IBAN.
input String The input field where the error occurred.
message String An error message describing the error in more detail.
updateResource response properties
Property Type Description
id String The ID of the returned /types/sepa-direct-debit resource.
method String The chosen payment method.
iban String Masked value of the passed IBAN.
input String The input field where the error occurred.
message String An error message describing the error in more detail.

SEPA mandate

SEPA mandate
Make sure that the customer approves the SEPA mandate.

To make the customers approve the SEPA mandate, you need to display the mandate text on your website.

Below, you can find sample SEPA mandate texts in English and German:


By signing this mandate form, you authorise {NAME OF MERCHANT} to send instructions to your bank to debit your account and your bank to debit your account in accordance with the instructions from {NAME OF MERCHANT}.

Note: As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited. Your rights regarding this SEPA mandate are explained in a statement that you can obtain from your bank.

In case of refusal or rejection of direct debit payment I instruct my bank irrevocably to inform {NAME OF MERCHANT} or any third party upon request about my name, address and date of birth.


SEPA Lastschrift-Mandat (Bankeinzug)

Ich ermächtige {NAME OF MERCHANT}, Zahlungen von meinem Konto mittels SEPA Lastschrift einzuziehen. Zugleich weise ich mein Kreditinstitut an, die von {NAME OF MERCHANT} auf mein Konto gezogenen SEPA Lastschriften einzulösen.

Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrags verlangen. Es gelten dabei die mit meinem Kreditinstitut vereinbarten Bedingungen.

Für den Fall der Nichteinlösung der Lastschriften oder des Widerspruchs gegen die Lastschriften weise ich meine Bank unwiderruflich an, {NAME OF MERCHANT} oder Dritten auf Anforderung meinen Namen, Adresse und Geburtsdatum vollständig mitzuteilen.