Hosted Payment Page

The Hosted Payment Page is a webpage hosted by Unzer that presents your customer with all of your payment methods.

About the Hosted Payment Page

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

The Hosted Payment Page is fully responsive, and its user interface can be customized. You can change the images, colors and text, and hide the basket items from the page.

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

Example

To see and test an example Hosted 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 Hosted Payment Page on your website.

Checkout flow

The checkout flow goes like this:

  1. The Hosted Payment Page opens.

  2. If basketId was provided, the customer double-checks the list of items in the basket.

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

  4. The customer selects the Pay button.

  5. If the customer selects a redirect payment method:

    5.1 A third-party payment page opens.

    5.2 The customer completes the payment.

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

    5.4 You fetch the payment resource using the GET method, 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.

  6. If the customer selects another payment method, they are redirected to the returnUrl.

Return URL
We recommend that the returnUrl redirects to a success page hosted on your website.

Supported payment methods

The Hosted Payment Page supports the following payment methods:

Implement the Hosted Payment Page

The Hosted Payment Page is the easiest to implement among all the Unzer’s payment methods. To implement the Hosted Payment Page, 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 Hosted 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 Hosted 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.

If you want to display all basket items, before you redirect the customer to the Hosted Payment Page, you need to create a valid basketId.

For details on the baskets resource, go to Basket.

Mandatory basket

The following payment methods need a basket for correct validation:

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

{
...
  "resources": {
        "basketId": "s-bsk-1",
        "customerId": "s-cst-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": {
        "basketId": "s-bsk-1",
        "customerId": "s-cst-1",
        "metadataId": "s-mtd-1",
    },
...
}

Step 1: Make a paypage call

To display the Hosted Payment Page to your customer, you need to call the Unzer API for:

  • tokenId
  • redirectUrl.

The redirectUrl is a unique Hosted Payment Page URL, where the customer completes the payment.

The tokenId works in the following way:

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

To request a tokenId and a redirectUrl, 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
fullPageImage No String / The URL of the image to show in the Hosted Payment Page’s background. https://www.any.ed/photos/302743/pexels-photo-302743.jpeg
shopDescription No String / Main description of the purchase. Your purchase has never been better.
logoImage No String / Your company logo to show in the Hosted Payment Page’s header. If not provided, shopName shows instead. http://www.any.ed/images/page/info-img.png
tagline No String / A short description to show in the Hosted Payment Page’s header. Established 1864
shopName No String / Your company name to show in the Hosted Payment Page’s header. Any shop name
helpUrl No String / The URL of the help page to show in the Hosted Payment Page’s header. http://www.any.ed/help
contactUrl No String / The URL of the contact page to show in the Hosted Payment Page’s header. http://www.any.ed/contact
termsAndConditionUrl No String / Your Terms and Conditions URL to show in the Hosted Payment Page’s footer. https://www.unzer.com
privacyPolicyUrl No String / Your Privacy Policy URL to show in the Hosted Payment Page’s footer. http://www.any.ed/policy
impressumUrl No String / Your impressum URL to show in the Hosted Payment Page’s footer. http://www.any.ed/impressum
customerId No String / The ID of the customers resource to be used. s-cst-1
basketId No String / The ID of the baskets resource to be used. s-bsk-1
metadataId No String / The ID of the metadata resource to be used. s-mtd-1

Example request

POST https://api.unzer.com/v1/paypage/charge

Body:
{
  "amount": "100",
  "currency": "EUR",
  "returnUrl": "https://www.unzer.com",
  "orderId": "Order-12",
  "fullPageImage": "https://www.any.ed/photos/302743/pexels-photo-302743.jpeg",
  "shopDescription": "Your purchase has never been better.",
  "logoImage": "http://www.any.ed/images/page/info-img.png",
  "tagline": "Established 1862",
  "shopName": "Company XYZ",
  "helpUrl": "http://www.any.ed/help",
  "contactUrl": "http://www.any.ed/contact",
  "termsAndConditionUrl": "https://www.unzer.com/",
  "privacyPolicyUrl": "http://www.any.ed/policy",
  "impressumUrl": "http://www.any.ed/impressum",
  "resources": {
    "customerId": "s-cst-1",
    "basketId": "s-bsk-1",
    "metadataId": "s-mtd-1"
  }
}

Example response

Response:
{
    "id": "s-ppg-c624589f2e0fec0d4c6d62ac93ab6b15b44f601588b69e52742615a1ee92f77b",
    "redirectUrl": "https://payment.unzer.com/v1/paypage/s-ppg-c624589f2e0fec0d4c6d62ac93ab6b15b44f601588b69e52742615a1ee92f77b",
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "logoImage": "http://www.any.ed/images/page/info-img.png",
    "fullPageImage": "https://www.any.ed/photos/302743/pexels-photo-302743.jpeg",
    "shopName": "Company XYZ",
    "shopDescription": "Your purchase has never been better.",
    "tagline": "Established 1862",
    "css": {},
    "orderId": "ord-UfyQqpZ2xI",
    "termsAndConditionUrl": "https://www.unzer.com/",
    "privacyPolicyUrl": "http://www.any.ed/policy",
    "paymentReference": "",
    "impressumUrl": "http://www.any.ed/impressum",
    "imprintUrl": "",
    "helpUrl": "",
    "contactUrl": "",
    "invoiceId": "inv-9d5fg8ZivF",
    "card3ds": "",
    "billingAddressRequired": "false",
    "shippingAddressRequired": "false",
    "resources": {
        "paymentId": "s-pay-34",
        "customerId": "s-cst-1",
        "basketId": "s-bsk-1",
        "metadataId": "s-mtd-1"
    },
    "action": "CHARGE"
}
Property Type Description
id String This is your tokenId.
redirectUrl String A unique Hosted Payment Page URL, where the customer completes the payment.
amount Number The transaction amount.
currency String The transaction currency, in the ISO 4217 alpha-3 format.
returnUrl String The URL to redirect the customer to after the payment is completed.
logoImage String Your company logo to show in the Embedded Payment Page’s header.
fullPageImage String The URL of the image to show in the Hosted Payment Page’s background.
shopName String Your company name to show in the Hosted Payment Page’s header.
shopDescription String Main description of the purchase.
tagline String A short description to show in the Hosted Payment Page’s header.
css Object An object containing the Hosted Payment Page customization details.
orderId String A unique order ID that identifies the payment on your side.
termsAndConditionUrl String Your Terms and Conditions URL to show in the Hosted Payment Page’s footer.
privacyPolicyUrl String Your Privacy Policy URL to show in the Hosted Payment Page’s footer.
paymentReference String Additional description of the transaction.
impressumUrl String Your impressum URL to show in the Hosted Payment Page’s footer.
imprintUrl String Your imprint URL to show in the Hosted Payment Page’s footer.
helpUrl String The URL of the help page to show in the Hosted Payment Page’s header.
contactUrl String The URL of the contact page to show in the Hosted Payment Page’s header.
invoiceId String Your internal invoice ID.
card3ds Boolean Switches between 3ds and non 3ds card transactions.
billingAddressRequired Boolean Determines whether the customer needs to provide a billing address.
shippingAddressRequired Boolean Determines whether the customer needs to provide a shipping address.
paymentId String The ID of the related payment resource.
customerId String The ID of the customers resource.
basketId String The ID of the related baskets resource.
metadataId String The ID of the related metadata resource.
action String Action to take place.

Request details

For more details on authentication, go to authentication.

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

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 Hosted Payment Page:

Customize the images

On the Hosted Payment Page, you can select some of the images that appear on the Hosted Payment Page. To do that, in step 1, inside the request body, set the following properties:

  • fullPageImage
  • logoImage

Customize the basket images

You can set individual basket images that show on the Hosted Payment Page.

For details on customizing basket images, go to Basket.

Customize the colors

You can customize the colors of the following elements of the Hosted Payment Page:

  1. The page header.
  2. The shopDescription element, located under the header.
  3. For mobile devices only: the backToMerchantLink.

To customize the colors, you can choose one of the two possibilites:

  • Pass the color values as the URL parameters of the redirect URL, or
  • In step 1, pass a css object in the request body.
Customizing colors
Passing a css object in the request body is more versatile and lets you target individual elements of the page.

Option 1: Pass the color values as the URL parameters

You can use this method to change:

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

For details on adding the URL parameters, go to Add the parameters to a URL.

Parameter name Example Description
headerBackgroundColor ffffff or fff Changes the background color of the header.
Acceptable values: only hex color values.
headerFontColor ffffff or fff Changes the font color of the header, that is the header’s links, shopName and tagline.
Acceptable values: only hex color values.
shopDescriptionFontColor ffffff or fff Changes the font color of the shopDescription passed in the body of the JSON file.
Acceptable values: only hex color values.
backToMerchantFontColor ffffff or fff Changes the font color of the backToMerchantLink. This link displays inside the footer, if the returnUrl is passed in the body of the JSON file.
Acceptable values: only hex color values.
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 Hosted Payment Page, you can pass values for:

  • shopDescription
  • header
  • shopName
  • tagline
  • helpUrl
  • contactUrl
  • backToMerchantLink

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:

{
  ...
  "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)",
    "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 text

On the Hosted Payment Page, you can change the shop name, description, and tagline.

To do that, in step 1, inside the request body, set the following properties:

  • shopName
  • shopDescription
  • tagline

Customize the Pay button

You can add the URL parameters to change the text inside the Pay button.

For details on adding the URL parameters, go to Add the parameters to a URL.

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.

Add the parameters to a URL

To add parameters to the redirectUrl, you need to:

  1. Make a paypage call.
  2. From the response, take the redirectUrl.
  3. Add the customization parameters to the redirectUrl.
  4. Redirect the customer to the Hosted Payment Page.

You can add a parameter to the redirectUrl like this:


var redirectUrl = returnData.redirectUrl
redirectUrl += '?shopDescriptionFontColor=fff&payButtonIntent=book'

// redirect the customer to customized Hosted Payment Page
window.location.href = redirectUrl

Your new redirectUrl looks like this:


redirectUrl = "https://payment.unzer.com/v1/paypage/s-ppg-5bcf2ebb8dd9360d98499dbad9c5090ae2f72073be854984951cbdb3ca471588?shopDescriptionFontColor=fff&payButtonIntent=book"

Customize the language

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

To localize your page, pass a locale parameter to the redirectUrl. 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.

For details on adding the URL parameters, go to Add the parameters to a URL.

You can add a locale parameter to the redirectUrl like this:


var redirectUrl = returnData.redirectUrl
// Setting the page to always load in German language
redirectUrl += '?locale=de-DE'

// redirect the customer to customized Hosted Payment Page
window.location.href = redirectUrl

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.