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.

Migration with SDKs

The usage of our SDKs is recommended if a Java or PHP based backend is used. It will simplify the authorization process for you and automatically takes care of the token refresh.

A new version of the Java and PHP SDK is released and available.

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

• Hosted Payment Page
• Embedded Payment Page

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

Create hosted payment page

Note
Hosted, embedded or linkpay is now a flag in the create payment page call. The same is true for charge and authorize.

$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(9.99, 'EUR'); // charge as default type.
//or if authorize is preferred:
//$paypage = new Paypage(9.99, 'EUR', 'authorize');

$paypage->setType("embedded");

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

$resources = new Resources($customer->getId(), null, null);
$paypage->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);

Coming Soon!

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.

Authorization: Basic auth with your merchant private key.

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