Integrate using UI Components (v2)

Accept 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.

1. Add UI components to your payment page and create the payment type resource.
2. 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.
3. 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.
4. 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 page

client side

First you need to initiate our UI components library and add the payment form to your payment page.

Initiate UI Components

Load the Unzer JS script

Include 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>

Faster load time

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”

Content security policy
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

To securely collect payment data from your customer, you need to add the <unzer-payment> component, inside which you insert the needed payment type components.

We recommend putting your submit button inside the <unzer-checkout> element. This will provide automatic handling for enabling/disabling the submit button depending on the current status, and showing/hiding of brand icons.

<unzer-payment
        id="unzer-payment"
        publicKey="s-pub-xyz"
        locale="de-DE">
    <!-- ... Here you will need to add the Unzer payment type tag, so the form UI elements will be inserted -->
    <!--    e.g <unzer-paylater-invoice></unzer-paylater-invoice> -->
</unzer-payment>
<unzer-checkout id='unzer-checkout'>
    <button type="submit" id="yourPaymentButtonId">Pay</button>
</unzer-checkout>

Following parameters need to be passed.

Optional: Customize UI components

Our 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.

<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

For each payment type that you use, you need to create a dedicated payment type resource.
After the submit button is clicked, the payment data are automatically submitted. You will then need to query the unzer-checkout element and handle the response inside its onPaymentSubmit event listener.

// ...
const unzerCheckout = document.getElementById('unzer-checkout');
unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.submitResponse.success) {
        const paymentId = response.submitResponse.data.id;
        // Submit the ID of the created payment type resource to your
        // server side integration to perform the payment transaction.
    } else {
        // 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>
<unzer-checkout id='unzer-checkout'>
    <button type="submit" id="yourPaymentButtonId">Pay</button>
</unzer-checkout>

    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 unzerCheckout = document.getElementById('unzer-checkout');
        unzerCheckout.onPaymentSubmit = (response) => {
            if (response.submitResponse && response.submitResponse.success) {
                const paymentId = response.submitResponse.data.id;
                // Submit the ID of the created payment type resource to your
                // server side integration to perform the payment transaction.
            } else {
                // Handle resource creation error
            }
        };
    }).catch((error) => {
        // Handle any error that might occur during the 
        // loading process and initialization
    });

Step 2: Make a payment

server 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);

Some payment methods require additional resources for the 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 payment

server 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 result

client 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 payments

server 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)

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

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'

Add Unzer API/Payment sandbox URLs to your CSP
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.

1. First perform test transactions using test data.
2. 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.