Customer UI
Implement the Customer UI on your website.
Introduction
The 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.
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 customerId (with all the necessary information) to pass onto the transaction, or you want to update information of already created customer, 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 a customer form on it’s own, but we recommend using it in addition to a payment method - for instance, one of the two mentioned above.
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 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="customer" class="field">
<!-- The customer form UI element will be inserted here -->
</div>
<!-- Submit button>
Down below in the examples section you can find completed examples using the customer form.
Step 2: Create the a customer instance
A 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:
// Creating a customer instance
var Customer = heidelpayInstance.Customer()
// Rendering the customer form
Customer.create({
containerId: 'customer'
})
// Creating a customer instance
var Customer = heidelpayInstance.Customer()
// Initialize customer form with existing customer data
Customer.initFormFields({
"lastname": "Universum",
"firstname": "Peter",
"salutation": "mr",
"birthDate": "1987-12-20",
"billingAddress": {
"street": "Hugo-Junkers-Str. 5",
"state": "DE-BO",
"zip": "60386",
"city": "Frankfurt am Main",
"country": "DE"
}
})
// 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
Customer.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
Customer.update('s-cst-7f0910d26396', {
containerId: 'customer',
})
Step 3: Handling the form’s submission
Customer form
Although we recommend using the customer form in addition to a payment, 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 write createCustomer()
, like so:
// Inside your form event handler:
Customer.createCustomer()
.then(function(data) {
// Success
})
.catch(function(error) {
// Error
})
// Inside your form event handler:
Customer.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.
Customer form with payment
Usually you want to use the customer form with a payment method, in that case you create promises for both resources and handle them with Promise.all()
.
Here’s an example:
// Inside your event handler
var paymentPromise = paymentMethod.createResource()
var customerPromise = Customer.createCustomer()
Promise.all([paymentPromise, customerPromise])
.then(function(values) {
// Success
})
.catch(function(error) {
// Error
})
Here we’re creating two variables to temporarily store the individual promises: paymentPromise
and customerPromise
.
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 completed HTML and JavaScript examples using this approach down below.
Examples
Here you can find completed examples for Unzer Direct Debit Secured and Invoice Guaranteed with a customer form.
Reminder: Unzer provides you with an optional customer form, in case you have not saved any customer data in the first place, or if you want to update your customer information. The customer UI component is almost completely optional, except when you want to integrate a guaranteed payment method.
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 guaranteed payment method and you don’t have any pre-existing customer data, you can copy the following code into your website:
<form id="payment-form-sepa-guaranteed-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="customer" class="field">
<!-- The 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 customer instance
var Customer = heidelpayInstance.Customer()
// Rendering the customer form
Customer.create({
containerId: 'customer'
})
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed-customer')
form.addEventListener('submit', function(event) {
event.preventDefault();
var SepaGuaranteedPromise = SepaGuaranteedCustomer.createResource()
var customerPromise = Customer.createCustomer()
Promise.all([SepaGuaranteedPromise, customerPromise])
.then(function(values) {
// Success
})
.catch(function(error) {
// Error
})
});
Invoice Guaranteed with customer create form
Before following this guide, we recommend you read through the Invoice first.
If you’re certain that you need a guaranteed payment method and you don’t have any pre-existing customer data, you can copy the following code into your website:
<form id="payment-form">
<div id="example-invoice-secured"></div>
<div id="customer" class="field">
<!-- The 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 unzer= new Unzer('s-pub-xxxxxxxxxx');
// Creating a Invoice Guaranteed instance
var InvoiceGuaranteed = heidelpayInstance.InvoiceGuaranteed()
// Creating a customer instance
var Customer = heidelpayInstance.Customer()
// Rendering the customer form
Customer.create({
containerId: 'customer'
})
// Handle payment form submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
event.preventDefault();
var InvoiceGuaranteedPromise = InvoiceGuaranteed.createResource()
var customerPromise = Customer.createCustomer()
Promise.all([InvoiceGuaranteedPromise, customerPromise])
.then(function(values) {
// Success
})
.catch(function(error) {
// Error
})
});
Unzer Direct Debit Secured with customer update form (birthday field only)
Before following this guide, we recommend you read through the Unzer Direct Debit integration guide first.
If you’re certain that you need a guaranteed payment method, you have pre-existing customer data and you want to update the customer’s birthdate, you can copy the following code into your website.
Note: You will need to set the customerId you pass into Customer.update() method yourself.
<form id="payment-form-sepa-guaranteed-birthday" class="heidelpayUI form" novalidate>
<div id="sepa-guaranteed-customer-IBAN" 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="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 customer instance
var Customer = heidelpayInstance.Customer()
// Load the ID of the customer you want to update
// The customerId string would look similar to s-cst-79b8zf879pp3
var customerId = 's-cst-79b8zf879pp3'
// Apart from updating birthdate, you can also update name and/or address of a customer
// If that is the case, pass 'name' and/or 'address' strings in the array of the `fields` key
var options = {
containerId: 'customer',
fields: ['birthdate'], // at least one string required ('birthdate' || 'name' || 'address')
infoBoxText: 'Your birthdate data', // optional
showHeader: false, // optional
}
// Rendering the customer update form with birthday field only
Customer.update(customerId, options);
// Handling the form's submission
var form = document.getElementById('payment-form-sepa-guaranteed-birthday')
form.addEventListener('submit', function(event) {
event.preventDefault();
var SepaGuaranteedPromise = SepaGuaranteedCustomer.createResource()
var customerPromise = Customer.updateCustomer()
Promise.all([SepaGuaranteedPromise, customerPromise])
.then(function(values) {
// Success
})
.catch(function(error) {
// Error
})
});
References
Constructors
Constructor | Description |
---|---|
heidelpay.Customer() |
Initializes the Customer object. |
Method summary
Type | Method | Description |
---|---|---|
void | create(Object options) | Creates a customer create form and mounts it onto the declared DOM element. |
void | update(String customerId, Object options) | Creates a customer update form and mounts it onto the declared DOM element. |
void | initFormFields(Object customer) | Initializes existing customer data. |
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), which results in making a PUT request to update a customer, or rejected (validation didn’t pass) |
initFormFields
Method
void initFormFields(Object customer)
Description
In case there is existing customer data, it is possible to initialize the form fields with said data on creation. Must be called before the .create()
function.
Properties
Type | Property | Description |
---|---|---|
Object | customer | An existing customer object in JSON format. |
customer
Type | Property | Description |
---|---|---|
String | fistname | The customer’s first name. Default: "" |
String | lastname | The customer’s last name. Default: "" |
String | birthDate | The customer’s birthdate. Default: "" |
String | salutation | The customer’s salutation. Default: "mr" |
Object | address | The customers billing address in JSON format. Default: {} |
address
Type | Property | Description |
---|---|---|
String | state | The customer’s billing address state. Default: "" |
String | street | The customer’s billing address street. Default: "" |
Number | zip | The customer’s billing address zip. Default: "" |
String | city | The customer’s billing address city. Default: "" |
String | country | The customer’s billing address country (as country code). Default: "DE" |
create
Method
void create(Object options)
Description
Creates an input form for 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 |
---|---|---|
String | containerId | The HTML id of the DOM element, where the UI component will be inserted.Example: containerId: 'card-element-id-number' |
Boolean | showInfoBox | Displays a small info box above the input form. Default: true |
String | infoBoxText | The text inside the info box. |
Boolean | showHeader | Small headers for the “personal data” and “address” sections of the input form. Default: true |
String | headerPersonalDataText | The text of the “personal data” heading. |
String | headerAddressText | The text of the “address” heading. |
String | externalCustomerId | The customerId you are already using in your system. This can save the hassle of saving a new customerId provided by Unzer in your database. |
update
Method
void update(String customerId, Object options)
Description
Creates an input form for updating customer data. You should pass customerId and additional options as key value pairs inside the options
parameter
Properties
Type | Property | Description | Required |
---|---|---|---|
String | customerId | A string representing the ID of the customer you wish to update. | Yes |
Object | options* | An object with various options. | Yes |
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 |
Array | fields | An array of items you want to update. It accepts strings: ‘birthdate’, ‘name’ and ‘address’ | Yes (at least one string) |
Boolean | showInfoBox | Displays a small info box above the input form. Default: true |
No |
String | infoBoxText | The text inside the info box. | No |
Boolean | showHeader | Small headers for the “personal data” and “address” sections of the input form. Default: true |
YNo |
String | headerPersonalDataText | The text of the “personal data” heading. | No |
String | headerAddressText | The text of the “address” heading. | No |
createCustomer
Method
Object createCustomer()
Description
Creates a promise and submits the (customer)form’s data. A /customers
is created and either 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 customer form’s updated data. If it resolves (validation passed), it updates the chosen customer. In both resolve or reject 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. |