Unzer Direct Debit Secured

Unzer Direct Debit Secured lets you accept payments in euro and secures your money.

About Unzer Direct Debit Secured

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

With Unzer Direct Debit Secured, you get the money from the customer even if the bank account is invalid or the customer doesn’t have money on their bank account. All the risks are checked and managed by the insurance company.

Risk check
To enable risk checks, you need to provide a customer reference to the /payments/charges call. For more information, see linking a customer to a payment.

To let your customer use Unzer Direct Debit, follow the steps below.

Accept an Unzer Direct Debit Secured payment

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

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

Step 1: Create a sepa-direct-debit-secured resource

Make a POST call to /types/sepa-direct-debit-secured, 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-secured/

Body:
{
    "iban": "DE89370400440532013000"
}

{
  "id": "s-dds-2xpazkjwdh9q",
  "method": "sepa-direct-debit-secured",
  "recurring": false,
  "geoLocation": {
    "clientIp": "127.0.0.1",
    "countryCode": "DE"
  },
  "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: Create a customers resource

Unzer Direct Debit Secured requires additional information about the customer. The customers resource lets you easily submit this information within the payment.

For details on the customers resource, go to Customer.

To use an existing customers resource, add its unique customerId to the resources object in the request body, like this:

{
...
  "resources": {
    "customerId": "s-cst-1"
  },
...
}

To create a new customers resource, make a POST call with the following parameters in the request body:

Parameter Required Type Default Description Example
lastname Yes String / The customer’s last name. Mustermann
firstname Yes String / The customer’s first name. Max
salutation Yes String / The customer’s honorific. mr
company Yes String / The customer’s company name. unzer GmbH
customerId Yes String / The ID of the customers resource. 51222
birthDate Yes String / The customer’s date of birth. 1970-01-01
email Yes String / The customer’s email address. info@unzer.com
phone Yes String / The customer’s landline phone number. +49 6221 64 71 100
mobile Yes String / The customer’s mobile phone number. +49 172 123 456
name Yes String / The customer’s name, as used in the customer’s billing address. Max Mustermann
street Yes String / The billing address street name and house number. Musterstrasse 15
state Yes String / The billing address state. DE-BW
zip Yes String / The billing address postal code. 69115
city Yes String / The billing address city. Heidelberg
country Yes String / The billing address country. DE
POST https://api.unzer.com/v1/customers

Body:
{
  "lastname": "Mustermann",
  "firstname": "Max",
  "salutation": "mr",
  "company": "Unzer GmbH",
  "customerId": "51222",
  "birthDate": "1970-01-01",
  "email": "info@unzer.com",
  "phone": "+49 6221 64 71 100",
  "mobile": "+49 172 123 456",
  "billingAddress": {
    "name": "Max Mustermann",
    "street": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  }
}

To see all possible customers parameters, go to Customer.

{
    "id": "s-cst-0ab7c75d8e59"
}
Property Type Description
id String The ID of the customers resource that you just created.

Step 3: Make a charges call

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

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

In the example 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-dds-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-secured 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 Secured UI on your website

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

Overview

When implementing Unzer Direct Debit Secured, 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
Customer ID
You can only use Unzer Direct Debit Secured without a customer form if this customer already has a valid customerId.

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

https://heidelpay.github.io/heidelpayUIExamples/iframes/sepa.html

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 Unzer instance with your public key:


// Create a heidelpayInstance with your personal 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 Secured UI will be inserted:

<form id="payment-form-sepa-guaranteed" class="heidelpayUI form" novalidate>
  <div id="sepa-guaranteed-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 3: Create your payment method

You can use the code sample below to create the payment method. When editing it, remember the following:

  • You cannot change the sepa-direct-debit-secured parameter that is used to specify the type of input field.
  • You can change the other parameters, such as container IDs.
// Creating an Unzer Direct Debit Secured instance
var SepaGuaranteed = heidelpayInstance.SepaDirectDebitGuaranteed()
// Rendering the input field
SepaGuaranteed.create('sepa-direct-debit-secured', {
  containerId: 'sepa-guaranteed-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 form correctly, see web integration.

Step 4: 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.

// Unzer Direct Debit Secured JavaScript
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  SepaGuaranteed.createResource()
    .then(function(data) {
    // Success
    })
    .catch(function(error) {
    // Error
    })
});

Step 5: 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-guaranteed" class="heidelpayUI form" novalidate>
  <div id="sepa-guaranteed-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 Secured instance
var SepaGuaranteed = heidelpayInstance.SepaDirectDebitGuaranteed()
// Rendering the input field
SepaGuaranteed.create('sepa-direct-debit-secured', {
  containerId: 'sepa-guaranteed-IBAN'
});
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  SepaGuaranteed.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

Optional: Unzer Direct Debit Secured with customer form

If you want to integrate Unzer Direct Debit Secured with a customer form, you can find the instructions in Customer.

Optional: Update an Unzer Direct Debit Secured resource

You can update the value of an existing Unzer Direct Debit Secured resource. The update process is very similar to creating a new Unzer Direct Debit Secured 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 Secured instance
var SepaGuaranteed = heidelpayInstance.SepaDirectDebitGuaranteed()
// Rendering the input field
SepaGuaranteed.create('sepa-direct-debit-secured', {
  containerId: 'sepa-guaranteed-IBAN',
  resourceId: 's-dds-invoiceid', // ID of the resource you want to update
});
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  SepaGuaranteed.updateResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

UI reference

Constructors

Constructor Description
heidelpay.SepaDirectDebitGuaranteed() Initializes an Unzer Direct Debit Secured 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-guaranteed
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-guaranteed 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-guaranteed 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.