Web integration

Integrate the Unzer API into your website.


The web integration guides walk you through creating a payment form, instantiating a payment method and handling the forms submission. Although the code differs from payment-method to payment-method, the process stays the same throughout the implementation.


To ensure easy and fast integration for each payment method, Unzer provides you with with two files:

unzer.js and unzer.css

Both of these files are required, in order to accept payments on your website. You can learn more about that in step 1.

Supported payment methods

Here’s a small list of payment methods you can integrate using heidelpay.js (often referred to as Unzer UI components):

Credit Card SOFORT
Unzer Direct Debit Giropay
iDEAL Przelewy24
Invoice Unzer Prepayment
Paypal EPS
Unzer Bank Transfer WeChat Pay

There you can find specific integration guides, samples and explanations.

UI Examples

On the demo page on static.unzer.com you can find all UI components in one place and try them out for yourself.


There are only four small steps required for creating a payment method.

  • Step 1: Setup
  • Step 2: Create your form
  • Step 3: Create your payment method
  • Step 4: Create your resource id and submit it to your server

Step 1: Setup

As you will see in all payment methods, step 1 always stays the same.

First, you need to include Unzer’s script and stylesheet on your website. They must always be loaded directly from https://static.unzer.com.

<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>
Importing Unzer styles
In order to minimize the risk of Unzer styles affecting the styles of your webpage, we suggest, in case you have multiple CSS files, to put heidelpay.css on top of other imported CSS files.
Good practice
Even though it’s not mandatory in HTML, it’s considered good practice to place scripts at the bottom of your HTML document. This way your website will display and load faster.

Next, create a Unzer instance with your public key:

// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
Placeholder keys
In the example above, we used a placeholder API key for showcase purposes. For production usage you should replace it with your personal public key.

If you don’t have a public and private key yet, you can get them by sending an e-mail to our support.

unzer instance
Note: In case you have multiple payment methods, only one Unzer instance is needed.

Localization and languages

We also support localization with locale option parameters. Currently these parameters are supported: (default) ‘auto’, ‘en-US’, ‘en-UK’, ‘de-DE’, ‘de-CH’, ‘de-AT’.

The ‘auto’ option (which is applied automatically) uses the clients browser language by default.

Here you can see how to manually set the language, in our case ‘de-DE’ - to do so, simply add a comma separated parameter to your Unzer instance - in the end, it should look like this:

var unzer= new Unzer('s-pub-xxxxxxxxxx', {locale: 'de-DE'});
This concludes the setup - Note: This step stays the same for every single payment method.

Step 2: Create your form

In order to securely collect payment data from your customers, you need to create a payment form with empty DOM elements and unique ID’s within them. That way unzer.js will know where to place its UI components.

It doesn’t matter what you set the ID’s to - it’s important that they’re the same in your HTML and javascript file.

Here’s a short example to help you understand - and don’t worry if you didn’t get everything the first time, we’ll guide you through it:

<div id="example-card-number">
    <!-- Card number UI Element will be inserted here. -->
Card.create('number', {
  containerId: 'example-card-number',
  onlyIframe: false

As you can see, we created a simple <div> element and assigned it a unique id. In our case it’s example-card-number.
That’s all unzer.js needs in your HTML document to place it’s UI components within it.

Don’t worry about the javascript code for now, we’ll explain that later, just look at the parameter list inside of the Card.create() function. There’s a JSON with key-value pairs within - one of them is containerId: 'example-card-number'.

So basically:

Matching IDs
When choosing your ID for a UI component, be sure the names in your HTML and javascript files match up.

For example:
<div id="example-card-number"> matches containerId:"example-card-number".

Every payment method has a different payment form, you can find specific integration examples under supported payment methods.

Step 3: Create your payment method

After you’ve determined what payment method you want to use (in step 2), it’s time to create a payment method. Depending on the method, integrations differ in functionality from one another.

To see detailed instructions and plenty examples, check supported payment methods.

Step 4: Create your resource ID and submit it to your server

In the last step basic form functionality is implemented - from creating a resource ID, listening to events and submitting payment information, everything is taken care of in a quick and easy way.

At supported payment methods you can find all the specific guides you need.

Questions? Maybe you can find the answer you’re looking for in our FAQ.

Redirect Payments

Implement the payment redirect UI on your website.

Read More
Customer UI

Implement the Customer UI on your website.

Read More
PayPal UI

Implement the PayPal UI on your website.

Read More
B2B Customer UI

Implement the B2B Customer UI on your website.

Read More
Migrate to Unzer UI components

Migrate from the old heidelpay UI components to the new Unzer UI components.

Read More