alt

Important information

Please be advised that there will be a scheduled downtime across our API network on November 05 and November 07, 2024. For more information, visit our platform status portal.:
- Scheduled maintenance on November 5, 2024
- Scheduled maintenance on November 7, 2024

Unzer
search
Ctrl+K

    Accept Unzer Installment with server-side-only integration

    Build your own payment form to add Unzer Installment to your checkout page

    icon info
    Unzer Installment is only available with basket v1.

    Overview

    Unzer Installment payment method requires additional data from the customer on the merchant website. This data is used to validate the customer and check if the customer is eligible to buy using the Unzer Installment payment method.

    Before you begin

    Step 1: Fetch all the available installment plans
    server side

    To create payment type Unzer Installment you first need to fetch all available installment plans so the customer can select one of them. The effective interest rate of the monthly installment payments is tied to your merchant configuration.

    GET https://api.unzer.com/v1/types/installment-secured/plans?amount=100&currency=EUR&effectiveInterest=5.99

    $unzer = new Unzer('s-priv-xxxxxxxxxx', SupportedLocale::GERMAN_GERMAN);
$plans = $unzer->fetchInstallmentPlans(amount, 'EUR', effectiveInterestRate, orderDate);

    Unzer Unzer = new Unzer("s-priv-xxxxxxxxxx");
List<InstallmentSecuredRatePlan> rateList = getUnzer().installmentSecuredRates(BigDecimal.TEN, Currency.getInstance("EUR"), effectiveInterestRate, orderDate);

    The response looks similar to the following example:

    {
    "code": "OK",
    "entity": [
        {
            "numberOfRates": 3,
            "dayOfPurchase": "2019-05-13",
            "totalPurchaseAmount": 100,
            "totalInterestAmount": 0.97,
            "totalAmount": 100.97,
            "effectiveInterestRate": 5.99,
            "nominalInterestRate": 1.47,
            "feeFirstRate": 0,
            "feePerRate": 0,
            "monthlyRate": 33.66,
            "lastRate": 33.65,
            "installmentRates": [
                {
                    "amountOfRepayment": 33.17,
                    "rate": 33.66,
                    "totalRemainingAmount": 66.83,
                    "type": "RATE",
                    "rateIndex": 1,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 33.34,
                    "rate": 33.66,
                    "totalRemainingAmount": 33.49,
                    "type": "RATE",
                    "rateIndex": 2,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 33.5,
                    "rate": 33.65,
                    "totalRemainingAmount": 0,
                    "type": "RATE",
                    "rateIndex": 3,
                    "ultimo": false
                }
            ]
        }
        ...
    ]
}

    Step 2: Create a payment type resource
    server side

    To create the payment type Unzer Installment, you need to send a request to the Unzer API. The response will contain an id , this is later referred to as typeId. You will need this typeId to perform the transaction. As mentioned before bic is optional.

    POST https://api.unzer.com/v1/types/installment-secured

{
  "iban":"DE46940594210000012345",
    "bic": "COBADEFFXXX", 
    "accountHolder": "Max Mustermann", 
    "invoiceDate": "2019-05-13", 
    "invoiceDueDate":"2019-09-11",
    "orderDate": "2019-05-13",
    "numberOfRates": 3,
    "dayOfPurchase": "2019-05-13",
    "totalPurchaseAmount": 100,
    "totalInterestAmount": 0.97,
    "totalAmount": 100.97,
    "effectiveInterestRate": 5.99,
    "nominalInterestRate": 1.47,
    "feeFirstRate": 0,
    "feePerRate": 0,
    "monthlyRate": 33.66,
    "lastRate": 33.65
}

    $selectedPlan = $plans->getPlans()[1];

$ins = new InstallmentSecured($selectedPlan, 'DE46940594210000012345', 'Manuel Weißmann');
$unzer->createPaymentType($ins);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
InstallmentSecuredRatePlan ratePlan = unzer.createPaymentType(ratePlan);

    The response looks similar to the following example:

    {
    "id": "s-ins-5m68opwdspge",
    "method": "installment-secured",
    "recurring": false,
    "geoLocation": {
        "clientIp": "115.77.189.143",
        "countryCode": "VN"
    },
    "iban": "DE4694************2345",
    "bic": "COBADEFFXXX",
    "holder": "Khang Vu",
    "orderDate": "2019-05-13",
    "numberOfRates": "3",
    "dayOfPurchase": "2019-05-13",
    "totalPurchaseAmount": "100",
    "totalInterestAmount": "0.97",
    "totalAmount": "100.97",
    "effectiveInterestRate": "5.99",
    "nominalInterestRate": "1.47",
    "feeFirstRate": "0",
    "feePerRate": "0",
    "monthlyRate": "33.66",
    "lastRate": "33.65",
    "invoiceDate": "2019-05-13",
    "invoiceDueDate": "2019-09-11"
}

    Step 3: Make a payment
    server side

    Other than the mandatory step of creating the payment type resource, you also require a customer and a basket resource for Unzer Installment payments.

    This payment type requires the following workflow:

    1. Fetch the available installment plans and show them to the customer to chose from.
      This is done automatically when creating the payment type in the front end.
    2. Creating the payment type resource using the installment plan details selected by the customer
    3. Performing an authorization transaction to initialize the selected installment plan.
    4. Show the selected installment plan and its conditions to the customer.
    5. Performing a charge transaction after the customer agrees to the conditions.
    6. Perform a shipment transaction to finalize and start the payments

    Create a customer resource

    Do this step only if you didn’t create a customer resource so far on the client side.

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

{
  "birthDate": "1974-10-03",
  "customerId": "info@unzer.com",
  "email": "info@unzer.com",
  "firstname": "Max",
  "lastname": "Mustermann",
  "mobile": "+49123456879",
  "phone": "+49123456789",
  "salutation": "mr",
  "billingAddress": {
    "city": "Berlin",
    "country": "DE",
    "name": "Max Musterfrau",
    "street": "Schöneberger Str. 21a",
    "zip": "10963"
  },
  "shippingAddress": {
    "city": "Berlin",
    "country": "DE",
    "name": "Max Musterfrau",
    "street": "Schöneberger Str. 21a",
    "zip": "10963",
    "shippingType": "equals-billing"
  }
}

    $unzer = new Unzer("s-priv-xxxxxxxxxxx");
$address = (new Address())
            ->setName('Max Mustermann')
            ->setStreet('Schöneberger Str. 21a')
            ->setZip('10963')
            ->setCity('Berlin')
            ->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->createCustomer($customer);

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxxx");
Address address = new Address();
address
  .setName("Max Mustermann")
  .setStreet("Schöneberger Str. 21a")
  .setCity("Berlin")
  .setZip("10963")
  .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);

customer = unzer.createCustomer(customer);

    The response looks similar to the following example:

    {
"id":"s-cst-23e165524229"
}

    The examples show B2C customer creation. For a full description of customer resource for example, updating and handling B2B customers, For a full description of customer resource, refer to the relevant server-side integration documentation page: Manage customer (direct API calls), Manage customer (PHP SDK), Manage customer (Java SDK).

    Create a basket resource

    The basket resource stores information about the purchased products, used vouchers, shipment costs, and the VAT amounts.

    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://static.unzer.com/paypage/static/media/unzer-logo.ee4b3a61.svg",
    "type": "goods"
  } ]
}

    $unzer = new Unzer("s-priv-xxxxxxxxxxx");
$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->createBasket($basket);

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

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

Basket basket = unzer.createBasket(basket);

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

    Make an authorize transaction

    Now, perform an authorize transaction using the InstallmentSecured resource that you created.

    POST https://api.unzer.com/v1/payments/authorize

{
  "amount": 100.0,
  "currency": "EUR",
  "orderId": "Your Order Id",
  "paymentReference": "Test authorize transaction",
  "resources": {
    "basketId": "s-bsk-xxxxxxxxxx",
    "customerId": "s-cst-xxxxxxxxxx",
    "typeId": "s-ins-upbgliswcvry"
  },
  "returnUrl": "https://url.of-your-return-controller.de"
}

    $unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$authorization = new Authorization(100.00, 'EUR', $returnUrl);
$authorization->setOrderId('Your Order Id')
$unzer->performAuthorization($authorization, 's-ins-xxxxxxxxxxx', 's-cst-xxxxxxxxxx', null, 's-bsk-xxxxxxxxxx');

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxxx");
Authorize charge = unzer.authorize(
  100.00,
  Currency.getInstance("EUR"),
  's-ins-xxxxxxxxxxx',
  new URL("https://url.of-your-return-controller.de"),
  "s-cst-xxxxxxxxxxx",
  "s-bsk-xxxxxxxxxxx"
);

    The response looks similar to the following example:

    For a full description of the authorize transaction, please refer to relevant server-side integration documentation page: authorize a payment (direct API calls), Authorize a payment (PHP SDK), Authorize a payment (Java SDK).

    Display the chosen installment plan

    After the authorize transaction is successful, you have to display the information of the chosen installment plan to the customer and display a download link of the PDF supplied in the response. If there was an error during the authorize transaction, display the corresponding customerMessage in the frontend instead.

    You should also display a button which places the order and triggers the Charge transaction when clicked.

    <div>
    <div>
      Total Purchase Amount: <!-- provide the total purchase amount and currency from your Backend integration-->
    </div>
    <div>
      Total Interest Amount: <!-- provide the total interest amount and currency from your Backend integration-->
    </div>
    <div>
        Total Amount: <!-- provide the total amount and currency from your Backend integration-->
    </div>
</div>
<div>
    <strong>Please download your rate plan <a href="<!-- provide the PDF Link from your Backend integration-->">here</a></strong><br/>
</div>
<div id="place_order" class="ui bottom attached primary button" tabindex="0" onclick="<!--trigger a charge transaction in your server-side integration-->">Place order</div>

    Make a charge transaction

    Now, make a charge transaction with the InstallmentSecured resource that you created. With a successful charge transaction, the amount has been prepared to be insured, and a payment resource is created.

    POST: https://api.unzer.com/v1/payments/{payment_ID}/charges

{
  "amount": 100.0,
  "currency": "EUR",
  "orderId": "Your Order Id",
  "paymentReference": "Test charge transaction",
  "resources": {
    "basketId": "s-bsk-xxxxxxxxxx",
    "customerId": "s-cst-xxxxxxxxxx",
    "typeId": "s-ins-xxxxxxxxxx"
  },
  "returnUrl": "https://url.of-your-return-controller.de"
}

    $unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$chargeInstance = new Charge(100.00, 'EUR', $returnUrl);
$chargeInstance->setOrderId('Your Order Id')
  ->setPaymentReference('Test charge transaction');
$transaction = $unzer->performCharge($chargeInstance,'s-ins-xxxxxxxxxxx', 's-cst-xxxxxxxxxx', null, 's-bsk-xxxxxxxxxx');

    Unzer unzer = new Unzer("s-priv-xxxxxxxxxxx");
Charge charge = unzer.charge(
  100.00,
  Currency.getInstance("EUR"),
  's-ins-xxxxxxxxxxx',
  new URL("https://url.of-your-return-controller.de"),
  "s-cst-xxxxxxxxxxx",
  "s-bsk-xxxxxxxxxxx"
);

    The response looks similar to the following example:

    {
  "id": "s-chg-1",
  "isSuccess": true,
  "isPending": false,
  "isError": false,
  "message": {
    "code": "OK"
  },
  "amount": "119.0000",
  "currency": "EUR",
  "date": "2021-06-15 08:24:07",
  "resources": {
    "customerId": "s-cst-33c5b9bef5a7",
    "paymentId": "s-pay-174811",
    "basketId": "s-bsk-41794",
    "metadataId": "",
    "payPageId": "",
    "traceId": "23dc97dac8f55b870c93048d251af12f",
    "typeId": "s-ins-fiqgzhw6j2su"
  },
  "paymentReference": "",
  "processing": {
    "externalOrderId": "8b9718f3-6b5d-40b7-9376-79bf74818cbe",
    "zgReferenceId": "4702417365603530003141093",
    "uniqueId": "31HA07BC811A66C29D3E9AE7ED47A055",
    "shortId": "4876.7184.8553",
    "traceId": "23dc97dac8f55b870c93048d251af12f"
  }
}

    For a full description of the charge transaction, refer to the relevant server-side integration documentation page: Charge a payment (direct API calls), Charge a payment (PHP SDK), Charge a payment (Java SDK).

    Step 4: Check status of the payment
    server side

    Once the Payment is made, you can fetch the Payment details from the Unzer API to handle the Payment according to its status.

    GET https://api.unzer.com/v1/payments/{payment_ID}
{
    "id": "s-pay-1762",
    "state": {
        "id": 0,
        "name": "pending"
    },
    "amount": {
        "total": "119.0000",
        "charged": "119.0000",
        "canceled": "0.0000",
        "remaining": "0.0000"
    },
    "currency": "EUR",
    "orderId": "o932271001622632368",
    "invoiceId": "",
    "resources": {
        "customerId": "s-cst-9d5f19fa17cc",
        "paymentId": "s-pay-1762",
        "basketId": "s-bsk-1582",
        "metadataId": "",
        "payPageId": "",
        "traceId": "059e6c3d3e1174bf53905f9546ef22f2",
        "typeId": "s-ins-u9hir9xkiliz"
    },
    "transactions": [
        {
            "date": "2021-06-02 11:12:49",
            "type": "authorize",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-1762/authorize/s-aut-1",
            "amount": "119.0000"
        },
        {
            "date": "2021-06-02 11:13:00",
            "type": "charge",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-1762/charges/s-chg-1",
            "amount": "119.0000"
        }
    ]
}

    Step 5: Display the payment result
    client side

    Use the information from the Check status of the payment step to display the payment result to your customer.
    This can be the success or error page of your shop. If something went wrong, you can use the client message from the API response and show it to the customer.

    Manage payment
    server side

    For more details on managing Unzer Installment payments, such as refunding them, see Manage Unzer Installment payments.

    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 page.

    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