Migrate to Payment Page v2

Upgrade your payment solutions with Unzer’s latest release—Version 2.0! Here’s why it’s a game-changer:

• Sleek, Modern Design: Say goodbye to the outdated and embrace the new, intuitive interface that makes navigating our system easier than ever.
• New Payment Methods: Expand your payment options with the latest methods, providing flexibility and convenience for your customers.
• Embedded Mode: Seamlessly integrate Unzer into your platform with our redesigned embedded mode, offering a smoother and more cohesive user experience.
• Minimal migration effort: Transition from Version 1.0 to 2.0 with our migration guide.

Feature comparison

Features	Version 2	Version 1
Modern Design
One API endpoint for EPP, HPP and LinkPay
Customization options for every Payment Method
Improved Redirect Handling
Bearer Token Authentication
Define order of payment methods
SDKs which ease integration

General information

The customer and basket creation stay the same and the IDs are passed during the creation of the payment page.

The new payment page creation endpoint will be used for Embedded, Hosted and LinkPay Pages and returns the following:

• paypageId: The ID of the created Payment Page.
• redirectUrl: The URL to which the end customer needs to be redirected (required for Hosted Payment Page and LinkPay only).
• qrCodeSvg: QR code representation of the redirectUrl in SVG format.

This means that instead of storing the paymentId, the paypageId must be stored and used when the customer returns to the merchant shop to verify the payment.

There are a few methods to verify the payment:

• Via a GET call and the paypageId here, which returns paymentId and transaction status.
• Via a GET call and the paymentId, which returns paypageId and payment details same as before
• Via Webhook: There is no change in the webhooks, except that the resources.payPageId should be used to map the paymentId to the paypageId, as it is not initially known.

Payment method mapping list

To make migration easier, we have created a mapping list for excludeTypes to paymentMethodsConfigs.

Migration with SDKs

If you’re using a Java or PHP-based backend, we recommend using our SDKs. They simplify the authorization process for you and automatically handle token refresh.

Check the following pages for the full documentation on our SDKs:

• Hosted Payment Page
• Embedded Payment Page
• LinkPay Page

You can also compare the highlighted changes in the following section:

Create payment page

Note
In the create payment page call, you can now use the type flag to specify whether it’s hosted, embedded, or linkpay page. This applies to charge and authorize as well. If you don’t specify the payment page type, like setting the type to embedded, it defaults to the hosted payment page.

PHP SDK

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$paypage = new Paypage(9.99, 'EUR'); // charge as default type.
//or if authorize is preferred:
//$paypage = new Paypage(9.99, 'EUR', 'authorize');

//it is recommended to add a customer object.
$customer = $unzer->createCustomer(CustomerFactory::createCustomer('Max', 'Mustermann'));

$resources = new Resources($customer->getId(), null, null);

//optionally add a none default config for card payment
$cardConfig = (new PaymentMethodConfig(true, 1))
    ->setCredentialOnFile(true)
    ->setExemption(ExemptionType::LOW_VALUE_PAYMENT);

$methodConfigs = (new PaymentMethodsConfigs())->addMethodConfig(Card::class, $cardConfig)

$paypage->setLogoImage('http://www.any.ed/images/page/info-img.png')
    ->setOrderId('shop-order-id')
    ->setShopName('Any shop name')
    ->setInvoiceId('shop-invoice-id')
    ->setPaymentMethodconfigs($methodConfigs)
    ->setResources($resources);

$unzer->createPaypage($paypage);
// Redirect to the paypage
redirect($paypage->getRedirectUrl());

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$paypage = new Paypage(100.00, 'EUR', 'https://www.unzer.com');

$paypage->setLogoImage('http://www.any.ed/images/page/info-img.png')
    ->setOrderId('shop-order-id')
    ->setShopName('Any shop name')
    ->setTagline('Any tagline')
    ->setInvoiceId('shop-invoice-id')
    ->setExemptionType(\UnzerSDK\Constants\ExemptionType::LOW_VALUE_PAYMENT);

$unzer->initPayPageCharge($paypage, $customer, $basket);

Java SDK

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
PaypageV2 paypage = new PaypageV2(new BigDecimal("9.99"), "EUR");
//or if authorize is preferred:
//PaypageV2 paypage = new PaypageV2(new BigDecimal("9.99"), "EUR", "authorize");

//it is recommended to add a customer object.
Customer customer = unzer.createCustomer(new Customer("Max", "Mustermann"));
Resources resources = new Resources(customer.getId(), null, null);

//optionally add a none default config for card payment
PaymentMethodConfig cardConfig = (new PaymentMethodConfig(true, 1))
        .setCredentialOnFile(true)
        .setExemption(CardTransactionData.ExemptionType.LVP.toString().toLowerCase());

HashMap<String, PaymentMethodConfig> methodConfigs = new HashMap<>()
methodConfigs.put("cards", cardConfig);

paypage.setLogoImage("http://www.any.ed/images/page/info-img.png")
    .setOrderId("shop-order-id")
    .setShopName("Any shop name")
    .setInvoiceId("shop-invoice-id")
    .setPaymentMethodsConfigs(methodConfigs)
    .setResources(resources);

PaypageV2 response = unzer.createPaypage(paypage);
// Redirect to the paypage
String redirectUrl = paypage.getRedirectUrl();

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Paypage paypage = new PayPage();

paypage.setAmount(new BigDecimal("100.00"));
paypage.setReturnUrl("https://www.unzer.com");
paypage.setLogoImage("http://www.any.ed/images/page/info-img.png");
paypage.setOrderId("shop-order-id");
paypage.setShopName("Any shop name");
paypage.setTagline("Any tagline");
paypage.setInvoiceId("shop-invoice-id");
paypage.setAction(Paypage.Action.CHARGE);

Map<String, String> additionalAttributes = new HashMap<>();
additionalAttributes.put("exemptionType", "lvp");
paypage.setAdditionalAttributes(additionalAttributes);

// Initialize the paypage
paypage = unzer.paypage(paypage);

Server side without SDKs

This section describes the new endpoints and mapping of the request. If you integrate directly with our API, you need to manage the access token generation yourself.

• Issue an Access Token
• Create Payment Page
• Optional: Get Payments

Issue an access token (new)

As long as a token is valid, it can be used multiple times for calls to Payment Page API.

To keep the token authentication mechanism safe and secure, there are some measures that need to be taken into account:

1. A requested token is valid for 7 minutes‚ after which it expires, and you need to request a new one.
2. There is a rate limit in place that allows 2 token creations per second.

If you are using one of our SDKs, the token handling is done automatically as long as you are reusing the Unzer instance.

Send an empty POST request for creating the token with basic auth with your merchant private key.

POST https://token.upcgw.com/v1/auth/token

GET https://token.upcgw.com/v1/auth/token

{
  "accessToken": "eyJraWQiOiJhbGlhcy9jb25uZWN0aXZpdHktdjItdG9rZW4ta21zIiwiYWxnIjoiUlMyNTY..."
}

To learn more, go to the Authentication page.

Create a Payment Page resource

Endpoints

• v1 Endpoint: POST https://api.unzer.com/v1/paypage/charge
• v1 Endpoint: POST https://api.unzer.com/v1/paypage/authorize
• v2 Endpoint: POST https://paypage.unzer.com/v2/merchant/paypage

The new create payment page call has a setting to either prefer authorize or charge.

Authorization

A bearer token is needed to authenticate. See the section “Issue an Access Token”.

Mapping fields

The following section describes the mapping of all fields, which are different in v2.

Ensure that all necessary fields from v1 are correctly mapped to their counterparts in v2. Some fields might need to be restructured or placed under new keys.

{
  "paypageId": "string",
  "redirectUrl": "string"
}

Optional: Get payments

Optionally, this endpoint can be called after the payment page is finished and the customer has returned to the shop. It will contain the paymentId, status and information about failures. We recommend this step even though you will also be notified via a webhook. Check Notifications to learn how to use them.

The current status of the payment can be seen in the response.

GET https://paypage.unzer.com/v2/merchant/paypage/{paypageId}
{
  "payments": [
    {
      "paymentId": "s-pay-1",
      "transactionStatus": "success",
      "creationDate": "2024-08-22T14:42:57.944Z",
      "messages": [
        {
          "code": "string",
          "customer": "string",
          "merchant": "string"
        }
      ]
    }
  ],
  "total": 0
}

Hosted Payment Page migration

There is no change on the client site for the hosted payment page. The browser needs to be redirected to the payment page as before. The return URL can now be specified for every different transaction state as shown above. If you want to use a specific locale, you need to adapt the parameter slightly with an & instead of an ?. For example,

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

Embedded Payment Page migration

The most significant change is, that the embedded flag needs to be set during the creation of the payment page with the type attribute now. In contrast to v1, where a flag was attached to the URL.

The changes on the server site depend on your type of integration. Either see the SDK or direct integration above. The client site implementation didn’t change much and are available here: Embedded Payment Page.

See also

• Embedded Payment Page
• Hosted Payment Page
• LinkPay Page