Customer UI components

New

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

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: Insert the customer form

Insert Unzer UI customer elements:

Customer element	Description
`<unzer-shipping-address>`	Adds the customer shipping address information (email, salutation, first name, last name, country, street, post code, city, mobile number).
`<unzer-billing-address>`	Adds the customer billing address information (first name, last name, country, street, post code, city).

The Unzer UI customer elements can be inserted either inside or outside the <unzer-payment> element. On submit, all data from the added Unzer UI customer elements will be gathered and submitted together with the payment form, in order to create the customer and payment type resources.

In case you wish to initialize the customer elements with the data of an already created customer, you will need to call the setCustomerData() function of the <unzer-payment> element, and pass a customer object in JSON format.

customer object

Parameter	Type	Description	Default value
`id`	`String`	The ID of the customer you wish to update. If not passed, then a new customer will be created.
`salutation`	`String`	The salutation for the customer. Allowed values are: `"mr"`, `"mrs"`, `"diverse"`	`"mr"`
`firstname`	`String`	The first name of the customer.	`""`
`lastname`	`String`	The last name of the customer.	`""`
`birthDate`	`String`	The birth date of the customer.	`""`
`email`	`String`	The email of the customer.	`""`
`mobileNumber`	`mobileNumber Object`	The mobile number.	`{}`
`shippingAddress`	`address object`	The shipping address for the customer in JSON format.	`{}`
`billingAddress`	`address object`	The billing address for the customer in JSON format.	`{}`
`customerSettings`	`customerSettings object`	The customerSettings is to define the customer type.	`{}`

address object

Parameter	Type	Description	Default value
`name`	`String`	The first name + last name of the customer.	`""`
`street`	`String`	The street and house number.	`""`
`zip`	`String`	The zip-code.	`""`
`city`	`String`	The city.	`""`
`state`	`String`	The state.	`""`
`country`	`String`	The country ISO country code ISO 3166 ALPHA-2.	`"DE"`
`shippingType` only in `shippingAddress`	`String`	The shippingType. Allowed values are: `"equals-billing"`, `"different-address"`, `"branch-pickup"`, `"post-office-pickup"`, `"pack-station"`	`"DE"`

customerSettings object

Parameter	Type	Description	Default value
`type`	`String`	Valid values are `"ALL"`, `"B2C"`, `"B2B"`. Type `"ALL"` will display a switch for Personal or Business type.	`"B2C"`

mobileNumber object

Parameter	Type	Description	Default value
`prefix`	`String`	The country prefix of the mobile number.	`""`
`phone`	`String`	The mobile number.	`""`

The following code example shows the options described above:

<unzer-payment
        id="unzer-payment"
        publicKey="s-pub-xyz"
        locale="de-DE">
<!-- ... Here you will need to add the Unzer payment type tag, so the form UI elements will be inserted -->
<!--    e.g <unzer-paylater-invoice></unzer-paylater-invoice> -->
</unzer-payment>

<p>Shipping Information</p>
<unzer-shipping-address></unzer-shipping-address>

<p>Billing Information</p>
<unzer-billing-address></unzer-billing-address>

<unzer-checkout id='unzer-checkout'></unzer-checkout>

    const unzerPaymentElement = document.getElementById('unzer-payment');
    unzerPaymentElement.setCustomerData({
        "lastname": "Universum",
        "firstname": "Peter",
        "salutation": "mr",
        "birthDate": "20.12.1987",
        "mobileNumber": {
            "prefix": "49",
            "phone": "1234"
        },
        "shippingAddress": {
            "name": "Peter Universum",
            "street": "Hugo-Junkers-Str. 5",
            "zip": "60386",
            "city": "Frankfurt am Main",
            "country": "DE",
            "shippingType": "equals-billing"
        },
        "billingAddress": {
           "state": "Peter Universum",
           "street": "Hugo-Junkers-Str. 5",
            "zip": "60386",
            "city": "Frankfurt am Main",
            "country": "DE"
        }
    })

Step 2: Handling the form’s submission

Customer form with payment

After the submit button is clicked, the customer and payment data are automatically submitted. You will then need to query the unzer-checkout element and handle the response inside its onPaymentSubmit event listener.

The following code example shows how to read customer and payment data from the response.

// ...
const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.customerResponse) {
        if (response.customerResponse.success) {
            // Optional: Only in case a new customer is created in the frontend.
            const customerId = response.customerResponse.data.id;
        }

        if (response.submitResponse.success) {
            const paymentTypeId = response.submitResponse.data.id;
        }

        // Submit all IDs to your server-side integration to perform the payment transaction.
    }
};

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

<unzer-payment
          id="unzer-payment"
          publicKey="s-pub-xyz"
          locale="de-DE">
  <unzer-paylater-direct-debit></unzer-paylater-direct-debit>
</unzer-payment>
  
<p>Shipping Information</p>
<unzer-shipping-address></unzer-shipping-address>

<p>Billing Information</p>
<unzer-billing-address></unzer-billing-address>

<unzer-checkout id='unzer-checkout'></unzer-checkout>

const unzerPaymentElement = document.getElementById('unzer-payment');

const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.customerResponse) {
        if (response.customerResponse.success) {
            // Optional: Only in case a new customer is created in the frontend.
            const customerId = response.customerResponse.data.id;
        }

        if (response.submitResponse.success) {
            const paymentTypeId = response.submitResponse.data.id;
        }

        // Submit all IDs to your server-side integration to perform the payment transaction.
    }
};

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

Unzer Invoice with customer create form

<unzer-payment
          id="unzer-payment"
          publicKey="s-pub-xyz"
          locale="de-DE">
  <unzer-paylater-invoice></unzer-paylater-invoice>
</unzer-payment>
  
<p>Shipping Information</p>
<unzer-shipping-address></unzer-shipping-address>

<p>Billing Information</p>
<unzer-billing-address></unzer-billing-address>

<unzer-checkout id='unzer-checkout'></unzer-checkout>

const unzerPaymentElement = document.getElementById('unzer-payment');

const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.customerResponse) {
        if (response.customerResponse.success) {
            // Optional: Only in case a new customer is created in the frontend.
            const customerId = response.customerResponse.data.id;
        }

        if (response.submitResponse.success) {
            const paymentTypeId = response.submitResponse.data.id;
        }

        // Submit all IDs to your server-side integration to perform the payment transaction.
    }
};

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 id you pass into setCustomerData method yourself.

<unzer-payment
          id="unzer-payment"
          publicKey="s-pub-xyz"
          locale="de-DE">
  <unzer-paylater-direct-debit></unzer-paylater-direct-debit>
</unzer-payment>
  
<p>Shipping Information</p>
<unzer-shipping-address></unzer-shipping-address>

<p>Billing Information</p>
<unzer-billing-address></unzer-billing-address>

<unzer-checkout id='unzer-checkout'></unzer-checkout>

const unzerPaymentElement = document.getElementById('unzer-payment');
unzerPaymentElement.setCustomerData({
    "id": "s-cst-xyz",
    "lastname": "Universum",
    "firstname": "Peter",
    "salutation": "mr",
    "birthDate": "20.12.1987",
    "mobileNumber": {
        "prefix": "49",
        "phone": "1234"
    },
    "shippingAddress": {
        "name": "Peter Universum",
        "street": "Hugo-Junkers-Str. 5",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE",
        "shippingType": "equals-billing"
    },
    "billingAddress": {
        "state": "Peter Universum",
        "street": "Hugo-Junkers-Str. 5",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE"
    }
});

const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.customerResponse) {
        if (response.customerResponse.success) {
            // Optional: Only in case a new customer is created in the frontend.
            const customerId = response.customerResponse.data.id;
        }

        if (response.submitResponse.success) {
            const paymentTypeId = response.submitResponse.data.id;
        }

        // Submit all IDs to your server-side integration to perform the payment transaction.
    }
};

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 id you pass into setCustomerData method yourself.

<unzer-payment
          id="unzer-payment"
          publicKey="s-pub-xyz"
          locale="de-DE">
  <unzer-paylater-invoice></unzer-paylater-invoice>
</unzer-payment>
  
<p>Shipping Information</p>
<unzer-shipping-address></unzer-shipping-address>

<p>Billing Information</p>
<unzer-billing-address></unzer-billing-address>

<unzer-checkout id='unzer-checkout'></unzer-checkout>

const unzerPaymentElement = document.getElementById('unzer-payment');
unzerPaymentElement.setCustomerData({
   "id": "s-cst-xyz",
    "lastname": "Universum",
    "firstname": "Peter",
    "salutation": "mr",
    "birthDate": "20.12.1987",
    "mobileNumber": {
        "prefix": "49",
        "phone": "1234"
    },
    "shippingAddress": {
        "name": "Peter Universum",
        "street": "Hugo-Junkers-Str. 5",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE",
        "shippingType": "equals-billing"
    },
    "billingAddress": {
        "state": "Peter Universum",
        "street": "Hugo-Junkers-Str. 5",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE"
    }
});
const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.customerResponse) {
        if (response.customerResponse.success) {
            // Optional: Only in case a new customer is created in the frontend.
            const customerId = response.customerResponse.data.id;
        }

        if (response.submitResponse.success) {
            const paymentTypeId = response.submitResponse.data.id;
        }

        // Submit all IDs to your server-side integration to perform the payment transaction.
    }
};

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