B2B Customer UI

Implement the B2B Customer UI on your website.

Introduction

The B2B Customer component is an additional input form for certain payment methods. You can find more information about that in the customers section of the documentation. Furthermore, the B2B Customer component is almost identical to the B2C Customer component

Down below you can see how the input form will look like, when following the instructions correctly.

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

As mentioned above, certain payment methods require you to pass customer information in addition to the usual resource ID’s. In case you don’t have an already established B2B customerId with all the necessary information, you can do so using this input form.

Payment methods with mandatory customer submission

These are the payment methods which require you to submit a customerId:

The overall rundown is similar to the web integration walkthrough with the exception of Step 1. You can use the B2B customer form on its own, but we recommend using it in addition to a payment method.

Prerequisites
In order to follow this guide without issues, you should already have an established payment method on your website, the customer form is merely an addition to it.

Step 1: Insert the customer form

In order to use the B2B customer form effectively, you have to insert it into your payment form. We recommend you place it between the payment elements and the submit button.

Here’s a short example:

<!-- ... Payment elements -->
<div id="b2b-customer" class="field">
  <!-- The B2B customer form UI element will be inserted here -->
</div>
<!-- Submit button>
Complete examples
Down below in the examples section you can find completed examples using the customer form.

Step 2: Create the B2B customer instance

A B2B customer instance is created like any other UI component. However, different steps are taken in case you with to update the date of an already created customer:

// JavaScript: B2B Customer (create)
// Creating a customer instance
var B2BCustomer = heidelpayInstance.B2BCustomer()
// Rendering the customer form
B2BCustomer.create({
  containerId: 'b2b-customer'
})
// JavaScript: B2B Customer (update)
// Creating a customer instance
var B2BCustomer = heidelpayInstance.B2BCustomer()
// Initialize customer form with existing customer data
B2BCustomer.initFormFields({
  "lastname": "Universum",
  "firstname": "Peter",
  "salutation": "mr",
  "company": "unzer GmbH",
  "birthDate": "1987-12-20",
  "email": "john.doe@unzer.com",
  "billingAddress": {
    "name": "Peter Universum",
    "street": "Hugo-Junkers-Str. 5",
    "state": "DE-BO",
    "zip": "60386",
    "city": "Frankfurt am Main",
    "country": "DE"
  },
  "companyInfo": {
    "registrationType": "not_registered",
    "function": "OWNER",
    "commercialSector": "AIR_TRANSPORT",
    "commercialRegisterNumber": "de-423fsdf-zz"
  },
})

// Optional: add a custom event listener that sends the validation result 
// of all input fields
// Note: the event listner has to be called before the `update()` call
B2BCustomer.addEventListener('validate', function(e) {
    if (e.success) {
    // run some code (e.g. enable the disabled `pay` button)
    } else {
    // run some code (e.g. disable the `pay` button)
  }
})

// Call the update method that will initialize the form with
// existing customer data
// You should pass the current customer's Id, and the containerId
B2BCustomer.update('s-cst-7f0910d26396', {
    containerId: 'b2b-customer',
})

Step 3: Handling the form’s submission

B2B Customer form

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 with the exception of the method signature.

Instead of createResource() you need to implement the createCustomer() method, if you are creating the customer for the first time, or updateCustomer(), if you initialised the customer following the update steps:

// JavaScript: createCustomer()
// Inside your form event handler:
B2BCustomer.createCustomer()
  .then(function(data) {
  // Success
})
  .catch(function(error) {
  // Error
})
// JavaScript: updateCustomer()
// Inside your form event handler:
B2BCustomer.updateCustomer()
  .then(function(data) {
  // Success
})
  .catch(function(error) {
  // Error
})

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

B2B 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 resources and handle them with Promise.all().

Here’s an example:

// Inside your event handler
var paymentPromise = paymentMethod.createResource()
var b2bCustomerPromise = B2BCustomer.createCustomer() // same case will apply for updateCustomer() method
Promise.all([paymentPromise, b2bCustomerPromise])
  .then(function(values) {
  // Success
})
  .catch(function(error) {
  // Error
})

Here we’re creating two variables to temporarily store the individual promises: paymentPromise and b2bCustomerPromise.

When creating the promises, be sure you use the right methods:
createResource() for the payment method you want to use - and createCustomer() for the customer.

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

You can find a few examples below.

Examples

Here you can find completed examples for Unzer Direct Debit Secured and Unzer Invoice Secured with a B2B customer form.

Reminder: Unzer provides you with an optional B2B customer form, in case you have not saved any customer data in the first place. The B2B customer UI component is almost completely optional, except when you want to integrate a secured payment method.

Including Unzer JS & CSS
Make sure you include unzer.js and unzer.css on your website first, before you start creating payment forms.

Unzer Direct Debit Secured with customer create form

Before following this guide, we recommend you read through the Unzer Direct Debit integration guide first.

If you’re certain that you need a secured payment method and you don’t have any pre-existing B2B customer data, you can copy the following code into your website:

<form id="payment-form-sepa-guaranteed-b2b-customer" class="heidelpayUI form" novalidate>
  <div id="sepa-guaranteed-customer-IBAN" class="field">
    <!-- The IBAN field UI Element will be inserted here -->
  </div>
  <div id="b2b-customer" class="field">
    <!-- The B2B customer form 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 SepaGuaranteedCustomer = heidelpayInstance.SepaDirectDebitGuaranteed()
// Rendering the input field
SepaGuaranteedCustomer.create('sepa-direct-debit-secured', {
  containerId: 'sepa-guaranteed-customer-IBAN'
});
// Creating a B2B customer instance
var B2BCustomer = heidelpayInstance.B2BCustomer()
// Rendering the B2B customer form
B2BCustomer.create({
  containerId: 'b2b-customer'
})
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed-b2b-customer')
form.addEventListener('submit', function(event) {
  event.preventDefault();
  var sepaGuaranteedPromise = SepaGuaranteedCustomer.createResource()
  var b2bCustomerPromise = B2BCustomer.createCustomer()
  Promise.all([sepaGuaranteedPromise, b2bCustomerPromise])
    .then(function(values) {
    // Success
  })
    .catch(function(error) {
    // Error
  })
});

Unzer Invoice Secured with customer create form

Before following this guide, we recommend you read through the Invoice first.

If you’re certain that you need a secured payment method and you don’t have any pre-existing B2B customer data, you can copy the following code into your website:

<form id="payment-form">
  <div id="example-invoice-secured"></div>
  <div id="b2b-customer" class="field">
    <!-- The B2B customer form 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 Invoice Secured instance
var InvoiceGuaranteed = heidelpayInstance.InvoiceGuaranteed()
// Creating a B2B Customer instance
var B2BCustomer = heidelpayInstance.B2BCustomer()
// Rendering the B2B customer form
B2BCustomer.create({
  containerId: 'b2b-customer'
})
// Handle payment form submission
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  var invoiceGuaranteedPromise = InvoiceGuaranteed.createResource()
  var b2bCustomerPromise = B2BCustomer.createCustomer()
  Promise.all([invoiceGuaranteedPromise, b2bCustomerPromise])
    .then(function(values) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

References

Constructors

Constructor Description
heidelpay.B2BCustomer() Initializes the B2BCustomer object.

Method summary

Type Method Description
void create(Object options) Initiates a B2B customer create form and mounts it onto the declared DOM element.
void initFormFields(Object b2bData) Passes the existing customer data to B2BCustomer component.
void update(String customerId, Object options) Initiates a B2B customer update form and mounts it onto the declared DOM element.
Promise createCustomer() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).
Promise updateCustomer() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).

create

Method

void create(Object options)

Description

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

Properties

Type Property Description
Object options A JSON object with various options.

options

Type Property Description Required
String containerId The HTML id of the DOM element, where the UI component will be inserted.
Example:
containerId: 'card-element-id-number'
Yes

initFormFields

Method

void initFormFields(Object b2bCustomerData)

Description

Passes the existing customer data to B2BCustomer component.

Properties

Type Property Description
Object b2bCustomerData An object containing existing customer information

b2bCustomerData

Type Property Description UI Validation
String firstname Value required only if registrationType is not_registered
Default: ""
maxLength: 40 characters"
String lastname Value required only if registrationType is not_registered
Default: ""
maxLength: 40 characters"
String salutation Value required only if registrationType is not_registered
Default: "mr"
Radio button, only one option is selected.
Choices: Mr., Mrs., Diverse
String birthDate Value required only if registrationType is not_registered
Default: ""
errorMessage:
- Wrong birthday
- Customer must be over 18 years old to use this payment method

dateFormat: depend on language of selected country. For example, English is yyyy-MM-dd
String email Value required only if registrationType is not_registered
Default: ""
maxLength: 100 characters
errorMessage: Wrong e-mail
acceptanceData: a-z, A-Z, 0-9, should contain only one @ character.
Object billingAddress Billing address of the customer.
Object companyInfo Customer’s company info.
Object differentBillingAddress Optional field
Another billing address
Default: ""
billingAddress
Type Property Description UI Validation
String street Default: "" maxLength: 50 characters"
String state Default: ""
String zip Default: "" Zip code validation will depend on selected country
errorMassage: Wrong postal code
String city Default: ""
String country Default: "Germany" Choices listed below:
country
Country
‘Germany’,
‘Austria’,
‘Belgium’,
‘Czechia’,
‘Denmark’,
‘France’,
‘Iran’,
‘Ireland’,
‘Italy’,
‘Luxembourg’,
‘Netherlands’,
‘Poland’,
‘Russia’,
‘Spain’,
‘Sweden’,
‘Switzerland’,
‘Tunisia’,
‘UK’,
‘Ukraine’,
‘USA’

companyInfo

Type Property Description
String registrationType Choices:
registered and not_registered
String commercialRegisterNumber Value required only if registrationType is registered
String commercialSector Choices listed below:
commercialSector
Choices
‘OTHER’,
‘WHOLESALE_TRADE_EXCEPT_VEHICLE_TRADE’,
‘RETAIL_TRADE_EXCEPT_VEHICLE_TRADE’,
‘WATER_TRANSPORT’,
‘AIR_TRANSPORT’,
‘WAREHOUSING_AND_SUPPORT_ACTIVITES_FOR_TRANSPORTATION’,
‘POSTAL_AND_COURIER_ACTIVITIES’,
‘ACCOMMODATION’,
‘FOOD_AND_BEVERAGE_SERVICE_ACTIVITIES’,
‘MOTION_PICTURE_PRODUCTION_AND_SIMILAR_ACTIVITIES’,
‘TELECOMMUNICATIONS’,
‘COMPUTER_PROGRAMMING_CONSULTANCY_AND_RELATED_ACTIVITIES’,
‘INFORMATION_SERVICE_ACTIVITIES’,
‘RENTAL_AND_LEASING_ACTIVITIES’,
‘TRAVEL_AGENCY_AND_RELATED_ACTIVITIES’,
‘SERVICES_TO_BUILDINGS_AND_LANDSCAPE_ACTIVITIES’,
‘LIBRARIES_AND_SIMILAR_CULTURAL_ACTIVITIES’,
‘SPORTS_ACTIVITIES_AND_AMUSEMENT_AND_RECREATION_ACTIVITIES’,
‘OTHER_PERSONAL_SERVICE_ACTIVITIES’,
‘NON_RESIDENTIAL_REAL_ESTATE_ACTIVITIES’,
‘MANAGEMENT_CONSULTANCY_ACTIVITIES’,
‘ELECTRICITY_GAS_AND_STEAM_SUPPLY’,
‘WATER_COLLECTION_TREATMENT_AND_SUPPLY’,
‘SEWERAGE’,
‘MANUFACTURE_OF_FOOD_PRODUCTS’,
‘MANUFACTURE_OF_BEVERAGES’,
‘MANUFACTURE_OF_TEXTILES’,
‘OTHERS_COMMERCIAL_SECTORS’,
‘MANUFACTURE_OF_WEARING_APPAREL’,
‘MANUFACTURE_OF_LEATHER_AND_RELATED_PRODUCTS’,
‘MANUFACTURE_OF_PHARMACEUTICAL_PRODUCTS’,
‘REPAIR_AND_INSTALLATION_OF_MACHINERY_AND_EQUIPMENT’,
‘TRADE_AND_REPAIR_OF_MOTOR_VEHICLES’,
‘PUBLISHING_ACTIVITIES’,
‘REPAIR_OF_COMPUTERS_AND_GOODS’,
‘PRINTING_AND_REPRODUCTION_OF_RECORDED_MEDIA’,
‘MANUFACTURE_OF_FURNITURE’,
‘OTHER_MANUFACTURING’,
‘ADVERTISING_AND_MARKET_RESEARCH’,
‘OTHER_PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_ACTIVITIES’,
‘ARTS_ENTERTAINMENT_AND_RECREATION’,

update

Method

void update()

Description

Initiates a B2B customer update form and mounts it onto the declared DOM element.

Properties

Type Property Description Required
String customerId ID of the customer that is to be updated. Yes
Object options Object containing containerId. Yes

options

Type Property Description Required
String containerId The HTML id of the DOM element, where the UI component will be inserted. Yes

createCustomer

Method

Object createCustomer()

Description

Creates a promise and submits the (b2b customer) form’s data. It either gets resolved or rejected. In both cases an object is returned.

Returns

An object with the following structure:

  • Success: {id: String}
  • Error: {}
Type Property Description
String id The returned /customers resource Id.

updateCustomer

Method

Object updateCustomer()

Description

Creates a promise and submits the (b2b customer) form’s updated data. It either gets resolved or rejected. In both cases an object is returned.

Returns

An object with the following structure:

  • Success: {id: String}
  • Error: {}
Type Property Description
String id The returned /customers resource Id.

The returned Id will be the same as the one passed in update() method