Integrate using UI components (v2)
BetaAccept payments through UI components v2 created by Unzer.
Overview
Payments can be accepted using our ready-to-use UI components v2 by Unzer.
You can quickly integrate your website with the Unzer API, with no need to prepare your website’s payment front end from scratch.
Our UI components v2 are also customizable, so they can fit your needs.
Example card UI component |
Example address UI component |
You can see all the UI components in action on our demo pages.
Your integration is automatically PCI-compliant if you are using the Unzer UI components. For details, see PCI compliance guide.
Read this guide for a general overview of how to accept payments with UI components. For a list of all payment methods that you can integrate using UI components, see the Supported Payment methods page.
Before you begin
Check the basic integration requirements.
How it works
To integrate a payment method using UI components, you need to perform steps both on client side and server side.
- Add UI components to your payment page and create the payment type resource.
- On the server side, use the ID of the newly created payment type to make a payment using one of the supported server-side technologies (Direct API integration, PHP SDK integration, Java SDK integration. For some payment methods, forwarding the customer to external page is necessary.
- After the payment is made, you should check its status on the server side and display the result to the customer on the client side.
- You can perform more operations on the server side once the payment has been made – a common example would be canceling the payment.
Step 1: Add UI components to your payment pageclient side
First you need to initiate our UI components library and add the payment form to your payment page.
Initiate UI components
Initiate UI components v2Load the Unzer JS script
Load the Unzer JS scriptInclude the Unzer JS script on your website. This will load all the Unzer custom UI components, prefixed with unzer-
e.g <unzer-paylater-invoice>
.
Make sure to always include the script directly from the Unzer domain https://static.unzer.com
<script
type="module"
src="https://static.unzer.com/v2/ui-components/index.js"
></script>
To make your website load faster, import the unzer script at the bottom of your HTML document.
Make sure to import the script as type=“module”
To learn which URLs must be added to the allowlist for Unzer UI components in your content security policy, please refer to Content security policy section.
It is a good practice to put your website in loading state until the Unzer script is loaded, and the UI components are ready to use.
// Make sure initially your application is in loading state
// until all Unzer components are loaded
Promise.all([
customElements.whenDefined("unzer-payment"),
// Probably add any other Unzer components used here. For example:
// customElements.whenDefined("unzer-paylater-invoice"),
]).then(() => {
// Hide the loading state and proceed with next steps
}).catch((error) => {
// Handle any error that might occur during the
// loading process and initialization
});
UI setup and configuration
UI setup and configurationTo securely collect payment data from your customer, you need to add the <unzer-payment>
component, inside which you insert the needed payment type components.
<unzer-payment
id="unzer-payment"
publicKey="s-pub-xyz"
locale="de-DE">
<!-- ... Here you will need to add the Unzer payment type tag e.g <unzer-paylater-invoice></unzer-paylater-invoice>, so the form UI elements will be inserted -->
<!-- <unzer-paylater-invoice></unzer-paylater-invoice>-->
</unzer-payment>
<button type="submit" id="yourPaymentButtonId">Pay</button>
Following parameters need to be passed.
Parameter | Type | Description | Default value |
---|---|---|---|
publicKey (required) | String | The merchant public key. | - |
locale | String | The used locale. For more information on supported locales, see Localization. | Browser user defined locale. |
initData | object | A key/value object in JSON-format containing data to initialize the payment type. For more information, Check payment methods and their features. | Empty object {} |
Optional: Customize UI components
Optional: Customize UI componentsOur UI Components v2 are provided with a default theme that contains base styles. You can easily customize these styles by overriding the following CSS variables.
Variable name | Description | Affected components |
---|---|---|
--unzer-font | Replaces all fonts with the given font. Users can define any font-face and provide the name of the custom font-face. | typography |
--unzer-text-color | The font color use for typography. | typography, icons |
--unzer-brand-color | The main color of the application. | button, checkbox, radio, loader |
--unzer-background-color | The page background. | |
--unzer-link-color | The color of links. | link |
--unzer-corner-radius | Whether controls will have rounded corners or not. Values can be either 0 or 1. | button, tags, chips |
--unzer-shadows | Whether shadows are enabled or not. Values can be either 0 or 1. | button, card |
<head>
<style>
:root {
--unzer-font: SFMono;
--unzer-brand-color: #ee1818;
--unzer-text-color: #f19316;
--unzer-background-color: #6a9472;
--unzer-link-color: #1330ef;
--unzer-corner-radius: 0;
--unzer-shadows: 1;
}
</style>
</head>
Create Payment Type Resource
Create Payment Type ResourceFor each payment type that you use, you need to create a dedicated payment type resource.
Inside the event listener of your submit button you need to query the unzer-payment
component and call its submit()
method to submit the payment.
// ...
const submitButton = document.getElementById('yourPaymentButtonId');
submitButton.addEventListener('click', function (event) {
const unzerPaymentContainer = document.getElementById('unzer-payment');
unzerPaymentContainer.submit().then((response) => {
if (response.submitResponse.data.success) {
const paymentId = response.submitResponse.data.id;
// Submit the ID of the created payment type resource (and customer resource) to your
// server side integration to perform the payment transaction with it.
}
}).catch((error) => {
// Handle resource creation error
})
})
Full example
<unzer-payment
id="unzer-payment"
publicKey="s-pub-xyz"
locale="de-DE">
<unzer-paylater-invoice></unzer-paylater-invoice>
</unzer-payment>
<button type="submit" id="yourPaymentButtonId">Pay</button>
Promise.all([
customElements.whenDefined("unzer-payment"),
customElements.whenDefined("unzer-paylater-invoice")
]).then(() => {
// Hide the loading state and proceed with next steps
// e.g hadle payment type creation
const submitButton = document.getElementById('yourPaymentButtonId');
submitButton.addEventListener('click', function (event) {
const unzerPaymentContainer = document.getElementById('unzer-payment');
unzerPaymentContainer.submit().then((response) => {
if (response.submitResponse.data.success) {
const paymentId = response.submitResponse.data.id;
// Submit the id of the created payment type to your
// backend to perform the payment transaction.
}
}).catch((error) => {
// Handle resource creation error
})
})
}).catch((error) => {
// Handle any error that might occur during the
// loading process and initialization
});
Step 2: Make a paymentserver side
After you have created the payment type resource, you can make a charge
transaction with it. There are two basic scenarios for the charge
transaction: direct charge
and charge
after authorization
. Direct charge
debits customer account immediately. charge
after authorization
will first reserve the requested amount on the customer account. The actual money transfer takes place when the merchant performs the charge
transaction —usually when shipping the goods.
For a detailed explanation, see One-time payment use case.
For example, directly charging a card looks like this:
POST https://api.unzer.com/v1/payments/charges
Body:
{
"amount" : "20",
"currency": "EUR",
"returnUrl": "https://www.my-shop-url.de/returnhandler",
"resources" : {
"customerId" : "s-cst-fm7tifzkqewy",
"typeId" : "crd-fm7tifzkqewy"
}
}
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = new Charge(100.00, 'EUR', $returnUrl);
$unzer->performCharge($charge, $typeId);
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
unzer.charge(amount, Currency.getInstance("EUR"), paymentTypeId, returnUrl, customerId);
charge
transaction.For a full description of the charge
and authorize
, see the relevant server-side integration documentation page: Direct API integration, PHP SDK integration, Java SDK integration.
Forward the customer to the external payment page
Some payment methods require the customer to finalize the payment action on an external page, such as PayPal and Credit Card 3DS.
In those cases, the API will return a redirectURL
in the response to the payment transaction. After the customer’s action on the external page, they are redirected back to the shop using the returnURL
that you have set in the payment transaction request (charge
or authorization
).
To learn more about different types of payment flows, see Payment methods page.
Step 3: Check status of the paymentserver side
Once the payment is made, you can make a call to retrieve the current payment
and transaction status.
GET https://api.unzer.com/v1/payments/{payment_ID}
Response:
{
"id": "s-pay-xyz",
"state": {
"id": 1,
"name": "completed"
},
"amount": {
"total": "12.9900",
"charged": "12.9900",
"canceled": "0.0000",
"remaining": "0.0000"
},
"currency": "EUR",
"orderId": "",
"invoiceId": "",
"resources": {
"customerId": "s-cst-xxxxxxxx",
"paymentId": "s-pay-xyz",
"basketId": "",
"metadataId": "",
"payPageId": "",
"traceId": "c214b92c869c08b3f2c99ab57d70c8e1",
"typeId": "s-crd-xxxxxxxxx"
},
"transactions": [
{
"date": "2021-05-27 11:25:20",
"type": "charge",
"status": "success",
"url": "https://api.unzer.com/v1/payments/s-pay-xyz/charges/s-chg-1",
"amount": "12.9900"
}
]
}
Notifications
Notifications allow you to receive information about any changes related to your payment
after the initial transaction. We recommend subscribing to the payment
event to receive notifications about any changes to the payment
resource. As soon as the event is triggered you should fetch the payment
and update the order status in your shop according to its status.
{
"event":"payment.pending",
"publicKey":"s-pub-xxxxxxxxxx",
"retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-xyz",
"paymentId":"s-pay-xyz"
}
For more details on implementing webhooks to receive notifications, see Notifications
Step 4: Display the payment resultclient side
Use the information from the Check status of the payment step to show the payment result to your customer.
This can either be the success or error page of your shop. If something went wrong, you can use the client message from the API response and display it to the customer.
Some payment types, like Unzer Installment and Unzer Invoice require to show additional data to the client on the success page. Refer to the specific integration descriptions of these types to learn more about it.
Manage paymentsserver side
After you have made a transaction, you can perform additional operations on it. Common example is the cancel operation which can be done for most of the payment methods. For a full reference of managing payments please refer to relevant Server-side integration documentation page: Direct API integration, PHP SDK integration, Java SDK integration.
Cancel after money receipt (refund)
To refund a payment you need to perform a cancel on a successful charge
transaction. This transfers the money back to the customer.
POST https://api.unzer.com/v1/payments/s-pay-xyz/charges/s-chg-1/cancels
Body:
{
"amount": "1.0",
"paymentReference": "Test"
}
$unzer = new Unzer('s-priv-xxxxxxxxxx');
$cancellation = $unzer->cancelChargeById('s-pay-xyz', 's-chg-1');
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
unzer.cancel("s-pay-xyz", "s-chg-1");
Cancel before money receipt (reversal)
To reduce or cancel reservation on the customer account you need to perform a cancel
on the initial authorize
. An example of reversal would be releasing (unblocking) the reserved amount on customer account after they returned a rented car.
POST https://api.unzer.com/v1/payments/s-pay-xyz/authorize/cancels
Body:
{
"amount": "1.0"
}
$unzer = new Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-xyz');
$unzer->cancelAuthorizationByPayment($payment, 100.00);
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Authorization authorization = unzer.fetchAuthorization('s-pay-xyz');
Cancel cancel = authorization.cancel();
Error handling
Requests to the API can result in an error that should be handled. Refer to Error handling guide to learn more about Unzer API (and other) errors and how to manage them.
Content security policy (CSP)
Content security policy (CSP)If you are using a Content Security Policy (CSP) you will need to include following URLs to your policy, which are required by the UI components to work.
URLs and Directives
URL | Directives | Description |
---|---|---|
https://static.unzer.com | font-src ,img-src , style-src , script-src | This is the domain used to include .js and .css files of UI components. In addition it is a source for images and fonts.For style-src you need to add 'unsafe-inline' as well. |
https://api.unzer.com | connect-src | This is the Unzer Payment API domain used by UI components for API calls with the public key. |
https://payment.unzer.com | frame-src , connect-src | This is the domain used to include card frames and embedded payment page. |
https://h.online-metrix.net * | frame-src , connect-src , script-src , img-src , worker-src | This is the domain used to include ThreatMetrix script/iframe when using Paylater payment methods and passing along a unique session ID. For more details see Add the ThreatMetrix script. |
https://pay.google.com * | frame-src , connect-src , script-src , img-src , worker-src | This is the domain used to include Google Pay script when using Google Pay payment method.For more details see Google Pay - Initiate UI component. |
Example CSP
An example CSP header to include Unzer UI components could look like this:
Content-Security-Policy: default-src 'self'; connect-src https://payment.unzer.com https://api.unzer.com; frame-src https://payment.unzer.com; script-src https://static.unzer.com; style-src https://static.unzer.com 'unsafe-inline'; font-src https://static.unzer.com; img-src https://static.unzer.com; object-src 'none'
When using sandbox keys, the payment requests are directed to the sandbox URLs.
To test transactions in the sandbox environment, you must also add the Unzer API/Payment sandbox URLs to the allowlist of your Content Security Policy (CSP). To do this, add new URLs with the existing base URLs and
sbx-
as the prefix (e.g sbx-api.unzer.com
).Test & go live
You should always test your integration before going live.
- First perform test transactions using test data.
- Next, check against Integration checklist and Go-live checklist to make sure that the integration is complete and you’re ready to go live.
Next steps
Check payment methods to start integrating specific payments types.