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.

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.

Supported payment methods

The Hosted Payment Page supports the following payment methods:

• Unzer Bank Transfer
• Unzer Direct Debit
• Unzer Instalment
• Unzer Invoice
• Unzer Prepayment
• Credit Card
• Alipay
• EPS
• Giropay
• iDEAL
• Paypal
• Przelewy24
• SOFORT
• WeChat Pay

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.

Optional: Create customers, baskets and metadata resources

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

• A customers resource, to submit additional information about the customer (required by Unzer Direct Debit Secured, Unzer Invoice Secured and Unzer Instalment).
• A baskets resource, to submit additional information about the product (required by Unzer Instalment).
• A metadata resource, to submit additional information about the payment itself.

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:

• Create the customers resource before calling the Hosted Payment Page.
• Use the built-in customer forms on the Hosted Payment Page.

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.

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 60 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:

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"
}

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:

• Images
• Colors
• UI Text
• Language

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.

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.

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

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)"
  }
  ...
}

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.

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