Customer UI components

Use customer form provided by Unzer in your online shopping solution.

Overview

Customer UI components are ready-made forms provided by Unzer that allow you to gather information required by some of our payment methods: Direct Debit Secured, Unzer Invoice, Unzer Installment. If you don’t have information about the customer (and accompanying customerId) to pass onto the transaction, or you want to update information about the already existing customer, you can use one of the customer UI components.

Read this guide to learn how to use the customer UI components, and check our demo page to see the customer UI components in action.

Although it’s possible to use customer UI components on their own, we recommend using it together with the UI component for one of the payment methods mentioned above.

Before you begin

Familiarize yourself with general guide on integrating using UI components.
We recommend that you already have one of the payment methods integrated on your website - the customer form is merely an addition to it.

Step 1: Create Unzer instance and insert the customer form

Create an unzer instance with your public key:

// Creating an unzer instance with your public key
let unzerInstance = new unzer('s-pub-xxxxxxxxxx');

We recommend adding the customer form inside your payment form and placing it between the payment element and the submit button, or above the payment elements, in case of Unzer Invoice.

<form id="payment-form" class="unzerUI form">
  <div id="example-your-payment-method" class="field">
    <!-- ... The Payment form UI elements will be inserted here -->
  </div>

  <div id="customer" class="field">
    <!-- The customer form UI element will be inserted here -->
  </div>

  <div id="error-holder" class="field" style="color: #9f3a38">
    <!-- Errors will be inserted here -->
  </div>
  <button class="unzerUI primary button fluid" id="submit-button" type="submit">
    Pay
  </button>
</form>

Step 2: Create a customer instance and render the form

A customer instance is created like any other UI component. In Order to render the customer form, you will need to call either create() or update() method. In case you wish to initialize the form with the data of an already created customer, you will need to call the initFormFields() function. This has to be done before the update() call.

// Creating a customer instance
let customer = unzerInstance.Customer()
// Rendering the customer form
customer.create({
  containerId: 'customer',
  errorHolderId: 'error-holder'
})

// Creating a customer instance
let customer = unzerInstance.Customer()

// Initialize customer form with existing customer data
customer.initFormFields({
  "lastname": "Universum",
  "firstname": "Peter",
  "salutation": "mr",
  "birthDate": "1987-12-20",
  "address": {
    "street": "Hugo-Junkers-Str. 5",
    "state": "DE-BO",
    "zip": "60386",
    "city": "Frankfurt am Main",
    "country": "DE"
  },
  "shippingAddress": {
    "street": "Hugo-Junkers-Str. 5",
    "state": "DE-BO",
    "zip": "60386",
    "city": "Frankfurt am Main",
    "country": "DE"
  }
})

// Call the update method that will initialize the form with existing customer data
// You need to pass the customerId and an options object as parameter.
// The containerId has to be set within the options object
customer.update('s-cst-7f0910d26396', {
    containerId: 'customer',
})

Step 3: Handling the form’s submission

Customer form with payment

Usually you want to use the customer form with a payment method. In that case, you will create promises for both payment type and customer resources and handle them with Promise.all(). Below, you can see examples for Direct Debit Secured and Unzer Invoice payment types.

// Inside your event handler
let paymentTypePromise = paymentMethod.createResource()
let customerPromise = customer.createCustomer()
Promise.all([paymentTypePromise, customerPromise])
    .then(function(values) {
      // Success
    })
    .catch(function(error) {
      // Error
    })

// Inside your event handler
let paymentTypePromise = paymentMethod.createResource()
let customerPromise = customer.updateCustomer()
Promise.all([paymentTypePromise, customerPromise])
    .then(function(values) {
      // Success
    })
    .catch(function(error) {
      // Error
    })

In the example, paymentTypePromise and customerPromise were created to temporarily store the individual promises.

When creating the promises, be sure to use the following methods:

createResource() for the PaymentType
createCustomer() for the Customer resource creation
updateCustomer() for the Customer resource update

After that, you can simply handle both promises with Promise.all() and the recently created variables as parameter list.

Optionally, you can add a custom event listener that sends the validation result of all input fields

Customer form only

Although we recommend using the customer form in addition to a payment method, it is possible to submit it on its own. This works just like with every other resource, except for the method signature. Instead of createResource() you need to write createCustomer() or updateCustomer().

// Inside your form event handler:
customer.createCustomer()
  .then(function(data) {
    // Handle success
  })
  .catch(function(error) {
    // Handle the error
  })

// Inside your form event handler:
customer.updateCustomer()
  .then(function(data) {
    // Handle success
  })
  .catch(function(error) {
    // Handle the error
  })

Both createCustomer() and updateCustomer() create a promise which has to be handled with then() and catch() as shown above.

Optionally, you can add a custom event listener that sends the validation result of all input fields

customer.addEventListener('validate', function(e) {
  if (e.success) {
    // run some code (for example, enable the `pay` button)
    document.getElementById('submit-button').removeAttribute('disabled')
  } else {
    // run some code (for example, disable the `pay` button)
    document.getElementById('submit-button').setAttribute('disabled', 'disabled');
  }
})

Examples

Here you can find complete examples for Direct Debit Secured and Unzer Invoice UI component integration with a customer form.

Reminder: Unzer provides you with a customer form, in case you don’t have customer data already in your shopping solution, or if you want to update your customer information. Sending customer information with the transaction is optional, except when you want to integrate one of the payment methods mentioned in the overview section.

Don’t forget to include unzer.js and unzer.css on your website before you start creating payment forms.

Direct Debit Secured with customer create form

<form id="payment-form" class="unzerUI form" novalidate>
  <div id="example-paylater-direct-debit" class="field">
    <!-- The IBAN field UI Element will be inserted here -->
  </div>
  <div id="customer" class="field">
    <!-- The customer form UI Element will be inserted here -->
  </div>
  <div class="field">
    <button class="unzerUI primary button fluid" type="submit">Pay</button>
  </div>
</form>

// Creating an Unzer instance with your public key
let unzerInstance = new unzer('s-pub-xxxxxxxxxx');
// Creating an Direct Debit Secured instance
let paylaterDirectDebit = unzerInstance.PaylaterDirectDebit()
// Rendering the input field
paylaterDirectDebit.create('paylater-direct-debit', {
  containerId: 'example-paylater-direct-debit'
});
// Creating a customer instance
let customer = unzerInstance.Customer()
// Rendering the customer form
customer.create({
  containerId: 'customer'
})
// Handling the form's submission
let form = document.getElementById('payment-form')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  let paylaterDirectDebitPromise = paylaterDirectDebit.createResource()
  let customerPromise = customer.createCustomer()
  Promise.all([paylaterDirectDebitPromise, customerPromise])
    .then(function(values) {
    // Success
  })
    .catch(function(error) {
    // Error
  })
});

For a complete guide on integrating this payment method, see Accept Direct Debit Secured with UI components

Unzer Invoice with customer create form

<form id="payment-form-paylater-invoice" class="unzerUI form>
  <div id="customer" class="field">
    <!-- The customer form UI element will be inserted here -->
  </div>
  <div id="example-paylater-invoice">
    <!-- ... The Payment form UI element, will be inserted here -->
  </div>
  <div class="field">
    <button class="unzerUI primary button fluid" type="submit">Pay</button>
  </div>
</form>

// Creating an Unzer instance with your public key
let unzerInstance = new unzer('s-pub-xxxxxxxxxx');
// Creating an Unzer Invoice instance
let paylaterInvoice = unzerInstance.PaylaterInvoice()
// Creating a customer instance
let customer = unzerInstance.Customer()
// Rendering the customer form
customer.create({
  containerId: 'customer',
  paymentTypeName: 'paylater-invoice'
})
// Rendering the Unzer Invoice payment form
paylaterInvoice.create({
  containerId: 'example-paylater-invoice',
  customerType: 'B2C'
})

// Handle customer and Unzer Invoice form validation
let isValidCustomer = false;
let isValidPaylaterInvoice = false;

paylaterInvoice.addEventListener('change', function eventHandlerResource(e) {
  if (e.success) {
    isValidPaylaterInvoice = true;
    if (isValidCustomer) {
      document.getElementById('submit-button').removeAttribute('disabled')
    }
  } else {
    isValidPaylaterInvoice = false;
    document.getElementById('submit-button').setAttribute('disabled', 'disabled');
  }
})

customer.addEventListener('validate', function(e) {
  if (e.success) {
    isValidCustomer = true;
    if (isValidPaylaterInvoice) {
      document.getElementById('submit-button').removeAttribute('disabled')
    }
  } else {
    document.getElementById('submit-button').setAttribute('disabled', 'disabled');
    isValidCustomer = false;
  }
})

// Handle payment form submission
let form = document.getElementById('payment-form-paylater-invoice');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  let paylaterInvoicePromise = paylaterInvoice.createResource()
  let customerPromise = customer.createCustomer()
  Promise.all([paylaterInvoicePromise, customerPromise])
    .then(function(values) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

For a complete guide on integrating this payment method, see Accept Unzer Invoice with UI components.

Direct Debit Secured with customer update form

You will need to set the customerId you pass into Customer.update() method yourself.

<form id="payment-form" class="unzerUI form>
  <div id="example-paylater-direct-debit" class="field">
    <!-- The IBAN field UI Element will be inserted here -->
  </div>
  <div id="customer" class="field">
    <!-- The customer form UI Element will be inserted here -->
  </div>
  <div class="field">
    <button class="unzerUI primary button fluid" type="submit">Pay</button>
  </div>
</form>

// Create an Unzer instance with your public key
let unzerInstance = new unzer('s-pub-xxxxxxxxxx');

// Create an Direct Debit Secured instance
let paylaterDirectDebit = unzerInstance.PaylaterDirectDebit()

// Rendering the input field
paylaterDirectDebit.create('paylater-direct-debit', {
  containerId: 'example-paylater-direct-debit'
});

// Creating a customer instance
let customer = unzerInstance.Customer()

// If you want to limit the fields that can be updated you can select one or more of the following
// field-groups in the option `fields`: 'name', 'address', 'birthdate'.
let options = {
  containerId: 'customer',
  fields: ['birthdate'], // optional
  infoBoxText: 'Your birthdate data', // optional
  showHeader: false, // optional
}
// Rendering the customer update form with birthday field only
customer.update('s-cst-79b8zf879pp3', options);

// Handling the form's submission
let form = document.getElementById('payment-form')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  let paylaterDirectDebitPromise = paylaterDirectDebit.createResource()
  let customerPromise = customer.updateCustomer()
  Promise.all([paylaterDirectDebitPromise, customerPromise])
    .then(function(values) {
    // Success
  })
    .catch(function(error) {
    // Error
  })
});

For a complete guide on integrating this payment method, see Accept Direct Debit Secured with UI components

Unzer Invoice with customer update form

You will need to set the customerId you pass into Customer.update() method yourself.

<form id="payment-form-paylater-invoice" class="unzerUI form>
  <div id="customer" class="field">
    <!-- The customer form UI element will be inserted here -->
  </div>
  <div id="example-paylater-invoice">
    <!-- ... The Payment form UI element, if any, will be inserted here -->
  </div>
  <div id="error-holder" class="field" style="color: #9f3a38">
    <!-- Errors will be inserted here -->
  </div>
  <div class="field">
    <button class="unzerUI primary button fluid" type="submit">Pay</button>
  </div>
</form>

// Creating an Unzer instance with your public key
let unzerInstance = new unzer('s-pub-xxxxxxxxxx');
// Creating an Unzer Invoice instance
let paylaterInvoice = unzerInstance.PaylaterInvoice()
// Creating a customer instance
let customer = unzerInstance.Customer()
// If you want to limit the fields that can be updated you can select one or more of the following
// field-groups in the option `fields`: 'name', 'address', 'birthdate'.
let options = {
  containerId: 'customer',
  fields: ['birthdate'], // optional
  infoBoxText: 'Your birthdate data', // optional
  showHeader: false, // optional
}
// Rendering the Unzer Invoice payment form
paylaterInvoice.create({
  containerId: 'example-paylater-invoice',
  customerType: 'B2C',
  errorHolderId: 'error-holder',
})
// Handle payment form submission
let form = document.getElementById('payment-form-paylater-invoice');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  let paylaterInvoicePromise = paylaterInvoice.createResource()
  let customerPromise = customer.updateCustomer();
  Promise.all([paylaterInvoicePromise, customerPromise])
          .then(function(values) {
            let typeId = values[0].id;
            let customerId = values[1].id;
            // Submit the IDs to your server-side integration.
          })
          .catch(function(error) {
            document.getElementById('error-holder').innerText = error.customerMessage || error.message || 'Error'
          })
});

// Call the update method that will initialize the form with existing customer data
// You need to pass the customerId, and the containerId
customer.update('s-cst-7f0910d26396', {
  containerId: 'customer',
})

For a complete guide on integrating this payment method, see Accept Unzer Invoice with UI components

Code reference

Constructor function

unzerInstance.Customer()

Initializes the customer object.

initFormFields function

void initFormFields(Object customer)

If there is an existing customer data, it is possible to initialize the form fields with this data on creation. This data must be called before the create() or update() function.

Parameter	Type	Description
`customer`	`Object`	An existing customer object in JSON format.

Customer object

Parameter	Type	Description	Default value
`firstname`	`String`	The first name of the customer.	`""`
`lastname`	`String`	The last name of the customer.	`""`
`birthDate`	`String`	The birth date of the customer.	`""`
`salutation`	`String`	The salutation for the customer.	`"mr"`
`address`	`address object`	The billing address for the customer in JSON format.	`{}`
`shippingAddress`	`address object`	The shipping address for the customer in JSON format.	`{}`

address object

Parameter	Type	Description	Default value
`state`	`String`	The state	`""`
`street`	`String`	The street and house number	`""`
`zip`	`String`	The zip-code	`""`
`city`	`String`	The city	`""`
`country`	`String`	The country ISO country code ISO 3166 ALPHA-2	`"DE"`

create function

void create(Object options)

Creates an input form for customer data. You can pass additional options as key value pairs inside the options parameter.

Parameter	Type	Description
`options`	`Object`	A JSON object with various options (see details in the following section)

options object

Parameter	Type	Description	Default value
`containerId` required	`String`	The HTML ID of the DOM element, where the UI component will be inserted. Example: `containerId: 'card-element-id-number'`	-
`showInfoBox`	`Boolean`	Displays a small info box above the input form.	`true`
`infoBoxText`	`String`	The text inside the info box.	`"Your address data for the credit check:"`
`showHeader`	`Boolean`	Small headers for the “personal data” and “address” sections of the input form.	`true`
`headerPersonalDataText`	`String`	The text of the personal data heading.	`“PERSONAL DATA“`
`headerAddressText`	`String`	The text of the address heading.	`“ADDRESS”`
`externalCustomerId`	`String`	The customer ID that you are already using in your system. This can save you the effort of saving the customer ID provided by Unzer in your database.	`""`
`paymentTypeName`	`String`	Allows rendering a specialized customer form for some payment types (e.g `paylater-invoice` or `klarna`).	`""`
`differentBillingAddress`	`Boolean`	Displays the `different billing address` checkbox	`false` except when `paymentTypeName` = `paylater-invoice` or `klarna`, then it defaults to `true`

update function

void update(String customerId, Object options)

Creates an input form for updating customer data. You should pass customerId and additional options as key value pairs inside the options parameter

Parameter	Type	Description
`customerId` required	`String`	A string representing the ID of the customer you wish to update.
`options` required	`Object`	An object with various options.

options object

Parameter	Type	Description	Default value
`containerId` required	`String`	The HTML ID of the DOM element, where the UI component will be inserted. Example: `containerId: 'card-element-id-number'`	-
`fields`	`Array`	An array of items you want to update. It accepts strings: `birthdate`, `name` and `address`	`null`
`showInfoBox`	`Boolean`	Displays a small info box above the input form.	`true`
`infoBoxText`	`String`	The text inside the info box.
`showHeader`	`Boolean`	Small headers for the “personal data” and “address” sections of the input form.	`true`
`headerPersonalDataText`	`String`	The text of the “personal data” heading.
`headerAddressText`	`String`	The text of the “address” heading.
`horizontalDivider`	`Boolean`	Displays horizontal dividers between personal and address data. “personal data” and “address” headers will not be shown in this case.	`false`
`paymentTypeName`	`String`	Allows rendering a specialized customer form for some payment types (e.g `paylater-invoice` or `klarna`).	`""`
`differentBillingAddress`	`Boolean`	Displays the `different billing address` checkbox	`false` except when `paymentTypeName` = `paylater-invoice` or `klarna`, then it defaults to `true`. If `fields` parameter is passed and does not contain `address`, then `differentBillingAddress` will be ignored

`createCustomer` function

Object createCustomer()

Creates a promise and submits the (customer) form data. A customer resource is created at the Unzer API.
In both success and error case, an object is returned.

Returns an object with the following structure:

Success: {id: String}
Error: {message: String}

Parameter	Type	Description
`id`	`String`	The ID of the created customer resource.
`message`	`String`	The error message to be shown to the customer.

`updateCustomer` function

Object updateCustomer()

Creates a promise and submits the customer form data. If it resolves (validation passed), it updates the customer resource in the Unzer API. In both success and error case an object is returned.

Returns an object with the following structure:

Success: {id: String}
Error: {message: String}

Parameter	Type	Description
`id`	`String`	The ID of the updated customer resource.
`message`	`String`	The error message to be shown to the customer.