Embedded Payment Page

The Embedded Payment Page is a website overlay that presents your customer with all of your payment methods.

About the Embedded Payment Page

With the Embedded Payment Page, you don’t have to implement individual payment methods directly on your website. When the customer presses the Pay button, the Unzer API is called and the Embedded Payment Page pop-up opens.

To compare the Embedded Payment Page against other payment page types, go to Accept payments with a payment page.

Example

To see and test an example Embedded Payment Page, go to our demo page.

Demo page
The demo page was created only for demonstration purposes. Don’t use the source code of the demo page to implement the Embedded Payment Page on your website.

Checkout flow

The checkout flow goes like this:

  1. The Embedded Payment Page opens.

  2. The customer selects one of the payment methods that you support.

  3. The customer selects the Pay button.

  4. If the customer selects a redirect payment method:

    4.1 A third-party payment page opens.

    4.2 The customer completes the payment.

    4.3 The customer is redirected back to the returnUrl passed in step 1.

    4.4 You fetch the payment resource and handle the order depending on its status: redirect to success if the call was successful, or show a failure message if there was an error.

  5. If the customer selects another payment method, you need to set up what happens after a successful payment, using the callback function inside the checkout.success().

Supported payment methods

The Embedded Payment Page supports the following payment methods:

Implement the Embedded Payment Page

To implement the Embedded Payment Page on your website, follow the steps below.

Keep your private key safe
Always store your private key securely on the back end, and don’t enable it on the client side.
For details on your keys, go to Authentication.

Optional: Create customers, baskets and metadata resources

Before implementing the Embedded Payment Page, you can create additional resources:

Create a customers resource

Some of the payment methods require additional information about the customer. The customers resource lets you easily submit this information within the payment.

For details on the customers resource, go to Customer.

To use an existing customers resource, add its unique customerId to the resources object in the request body, like this:


{
...
  "resources": {
    "customerId": "s-cst-1"
  },
...
}

If you don’t have an existing customers resource for your customer, you can gather the necessary customer information in one of the following ways:

Customer forms

The customer forms on the Embedded Payment Page display only when there is no existing customers resource for the following payment methods:

Create a baskets resource

The baskets resource contains all product information needed for the requested transaction.

For details on the baskets resource, go to Basket.

To use an existing baskets resource, add its unique basketId to the resources object in the request body, like this:


{
...
  "resources": {
    "customerId": "s-cst-1",
    "basketId": "s-bsk-1"
  },
...
}

Create a metadata resource

The metadata resource lets you add metadata: additional information about the payment itself. For example, you can use the metadata resource to store important information about the payment order.

For details on the metadata resource, go to Metadata.

To use an existing metadata resource, add its unique metadataId to the resources object in the request body, like this:


{
...
  "resources": {
    "customerId": "s-cst-1",
    "basketId": "s-bsk-1",
    "metadataId": "s-mtd-1",
  },
...
}

Step 1: Request a tokenId

Before displaying the Embedded Payment Page, you need to call the Unzer API for a tokenId.

  • You need to request a new tokenId every time your customer checks out.
  • Each tokenId expires after 60 minutes.
  • Each tokenId becomes invalid after a successful payment, or when the customer closes the Embedded Payment Page.

Use the received tokenId in checkout.js to open the Embedded Payment Page on your website.

To request a tokenId, make a POST call to paypage/charge, with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Number / The transaction amount. 100
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
returnURL Yes String / The URL to redirect the customer to after the payment is completed. https://www.unzer.com
orderId No String / A unique order ID that identifies the payment on your side. Order-12
LogoImage No String / Your company logo to show in the Embedded Payment Page’s header. http://www.any.ed/images/page/info-img.png
shopName No String / Your company name to show in the Embedded Payment Page’s header. Any shop name
termsAndConditionUrl No String / Your Terms and Conditions URL to show in the Embedded Payment Page’s footer. https://www.unzer.com
privacyPolicyUrl No String / Your Privacy Policy URL to show in the Embedded Payment Page’s footer. http://www.any.ed/policy
impressumUrl No String / Your impressum URL to show in the Embedded Payment Page’s footer. http://www.any.ed/impressum
customerId No String / The ID of the customers resource to be used. s-cst-1
metadataId No String / The ID of the metadata resource to be used. s-mtd-1
POST https://api.unzer.com/v1/paypage/charge

Body:
{
    "amount": "100",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "orderId": "Order-12",
    "logoImage": "http://www.any.ed/images/page/info-img.png",
    "shopName": "Any shop name",
    "termsAndConditionUrl": "https://www.unzer.com/",
    "privacyPolicyUrl": "http://www.any.ed/policy",
    "impressumUrl": "http://www.any.ed/impressum",
    "resources": {
        "customerId": "s-cst-1",
        "metadataId": "s-mtd-1"
    }
}

Response:
{
    "id": "s-ppg-1234",
    "redirectUrl": "https://payment.unzer.com/v1/paypage/s-ppg-1234",
    ...
}

Property Type Description
id String This is your tokenId.
redirectUrl String A unique Embedded Payment Page URL, where the customer completes the payment.

For more details on the paypage request, go to API requests.

Step 2: Load our JS script

Include Unzer’s checkout.js script on your website.

Always load the script directly from https://static.unzer.com/v1/checkout.js:


<script type="text/javascript" src="https://static.unzer.com/v1/checkout.js"></script>

Step 3: Create a checkout instance

Create a checkout instance, including the tokenId that you received in step 1:


var checkout = new window.checkout(tokenId);

// tokenId looks similar to: "s-ppg-b95baf2c884d1ab23870327f16159aa8163bb7"

Step 4: Handle the customer’s pay action

At the last stage, when a customer checks out with the Embedded Payment Page, implement a function that listens to a click or submit event.

  1. When a customer calls the checkout action, use checkout.init() to initialize the Embedded Payment Page. The init() method returns a Promise.
  2. When the Embedded Payment Page initializes successfully, use checkout.open() to open the payment pop-up dialog, or handle the error with your token.

You can also use these methods for adding your event listener on the followig events:

  • checkout.abort() - an abort action, such as selecting the Close button.
  • checkout.success() - on a payment success.
  • checkout.error() - on an error.

Example code that handles a click on the Pay button:


<button id="embedded-checkout">Pay with Embedded Payment Page</button>


document.getElementById('embedded-checkout').addEventListener('click', function (event) {
  // Initialize the payment page
  checkout.init().then(function() {
    // If successfull, open the dialog
    checkout.open();
    
    // Add your event listeners for abort or success events
    checkout.abort(function() {})
    checkout.success(function(data) {})
    checkout.error(function(error) {})
    
  }).catch(function(error) {
    // Handle error when initialize the payment page
  });
}, false);

Constructors

Constructor Description
checkout(String token, Object options) Initializes a checkout object with a token string. In the object options, you can provide a locale.

Method summary

Type Method Description
Promise checkout.init() Initialize the payment page.
void checkout.open() Open the payment page pop-up window.
void checkout.abort(Function handle) Set your callback function to handle an abort action.
void checkout.success(Function handle) Set your callback function to handle a success action.

Optional: Exclude payment types

If you want to exclude some of the payment types from the Embedded Payment Page, add excludeTypes to your request. Put all payment types you want to exclude from the page in an array, like this:


{
    "amount": "100",
    "currency": "EUR",
        ...
        "excludeTypes": ["paypal", "sepa-direct-debit"],
        ...
}

Customization and localization

You can customize the following elements of the Embedded Payments Page:

  • The Header section
  • The text on the Pay button

Customize the header

To customize the header section, you can choose one of the two possibilities:

  • In step 2, pass the style values to the options object as the second parameter of the checkout method.
  • In step 1, pass a css key to the request body.

Option 1: Pass the style values to the checkout method

This way, you can change the font color and the background color of the header.

Changing font colors
If you change the font color, any text inside the header changes too, for example tagline and shopName. You can’t change only one of these elements.

var options = {
  style: {
    header: {
      backgroundColor: '000', // for black color
      fontColor: 'fff', // for white color
    }
  }
}
var checkout = new window.checkout('s-ppg-xxx', options);

Color format
When changing backgroundColor or fontColor, use only hex color values without # before the color code.
For example, use fff for white.

Option 2: Pass a CSS object to the request body

Another way to customize the header is to pass a css object to the body of the request.

This option is more flexible and lets you select individual elements.

For the Embedded Payment Page, you can pass values for:

  • header
  • tagline
  • shopName

For each element, you can change:

  • backgroundColor
  • fontColor
  • fontSize.

To use this option, in step 1 add the css object to the request body, like this:


Body:
{
  ...
  "css": {
    "shopDescription": "color: #cacaca",
    "header": "background-color: black",
    "shopName": "color: #fff; font-size: 24px",
    "tagline": "color: green; font-size: 10px",
    "helpUrl": "color: blue; font-size: 12px",
    "contactUrl": "color: rgb(230, 185, 64)",
    "invoiceId": "color: rgb(230, 185, 64)",
    "orderId": "color: rgb(230, 185, 64)",
    "backToMerchantLink": "color: rgb(230, 185, 64)"
  }
  ...
}

Tips on customizing backend CSS
  • When creating CSS that you send to the backend, use vanilla CSS with camelCase in the names of the keys.
  • If you send several values for an individual element, separate these values with a colon ;.
  • We recommend testing the UI changes for all device sizes, especially when passing font-size values.
  • When you pass styles for the same element through the checkout method and the css object, the styles from the css object prevail.

Customize the Pay button

You can change the text inside the Pay button. To customize the Pay button, pass a value to the options object as the second parameter of the checkout method, like this:


var options = {
  style: {
    payButton: {
      intent: 'Subscribe',
    }
  }
}
var checkout = new window.checkout('s-ppg-xxx', options);

Parameter name Example Description
intent buy Changes the text on the Pay button.
Default value:
Pay

Accepted values:
Checkout
Buy
Donate
Book
Subscribe
Format of the intent values
The intent values are case insensitive.

Customize the language

We support localization, which means that you can create your pages in different languages.

To localize your page, pass a locale value as the second argument to the checkout method. When the locale value is set to auto, the language of the customer’s browser is read, and if supported by Unzer, your page is translated to this language.

If you pass another language value, this language is always selected, regardless of the browser’s language.


// Setting the page to always load in German language
var checkout = new window.checkout('s-ppg-xxx', {locale: 'de-DE'});

Supported languages

Parameter name Example Description
locale de or de-DE Default value: auto
English: en
German: de
Czech: cs
Spanish: es
French: fr
Croatian: hr
Hungarian: hu
Italian: it
Dutch: nl
Polish: pl
Portuguese: pt
Romanian: ro
Slovakian: sk
Turkish: tr

Accepted formats:
2-letter locale
4-letter locale with a - separator.
Format of the locale values
The locale values are case insensitive.