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.
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:
-
The Hosted Payment Page opens.
-
If
basketId
was provided, the customer double-checks the list of items in the basket. -
The customer selects one of the payment methods that you support.
-
The customer selects the Pay button.
-
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. -
If the customer selects another payment method, they are redirected to the
returnUrl
.
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:
- 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.
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:
- 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.
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.
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:
- The page header.
- The
shopDescription
element, located under the header. - 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.
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:
- The font color and background color of the
header
. - The font color of the
shopDescription
.
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. |
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)"
}
...
}
- 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 thecss
object, the styles from thecss
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:
- Make a
paypage
call. - From the response, take the
redirectUrl
. - Add the customization parameters to the
redirectUrl
. - 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. |