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

Customer element	Description
`<unzer-customer-form>`	Adds the complete customer form including personal information (email, salutation, first name, last name), billing address, and shipping address. Automatically adjusts visible fields based on customer type (B2C/B2B) and payment method requirements (e.g., birth date and mobile number for Unzer Invoice and Installment).

The <unzer-customer-form> component can be inserted either inside or outside the <unzer-payment> element. On submit, all customer data will be automatically gathered and submitted together with the payment form to create the customer and payment type resources.

Customer Type Support
The customer form automatically handles both B2C (individual) and B2B (business) customers. Fields like birth date are shown for B2C customers when required by the payment method, while company-related fields are shown for B2B customers.

Field Visibility

The customer form dynamically shows/hides fields based on customer type and payment method:

B2C (Individual) customers:

Personal fields: email, salutation, first name, last name
Birth date (when required by payment method, e.g., Unzer Invoice, Unzer Installment)
Mobile number (when required by payment method)
Billing and shipping addresses
Company fields are hidden

B2B (Business) customers:

Personal fields: email, salutation, first name, last name
Company fields: company name, company type, registration details
Owner information (for sole proprietors)
Mobile number (when required by payment method)
Billing and shipping addresses
Birth date may be hidden depending on payment method

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"`	`""`
`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`	Configuration to pre-set the customer type without pre-populating data. See customerSettings object below.	`{ type: 'B2C' }`

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.	`""`
`shippingType` only in `shippingAddress`	`String`	The shippingType. Allowed values are: `"equals-billing"`, `"different-address"`, `"branch-pickup"`, `"post-office-pickup"`, `"pack-station"`	`""`

mobileNumber object

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

customerSettings object

Parameter	Type	Description	Default value
`type`	`String`	Pre-sets the customer type for the form. Valid values are `"B2C"` (individual customer) or `"B2B"` (business customer). Use this to render an empty form with the appropriate fields visible. Defaults to B2C if not provided.	`"B2C"`

Rendering Empty Forms

Use customerSettings to render empty forms pre-configured for specific customer types:

setCustomerData({ customerSettings: { type: 'B2C' } }) - Empty B2C form (or omit for default)
setCustomerData({ customerSettings: { type: 'B2B' } }) - Empty B2B form with company fields

Address Synchronization

The customer form includes an address synchronization feature:

Checkbox: “Billing address same as shipping address”
When checked, billing address fields automatically populate from shipping address
The shippingType parameter reflects the sync state:
- "equals-billing" - Addresses are synced (checkbox is checked)
- "different-address" - Separate billing and shipping addresses (checkbox is unchecked)

Shipping Type Values
Only "equals-billing" and "different-address" values have functional logic in the customer form. Other shippingType enum values may exist for compatibility but are not actively used.

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>

<unzer-customer-form></unzer-customer-form>

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

<unzer-customer-form></unzer-customer-form>

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

<unzer-customer-form></unzer-customer-form>

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

<unzer-customer-form></unzer-customer-form>

<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.
    }
};