Unzer Docs

    Integrate using Hosted Payment Page

    Accept payments through a customizable, ready-made payment page hosted on your server.

    Overview

    Hosted Payment Page (HPP) is a ready-made Unzer hosted website containing your payment methods mix. When a customer clicks the Pay button in your online shop, they are redirected to the Hosted Payment Page. They can then make the payment using their desired option. After the payment is completed they are redirected back to your shop.

    Same as with the EPP, using Hosted Payment Page you can support multiple payment methods with one simple integration. The HPP is the easiest way to integrate with Unzer.

    Hosted payment page

    You can check the HPP in action on our demo page.

    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.

    Read this guide for a general overview on how to accept payments with Hosted Payment Page. For a list of all payment methods supported by HPP please check Supported Payment methods. 

    Before you begin

    Check the basic integration requirements.

    How it works

    To integrate payments using HPP you need to perform steps both on client and server side.

    1. First, you need to set up the payment page  – create Customer and Basket resources and  initialize the payment page on the server side.
    2. Using the information form the previous step you can now redirect your customer to the Hosted Payment Page where the payment will take place.
    3. After the payment is made you should check its status on the server side and display the result to the customer on the client side 
    4. You can perform more operations on the server side once the payment has been made – most common example would be cancelling the payment.

    Step 1: Set up the payment page [server side] 

    First you should prepare resources needed when initializing the payment page on the server side – Customer and Basket resource (recommended) as well as Metadata resource (optional).

    Create Customer resource (recommended)

    The customer resource contains information about the customer and is required by card payment method as well as Unzer Invoice Secured, Unzer Direct Debit Secured and Unzer Instalment.

    We recommend that you always provide the customer resource. 

    To use an existing customer resource, you just need its corresponding customerId. 

    If you don’t have an existing customer resource, you can create it on the server side. 

    POST https://api.unzer.com/v1/customers

{
  "lastname": "Mustermann",
  "firstname": "Max",
  "salutation": "mr",
  "customerId": "51222",
  "birthDate": "1970-01-01",
  "email": "info@unzer.com",
  "phone": "+49 6221 - 64 71 100",
  "mobile": "+49 172 123 456",
  "billingAddress": {
    "name": "Max Mustermann",
    "street": "Vangerowstr. 18",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  },
  "shippingAddress": {
    "name": "Max Mustermann",
    "street": "Vangerowstr. 18",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  }
}

    $address = (new Address())
            ->setName('Max Mustermann')
            ->setStreet('Vangerowstr. 18')
            ->setZip('69115')
            ->setCity('Heidelberg')
            ->setCountry('DE');

$customer = (new Customer())
            ->setFirstname('Max')
            ->setLastname('Mustermann')
            ->setSalutation(Salutations::MR)
            ->setCompany('Unzer GmbH')
            ->setBirthDate('1972-12-24')
            ->setEmail('Max.Mustermann@unzer.com')
            ->setMobile('+49 123456789')
            ->setPhone('+49 123456789')
            ->setBillingAddress($address)
            ->setShippingAddress($address);

$unzer= new Unzer('s-priv-xxxxxxxxxx');
$unzer->createCustomer($customer);

    Address address = new Address();
address
  .setName("Max Mustermann")
  .setStreet("Vangerowstr. 18")
  .setCity("Heidelberg")
  .setZip("69115")
  .setCountry("DE");
      
Customer customer = new Customer("Max", "Mustermann");
customer
  .setCustomerId(customerId)
  .setSalutation(Salutation.mr)
  .setEmail("max.mustermann@unzer.com")
  .setMobile("+49123456789")
  .setBirthDate(getDate("12.12.2000"))
  .setBillingAddress(address)
  .setShippingAddress(address);

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
customer = unzer.createCustomer(customer);

    For Unzer Invoice Secured, Unzer Direct Debit Secured, if there is no existing Customer resource, built-in customer forms will be displayed on the Embedded Payment Page. 

    For a full description of customer resource please refer to relevant server-side integration documentation page: Manage customer (direct API calls), Manage customer (PHP SDK), Manage customer (Java SDK).

    Create the Basket resource (recommended)

    Basket resource stores information about the purchased products, used vouchers as well as shipment costs. It is required for Unzer Invoice Secured, Unzer Direct Debit Secured payment methods. We recommend that you always create a Basket resource. 

    POST https://api.unzer.com/v1/baskets

{
  "amountTotalGross" : 200.00,
  "amountTotalDiscount" : 10.00,
  "amountTotalVat" : 33.33,
  "currencyCode" : "EUR",
  "orderId" : "Order-12345",
  "note" : "Test Basket",
  "basketItems" : [ {
    "basketItemReferenceId" : "Item-d030efbd4963",
    "unit" : "m",
    "quantity" : 10,
    "amountDiscount" : 10.00,
    "vat" : 0.2,
    "amountGross" : 200.00,
    "amountVat" : 33.33,
    "amountPerUnit" : 16.667,
    "amountNet" : 166.67,
    "title" : "SDM 6 CABLE",
    "subTitle" : "This is brand new Mid 2019 version",
    "imageUrl" : "https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg",
    "type": "goods"
  } ]
}

    $basketItem = (new BasketItem())
    ->setBasketItemReferenceId('Item-d030efbd4963')
    ->setQuantity(10)
    ->setUnit('m')
    ->setAmountPerUnit(16.667)
    ->setAmountNet(166.67)
    ->setAmountDiscount(10.0)
    ->setVat(0.2)
    ->setAmountGross(200.0)
    ->setAmountVat(33.33)
    ->setTitle('SDM 6 CABLE')
    ->setSubTitle('This is brand new Mid 2019 version')
    ->setImageUrl('https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg')
    ->setType(BasketItemTypes::GOODS);

$basket  = (new Basket())
    ->setAmountTotalGross(200.00)
    ->setCurrencyCode('EUR')
    ->setOrderId('Order-12345')
    ->setNote('Test Basket')
    ->addBasketItem($basketItem);

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$unzer->createBasket($basket);

    BasketItem basketItem = new BasketItem()
  basketItem.setBasketItemReferenceId("Item-d030efbd4963")
  basketItem.setUnit("m")
  basketItem.setQuantity(10)
  basketItem.setAmountDiscount(new BigDecimal("10.0"))
  basketItem.setVat(new BigDecimal("0.2"))
  basketItem.setAmountGross(new BigDecimal("200.00"))
  basketItem.setAmountVat(new BigDecimal("33.33"))
  basketItem.setAmountPerUnit(new BigDecimal("16.667"))
  basketItem.setAmountNet(new BigDecimal("166.67"))
  basketItem.setTitle("SDM 6 CABLE")
  basketItem.setSubTitle("This is brand new Mid 2019 version")
  basketItem.setImageUrl("https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg")
  basketItem.setType("goods");

Basket basket = new Basket()
  basket.setAmountTotalGross(new BigDecimal("200.00"))
  basket.setAmountTotalDiscount(new BigDecimal("10.00"))
  basket.setAmountTotalVat(new BigDecimal("33.33"))
  basket.setCurrencyCode(Currency.getInstance("EUR"))
  basket.addBasketItem(basketItem)
  basket.setOrderId("Order-12345")
  basket.setNode("Test Basket");

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Basket basket = unzer.createBasket(basket);

    For a full description of basket resource please refer to relevant server-side integration documentation page: Manage basket (direct API calls), Manage basket (PHP SDK), Manage basket (Java SDK).

    Step 2: Initialize payment page [server side]

    Now you can combine the resources with the data about the transaction (amount, currency) and payment page configuration options (return url, shop name & logo, etc.) to make an initialization call for the payment page.  

    You can initialize the payment page to support either charge or authorize transactions. For a description of charge and authorize transactions please refer to relevant server-side integration documentation page: Manage API resources (direct API calls), Manage API resources (PHP SDK), Manage API resources (Java SDK).

    Option 1: Initialize payment page for the Charge transaction 

    In this case charge transaction will be used during the payment process. Most of the payment methods support charge transaction. You can see the full list on the Payment methods page.

    Please note that only payment methods supporting charge transaction, included in your contract will be shown.

    You should save the paymentId and redirectURL contained in paypage call response. The redirectUrl is a unique Hosted Payment Page URL, where the customer completes the payment and the paymentId will be needed to check the payment later.  

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

{
    "amount": "100",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "orderId": "Order-12",
    "invoiceId": "shop-invoice-id",
    "logoImage": "http://www.any.ed/images/page/info-img.png",
    "shopName": "Any shop name",
    "tagline": "Any tagline",
    "resources": {
        "customerId": "s-cst-1",
        "basketId" : "s-bsk-1",
        "metadataId": "s-mtd-1"
    }
}

    $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');

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$unzer->initPayPageCharge($paypage, $customer, $basket);

    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");

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

    The response looks similar to the following example:

    {
    "id": "s-ppg-8bb3eee8681cb2a7ff5cc3e0db5580d3a8a7ccf593538a470e70bb7af5682f52",
    "redirectUrl": "https://sbx-payment.heidelpay.com/v1/paypage/s-ppg-8bb3eee8681cb2a7ff5cc3e0db5580d3a8a7ccf593538a470e70bb7af5682f52",
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "logoImage": "https://dev.unzer.com/wp-content/uploads/2020/09/Unzer__PrimaryLogo_Raspberry_RGB.png",
    "fullPageImage": "",
    "shopName": "Any shop name",
    "shopDescription": "",
    "tagline": "Any tagline",
    "css": {},
    "orderId": "Order-12",
    "termsAndConditionUrl": "",
    "privacyPolicyUrl": "",
    "paymentReference": "",
    "impressumUrl": "",
    "imprintUrl": "",
    "helpUrl": "",
    "contactUrl": "",
    "invoiceId": "",
    "card3ds": "",
    "billingAddressRequired": "false",
    "shippingAddressRequired": "false",
    "resources": {
        "paymentId": "s-pay-173808",
        "customerId": "s-cst-1",
        "basketId": "s-bsk-1",
        "metadataId": "s-mtd-1"
    },
    "action": "CHARGE"
}

    For a complete list of parameters, see the API Reference for a full list of parameters.

    Option 2: Initialize payment page for the Authorize transaction

    In this case authorize transaction will be used during the payment process. Check Payment methods page to see what payment methods support it. 

    You should save the paymentId and redirectURL contained in paypage call response. The redirectUrl is a unique Hosted Payment Page URL, where the customer completes the payment and the paymentId will be needed to check the payment later.  

    For Unzer Instalment you need to provide the effectiveInterestRate parameter in the Authorize call.
    POST https://api.unzer.com/v1/paypage/authorize

{
    "amount": "100",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "orderId": "Order-12",
    "invoiceId": "shop-invoice-id",
    "logoImage": "http://www.any.ed/images/page/info-img.png",
    "shopName": "Any shop name",
    "tagline": "Any tagline",
    "additionalAttributes": {
      "effectiveInterestRate": 4.99
    },
    "resources": {
        "customerId": "s-cst-1",
        "basketId" : "s-bsk-1",
        "metadataId": "s-mtd-1"
    }
}

    $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');
    ->setEffectiveInterestRate(4.99); // Needed for Unzer Instalment
    
$unzer->initPayPageAuthorize($paypage, $customer, $basket, $metadata);

    [not supported by Java SDK at the moment]

    The response looks similar to the following example:

    {
    "id": "s-ppg-bf1d82a8c3ed53ae81c689a6fd747b8f2910400d7998868dba3590a32d92ba64",
    "redirectUrl": "https://unzer.com/v1/paypage/s-ppg-bf1d82a8c3ed53ae81c689a6fd747b8f2910400d7998868dba3590a32d92ba64",
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "logoImage": "https://dev.unzer.com/wp-content/uploads/2020/09/Unzer__PrimaryLogo_Raspberry_RGB.png",
    "fullPageImage": "",
    "shopName": "Any shop name",
    "shopDescription": "",
    "tagline": "Any tagline",
    "css": {},
    "orderId": "Order-12",
    "termsAndConditionUrl": "",
    "privacyPolicyUrl": "",
    "paymentReference": "",
    "impressumUrl": "",
    "imprintUrl": "",
    "helpUrl": "",
    "contactUrl": "",
    "invoiceId": "",
    "card3ds": "",
    "billingAddressRequired": "false",
    "shippingAddressRequired": "false",
    "resources": {
        "paymentId": "s-pay-173809",
        "customerId": "s-cst-1",
        "basketId": "s-bsk-1",
        "metadataId": "s-mtd-1"
    },
    "action": "AUTHORIZE"
}

    For a full list of parameters, see API Reference for a full list of parameters.

    • You need to request a new payment page every time your customer pays. That also includes failed transactions.
    • Each payment page expires after 60 minutes. 
    • Each payment page becomes invalid after a successful payment.
    • Each payment page becomes invalid if an unrecoverable error occurs. i.e. payment type creation successful but payment transaction failed.

    Optional: Exclude payment methods

    If you want to exclude some of the payment methods from the Embedded Payment Page, add the arrayexcludeTypes when initializing on the server side. Put all payment types you want to exclude from the page in an array: 

    POST https://api.unzer.com/v1/paypage/{authorize|charge}
Body:
{
  ...
  "excludeTypes": ["paypal", "sepa-direct-debit"],
  ...
}

    ...
$paypage->setExcludeType(['paypal', 'sepa-direct-debit']);
...

    ...
String[] excludeTypes = {"paypal", "sepa-direct-debit"};
paypage.setExcludeTypes(excludeTypes);
...

    For a list of all possible excludeTypes array values, see Payment methods.

    Step 3: Forward the customer to the Hosted Payment Page

    After you initialized the Hosted Payment Page resource, implement the following flow:

    1. Forward the customer to the redirectUrl returned in the response to your initialization request.
    2. The customer is forwarded to the Hosted Payment Page.
    3. After a successful payment or abort on the Hosted Payment Page, the customer is redirected to the returnURLspecified in the initialization call in step 2.

    Step 4: Check payment status [server side]

    Once the payment is done, the customer will be redirected back to returnURL, that you set in Step 1. Now you can fetch the payment and check its status. Check all possible payment states here.

    GET https://api.unzer.com/v1/payments/{payment_ID}
Response: 
{
    "id": "s-pay-131937",
    "state": {
        "id": 1,
        "name": "completed"
    },
    "amount": {
        "total": "20.0000",
        "charged": "20.0000",
        "canceled": "0.0000",
        "remaining": "0.0000"
    },
    "currency": "EUR",
    "orderId": "",
    "invoiceId": "",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-131937",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "70ddf3152a798c554d9751a6d77812ae",
        "typeId": "s-eps-grpucjmy5zrk"
    },
    "transactions": [
        {
            "date": "2021-05-10 00:51:03",
            "type": "charge",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-131937/charges/s-chg-1",
            "amount": "20.0000"
        }
    ]
}
    You should handle the status according to the payment method used by the customer.

    Notifications

    We recommend subscribing to the payment event to receive notifications about any changes to the payment resource. As soon as the event is triggered you should fetch the payment and update the order status in your shop according to its status.

      {
    "event":"payment.pending",
    "publicKey":"s-pub-xxxxxxxxxx",
    "retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
    "paymentId":"s-pay-774"
  }

    For more details on implementing Webhooks to receive notifications, see Notifications.

    Step 5: Display payment result [client side] 

    After the transaction is made you should display its result to the customer in the front end using the information from previous step. 

    Keep in mind that depending on the payment method used, information relevant for the customer  as a part of the success/error message can differ. E.g., for Unzer Invoice, Unzer Invoice Secured and Unzer Prepayment you should display payment details to the customer. 

    Localization 

    We support localization with locale option parameters. Please check the Localisation page on supported locales.

    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.

    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

    Customization 

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

    • Images
    • Colors
    • UI text

    Customize the images

    You can define some of the images that appear on the Hosted Payment Page. To do that, set the following properties when initializing the payment page in Step 2:

    • fullPageImage
    • logoImage
    POST https://api.unzer.com/v1/paypage/{authorize|charge}

{
  ...
  "fullPageImage": "https://full-page-image-url",
  "logoImage": "https://logo-image-url",
  ...
}


    ...
$paypage->setFullPageImage('https://full-page-image-url')
$paypage->setLogoImage('https://logo-image-url')
...


    ...
paypage.setFullPageImage('https://full-page-image-url')
paypage.setLogoImage('https://logo-image-url')
...

    Customize the basket images

    You can set individual basket images that show on the Hosted Payment Page. Check the Basket resource documentation page for details: Manage basket (direct API calls), Manage basket (PHP SDK), Manage basket (Java SDK).

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

    • Pass the color values as the URL parameters of the redirectURL
    • pass a CSS object when initializing payment page in Step 2

    Passing a CSS object 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.
    • The font color of the backToMerchantLink

    You must change all the three elements together for links, tagline and shopName. You can’t change only one of these elements.

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

    Parameter Description Example value
    headerBackgroundColor Changes the background color of the header.
    Acceptable values: only hex color values.    		 ffffff or fff
    headerFontColor Changes the font color of the header, that is the header’s links, shopName and tagline.
    Acceptable values: only hex color values.
    shopDescriptionFontColor Changes the font color of the shopDescription passed in the body of the JSON file.
    Acceptable values: only hex color values.
    backToMerchantFontColor 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 when initializing payment page

    Another way to customize the HPP is to pass a CSS object. 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, add the CSS object when initializing payment page in Step 2: 

    POST https://api.unzer.com/v1/paypage/{authorize|charge}

{
  ...
    "css": {
      "shopName": "color: #fff; font-size: 24px",
      "tagline": "color: green; font-size: 10px"
    },
  ...
}

    ...
$styles = [
  'shopName' => 'color: #fff; font-size: 24px',
  'tagline' => 'color: green; font-size: 10px',
];
$paypage->->setCss($styles);
...

    ...
Map<String, String> cssMap = new HashMap<String, String>();
cssMap.put("tagline", "color: blue; font-size: 30px");
cssMap.put("shopName", "color: blue; font-size: 30px");

    paypage.setCss(cssMap);
…

    • 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 semicolon ;.
    • 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 latter takes precedence. 

    Customize the text

    On the Hosted Payment Page, you can customize the shop name, description, and tagline. To do that, in Step 2 set the following properties:

    • shopName
    • shopDescription
    • tagline
    POST https://api.unzer.com/v1/paypage/{authorize|charge}

{
  ...
  "shopName": "Any shop name",
  "shopDescription": "Any shop description",
  "tagline": "Any tagline",
  ...
}

    ...
$paypage->setShopName('Any shop name'');
$paypage->setShopDescription('Any shop description'');
$paypage->setTagline('Any tagline'');
...

    ...
paypage.setShopName("Any shop name");
paypage.setShopDescription("Any shop description");
paypage.setTagline("Any tagline");
...

    Customize the Pay button

    You can add the URL parameters to change the text inside the Pay button. Accepted intent parameter values: Pay (default), Checkout, Buy, Donate, Book, Subscribe 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. Initialize the payment page
    2. Take the returned redirectUrl.
    3. Add the customization parameters to the redirectUrl.

    Following is an example of one of the ways to modify the redirectURL using JavaScript.

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

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

    Manage payment

    After you have made a transaction, you can perform additional operations on it. A common example is the cancel operation which can be done for most of the payment methods.

    Cancel before money receipt (reversal)

    To reduce or cancel a reservation on the customer account you need to perform a Cancel on the initial transaction. An example of reversal would be unblocking reserved amount on customer account after he/she returned a rented car. 

    POST https://api.heidelpay.com/v1/payments/s-pay-1/authorize/cancels

{
  "amount" : "100.00"
}

    $unzer = new Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$unzer->cancelAuthorizationByPayment($payment, 100.00);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Authorization authorization = unzer.fetchAuthorization('s-pay-1');
Cancel cancel = authorization.cancel();

    The response looks similar to the following example:

    {
  "id": "s-cnl-1",
  "isSuccess": true,
  "isPending": false,
  "isError": false,
  "card3ds": false,
  "message": {
    "code": "COR.000.100.112",
    "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
    "customer": "Your payments have been successfully processed in sandbox mode."
  },
  "amount": "100.0000",
  "currency": "EUR",
  "date": "2021-06-10 10:47:43",
  "resources": {
    "customerId": "",
    "paymentId": "s-pay-1",
    "basketId": "",
    "metadataId": "",
    "payPageId": "",
    "traceId": "d9763d2fdd7830bdd73f76957423f351",
    "typeId": "s-crd-e6f2yo8ggwhg"
  },
  "paymentReference": "",
  "processing": {
    "uniqueId": "31HA07BC8174FCB9564077FB19AEF03B",
    "shortId": "4872.4846.3345",
    "traceId": "d9763d2fdd7830bdd73f76957423f351"
  }
}

    Cancel after money receipt (refund)

    To refund a payment you need to perform a cancel on a successful charge transaction. This transfers the money back to the customer. 

    POST https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-1/cancels
{
  "amount" : "12.450",
  "paymentReference": "Test cancel transaction"
}

    $unzer= new Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel();

    Unzer unzer = new Unzer(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
Charge charge = unzer.fetchChargeById("s-pay-1", "s-chg-1");
Cancel cancel = charge.cancel();

    Error handling

    All requests to the API can result in an error that should be handled. Refer to the Error handling guide to learn more about Unzer API (and other) errors and handling them.

    Test & go live

    You should always test your integration before going live. First perform test transactions using test data. Next, check against Integration checklist and Go-live checklist to make sure the integration is complete and you’re ready to go live.

    See also