Web integration
Integrate the Unzer API into your website.
Introduction
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.
Requirements
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 |
Alipay |
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.
Rundown
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>
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.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');
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.
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'});
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. -->
</div>
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:
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.