Unzer Instalment

Unzer Instalment lets your customers pay in monthly payments.

About Unzer Instalment

With Unzer Instalment, you receive the full amount right away, whereas your customers pay in instalments each month (with additional interest).

Your customers can choose one of several instalment plans. The available instalment plans and interest rates are defined in your Unzer contract.

Unzer Instalment supports the following Unzer API calls:

Constraints
Unzer Instalment supports only the EUR currency.
Unzer Instalment supports only customers from Austria and Germany.

Accept an Unzer Instalment payment

To accept an Unzer Instalment payment, follow the steps below.

When testing, do not use real customer data. Use the Unzer Instalment test data prepared by Unzer.

Step 1: Fetch available instalment plans

After your customer chooses to pay in instalments, you need to show them all available instalment plans.

To fetch all instalment plans for a specific (total) amount, make a GET call with the following parameters:

Parameter Required Type Default Description Example
amount Yes Float / Specifies the total amount to be paid in monthly instalments. 100
currency Yes Currency code / The transaction currency, in the ISO 4217 alpha-3 format. EUR
orderDate No Date Current date Specifies the date of the order. 2019-04-24
effectiveInterest Yes Float 0 Specifies the effective interest rate of the monthly instalment payments. The range is tied to your merchant configuration. 5.99
https://api.unzer.com/v1/types/installment-secured/plans?amount=100&currency=EUR&effectiveInterest=5.99
{
    "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
                }
            ]
        },
        {
            "numberOfRates": 6,
            "dayOfPurchase": "2019-05-13",
            "totalPurchaseAmount": 100,
            "totalInterestAmount": 1.71,
            "totalAmount": 101.71,
            "effectiveInterestRate": 5.99,
            "nominalInterestRate": 2.94,
            "feeFirstRate": 0,
            "feePerRate": 0,
            "monthlyRate": 16.96,
            "lastRate": 16.91,
            "installmentRates": [
                {
                    "amountOfRepayment": 16.47,
                    "rate": 16.96,
                    "totalRemainingAmount": 83.53,
                    "type": "RATE",
                    "rateIndex": 1,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 16.55,
                    "rate": 16.96,
                    "totalRemainingAmount": 66.98,
                    "type": "RATE",
                    "rateIndex": 2,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 16.63,
                    "rate": 16.96,
                    "totalRemainingAmount": 50.35,
                    "type": "RATE",
                    "rateIndex": 3,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 16.72,
                    "rate": 16.96,
                    "totalRemainingAmount": 33.63,
                    "type": "RATE",
                    "rateIndex": 4,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 16.8,
                    "rate": 16.96,
                    "totalRemainingAmount": 16.83,
                    "type": "RATE",
                    "rateIndex": 5,
                    "ultimo": false
                },
                {
                    "amountOfRepayment": 16.88,
                    "rate": 16.91,
                    "totalRemainingAmount": 0,
                    "type": "RATE",
                    "rateIndex": 6,
                    "ultimo": false
                }
            ]
        }
    ]
}
Property Type Description
code String The response code.
numberOfRates Number The total number of instalments.
totalPurchaseAmount Number The total purchase amount.
totalInterestAmount Number The total amount of interest.
effectiveInterestRate Number The effective interest rate.
nominalInterestRate Number The nominal interest rate.
feeFirstRate Number The first instalment’s fee.
monthlyRate Number The amount of each monthly instalment.
lastRate Number The amount of the last instalment.
amountOfRepayment Number The repayment amount paid in this instalment.
rate Number The total amount paid in this instalment.
totalRemainingAmount Number The total amount still to be paid.
type String The type of instalment.
rateIndex Number The instalment’s sequence number.
ultimo Boolean true or false

Step 2: Create customers and basket resources

For security reasons, before you create a types/installment-secured resource, you need to create those resources first:

Create a customers resource

Unzer Instalment requires 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"
  },
...
}

To create a new customers resource, make a POST call with the following parameters in the request body:

Parameter Required Type Default Description Example
lastname Yes String / The customer’s last name. Mustermann
firstname Yes String / The customer’s first name. Max
salutation Yes String / The customer’s honorific. mr
company Yes String / The customer’s company name. unzer GmbH
customerId Yes String / The ID of the customers resource. 51222
birthDate Yes String / The customer’s date of birth. 1970-01-01
email Yes String / The customer’s email address. info@unzer.com
phone Yes String / The customer’s landline phone number. +49 6221 64 71 100
mobile Yes String / The customer’s mobile phone number. +49 172 123 456
name Yes String / The name used in the customer’s billing address. Max Mustermann
street Yes String / The billing address street name and house number. Musterstrasse 15
state Yes String / The billing address state. DE-BW
zip Yes String / The billing address postal code. 69115
city Yes String / The billing address city. Heidelberg
country Yes String / The billing address country. DE
POST https://api.unzer.com/v1/customers

Body:
{
  "lastname": "Mustermann",
  "firstname": "Max",
  "salutation": "mr",
  "company": "Unzer GmbH",
  "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": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  }
}

To see all possible customers parameters, go to Customer.

{
    "id": "s-cst-0ab7c75d8e59"
}
Property Type Description
id String The ID of the customers resource that you just created.

Create a baskets resource

The baskets resource contains all product information needed for the requested transaction.

For details on the baskets resource, go to Basket.

To use an existing baskets resource, add its unique basketId to the resources object in the request body, like this:

{
...
  "resources": {
    "customerId": "s-cst-1",
    "basketId": "s-bsk-1"
  },
...
}

To create a new baskets resource, make a POST call with the following parameters in the reqest body:

Parameter Required Type Default Description Example
amountTotal Yes Number / The total purchase amount. 200.00
amountTotalDiscount Yes Number / The total discount amount. 0.00
amountTotalVat Yes Number / Thet total amount of VAT. 0.00
currencyCode Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
orderId Yes String / The ID of the order. 136d24be-12b0
note Yes String / A note about the transaction. merchantwebshop.com basket for masterpass
basketItemReferenceId Yes String / The ID of the related baskets resource. xxxxx
unit Yes String / The unit of basket items. Pc.
quantity Yes Integer / The quantity of basket items. 2
amountDiscount Yes Number / The basket discount amount. 100.00
vat Yes Number / The basket percentage of VAT. 0
amountGross Yes Number / The basket gross amount. 200.00
amountVat Yes Number / The basket amount of VAT. 0
amountPerUnit Yes Number / The amount per basket item. 100.00
amountNet Yes Number / The basket net amount. 200.00
title Yes String / The name of the basket product(s). Macbook pro
type Yes String / The type of basket product(s). goods
subTitle Yes String / A description of the basket product(s). This is brand new Mid 2019 version
imageUrl Yes String / The basket product(s) image URL. https://www.unzer.com/file.svg
POST https://api.unzer.com/v1/baskets

Body:
{
  "amountTotal": 200.00,
  "amountTotalDiscount": 0.00,
  "amountTotalVat": 0.00,
  "currencyCode": "EUR",
  "orderId": "136d24be-12b0",
  "note": "merchantwebshop.com basket for masterpass",
  "basketItems": [
    {
      "basketItemReferenceId": "xxxxx",
      "unit":"Pc.",
      "quantity": 2,
      "amountDiscount": 100.00,
      "vat": 0,
      "amountGross": 200.00,
      "amountVat": 0,
      "amountPerUnit": 100.00,
      "amountNet": 200.00,
      "title": "Macbook pro",
      "type": "goods",
      "subTitle": "This is brand new Mid 2019 version",
      "imageUrl": "https://www.unzer.com/typo3conf/ext/Unzer_site/Resources/Public/Images/Unzer-Logo_weiss.svg"
    }
  ]
}

To see all possible baskets parameters, go to Basket.

{
    "id":"s-bsk-1"
}
Property Type Description
id String The ID of the baskets resource that you just created.

Step 3: Create an installment-secured resource

After creating the customers and baskets resources, create an Unzer Instalment resource: types/installment-secured.

Make a POST call to types/installment-secured with the following parameters in the request body:

Parameter Required Type Default Description Example
iban For Shipment String / The customer’s IBAN. DE46940594210000012345
bic For Shipment String / The customer BIC. COBADEFFXXX
accountHolder For Shipment String / The name of the account holder. Manuel Weißmann
invoiceDate For Shipment String / The day the invoice is issued (in the following date format: yyyy-MM-dd). 2019-05-13
invoiceDueDate For Shipment String / The day the invoice payment is due (in the following date format: yyyy-MM-dd). 2019-09-11
orderDate For Shipment String / The day the order is issued (in the following date format: yyyy-MM-dd). 2019-05-13
numberOfRates Yes Integer / The number of rates to be paid. 3
dayOfPurchase Yes String / The day of the purchase (in the following date format: yyyy-MM-dd). 2019-05-13
totalPurchaseAmount Yes Number / The total purchase amount (as currency amount). 100
totalInterestAmount Yes Number / The total interest amount (as currency amount). 0.97
totalAmount Yes Number / The total amount (as currency amount). 100.97
effectiveInterestRate Yes Number / The total interest rate (as percentage). 5.99
nominalInterestRate Yes Number / The nominal interest rate (as percentage). 1.47
feeFirstRate Yes Number / A fee for the first rate (as currency amount). 0
feePerRate Yes Number / A fee per rate (as currency). 0
monthlyRate Yes Number / The monthly rate to be paid (as currency amount). 33.66
lastRate Yes Number / The last rate to be paid (as currency amount). 33.65
POST https://api.unzer.com/v1/types/installment-secured

Body:
{
    "iban":"DE46940594210000012345",
    "bic": "COBADEFFXXX", 
    "accountHolder": "Manuel Weißmann", 
    "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
}
{
    "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"
}
Property Type Description
id String The ID of the resource that you just created.
method String The payment method.
recurring Boolean Indicates if this is a recurring payment.
clientIp String The IP address of the device used for the payment.
countryCode String The country associated with clientIp, displayed in the ISO 3166-1 alpha-2 format.
iban String The customer’s IBAN.
bic String The customer BIC.
holder String The account holder’s name.
orderDate String The date of the order.
numberOfRates Integer The total number of instalments.
dayOfPurchase String The day of purchase.
totalPurchaseAmount Number The total purchase amount.
totalInterestAmount Number The total interest amount.
totalAmount Number The total amount.
effectiveInterestRate Number Effective interest rate.
nominalInterestRate Number Nominal interest rate.
feeFirstRate Number The first instalment’s fee.
feePerRate Number Fee per instalment.
monthlyRate Number Montly instalment amount.
lastRate Number Last instalment amount.
invoiceDate String The date of the invoice.
invoiceDueDate String The invoice due date.

Optional: Update the types/installment-secured resource

To update an existing types/installment-secured resource, make a PUT call with the payment-method-id of the resource that you want to update:

PUT https://api.unzer.com/v1/types/installment-secured/{payment_method_id}

Body:
{
    "iban":"DE89370400440532013000",
    "bic": "COBADEFFXXX", 
    "accountHolder": "Manuel Weißmann", 
    "invoiceDate": "2019-05-13", 
    "invoiceDueDate":"2019-09-11",
    "orderDate": "2019-05-13"
}

Step 4: Authorize the full amount

With Unzer Instalment, you can’t charge the customer directly. You need to authorize the full amount first.

To authorize the full amount, make a POST call with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Number / The authorized amount. 12.20
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. http://www.unzer.com/returnUrl
orderId Yes String / A unique order ID that identifies the payment on your side. payment-order-1557751911319-685
effectiveInterestRate Yes Float / The total interest rate (as percentage). 5.99
typeId Yes String / The ID of the Payment types resource to be used. s-ins-5m68opwdspge
customerId Yes String / The ID of the customers resource to be used.
The related Customer resource must contain at least firstname, lastname, company, birthDate, email and billingAddress.
s-cst-f63654a8d1da
basketId Yes String / The ID of the basket resource to be used.
Don’t use Discount, as Unzer Instalment doesn’t support it.
s-bsk-1192
POST https://api.unzer.com/v1/payments/authorize

Body:
{
  "amount" : "100.97",
  "currency" : "EUR",
  "returnUrl": "http://www.unzer.com/returnUrl",
  "orderId": "payment-order-1557751911319-685",
  "effectiveInterestRate": 5.99,
  "resources" : {
    "typeId" : "s-ins-5m68opwdspge",
    "customerId": "s-cst-f63654a8d1da",
    "basketId": "s-bsk-1192"
  }
}

To see all possible Authorize parameters, go to Authorize.

{
    "id": "s-aut-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "OK"
    },
    "amount": "100.9700",
    "currency": "EUR",
    "returnUrl": "http://www.unzer.com/returnUrl",
    "date": "2019-05-13 12:51:52",
    "resources": {
        "customerId": "s-cst-f63654a8d1da",
        "paymentId": "s-pay-3059",
        "basketId": "s-bsk-1192",
        "typeId": "s-ins-5m68opwdspge"
    },
    "orderId": "payment-order-1557751911319-685",
    "processing": {
        "iban": "DE4694************3000",
        "bic": "COBADEFFXXX",
        "externalOrderId": "eac0fe4a-7894-4e06-866b-7473842b4819",
        "uniqueId": "",
        "holder": "Manuel Weißmann",
        "PDFLink": "https://test-Unzer-dm.hpcgw.net/sdm-services/api/Unzer/hirepurchase/31HA07BC8189F478C189126BA0ABB084/download/aDNpZDNscEB5X3MzY3IzdGVhYzBmZTRhLTc4OTQtNGUwNi04NjZiLTc0NzM4NDJiNDgxOQ=="
    }
}
Property Type Description
id String The authorization’s unique ID.
isSuccess Boolean Indicates if the transaction was successful.
isPending Boolean Indicates if the transaction is still pending.
isError Boolean Indicates if there was an error.
code String A unique ID of the message.

For details, go to Error code structure.
amount String The authorization 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.
date String Date and time of the authorization.
customerId String The ID of the customers resource.
paymentId String The ID of the related payment resource.
basketId String The ID of the related baskets resource.
typeId String The newly-created payment type ID that you received in response to creating an installment-secured resource (Step 1).
orderId String The ID of the order.
iban String The customer’s IBAN.
bic String The customer BIC.
externalOrderId String An ID of a related external order.
uniqueId String The ID of the transaction process.
holder String The account holder’s name.
PDFLink String A URL of the related PDF document.

Step 5: Make an empty charges call

After a successful authorization, make a payments/{paymentId}/charges call with an empty body:

POST https://api.unzer.com/v1/payments/s-pay-1234/charges

Body: {}
{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "OK"
    },
    "amount": "100.97",
    "currency": "EUR",
    "date": "2019-05-13 12:53:12",
    "resources": {
        "customerId": "s-cst-f63654a8d1da",
        "paymentId": "s-pay-3059",
        "basketId": "s-bsk-1192",
        "metadataId": "",
        "payPageId": "",
        "typeId": "s-ins-5m68opwdspge"
    },
    "orderId": "payment-order-1557751911319-685",
    "processing": {
        "externalOrderId": "eac0fe4a-7894-4e06-866b-7473842b4819",
        "uniqueId": "31HA07BC8110EE7AEA236F696D70E013",
        "shortId": "4216.7839.2668"
    }
}

Optional: Fetch the payments/{paymentId}/charges result

GET https://api.unzer.com/v1/payments/s-pay-1234/charges/s-chg-1
{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "OK"
    },
    "amount": "100.97",
    "currency": "EUR",
    "date": "2019-05-13 12:53:12",
    "resources": {
        "customerId": "s-cst-f63654a8d1da",
        "paymentId": "s-pay-3059",
        "basketId": "s-bsk-1192",
        "metadataId": "",
        "payPageId": "",
        "typeId": "s-ins-5m68opwdspge"
    },
    "orderId": "payment-order-1557751911319-685",
    "processing": {
        "externalOrderId": "eac0fe4a-7894-4e06-866b-7473842b4819",
        "uniqueId": "31HA07BC8110EE7AEA236F696D70E013",
        "shortId": "4216.7839.2668"
    }
}

Step 6: Send the shipment

Partial shipment
Unzer Instalment doesn’t support partial shipment.

After charching the customer, send the shipment.

Make a POST call to payments/{paymentId}/shipments:

POST https://api.unzer.com/v1/payments/s-pay-1234/shipments

Body: 
{
  "invoiceId": "invoice-nr-1"
}
{
    "id": "s-shp-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "OK"
    },
    "amount": "100.97",
    "currency": "EUR",
    "date": "2019-05-13 12:53:47",
    "resources": {
        "customerId": "s-cst-f63654a8d1da",
        "paymentId": "s-pay-3059",
        "basketId": "s-bsk-1192",
        "metadataId": "",
        "payPageId": "",
        "typeId": "s-ins-5m68opwdspge"
    },
    "orderId": "payment-order-1557751911319-685",
    "invoiceId": "invoice-nr-1",
    "processing": {
        "externalOrderId": "eac0fe4a-7894-4e06-866b-7473842b4819",
        "uniqueId": "31HA07BC8110EE7AEA234F2D544C81A9",
        "shortId": "4216.7842.7680"
    }
}

Optional: Make a refund

Make a full refund (cancel)

To fully refund the money to the custoner, make the following call:

POST https://api.unzer.com/v1/payments/{paymentId}/charges/{chargeId}/cancels
Cancel
You can only cancel an Unzer Instalment payment after you make a payments/{orderId}/charges call. You can’t cancel an authorization.
You can cancel before or after making a payments/{paymentId}/shipments call

Make a partial refund

To partially refund a transaction, provide Gross, Net and VATamounts. For details, see API reference.

POST https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-1/cancels
{
  "amountGross": 11.9,
  "amountNet": 10,
  "amountVat": 1.9
}

Full cURL example

Use the cURL samples below to go through the Unzer Instalment process yourself.

Remember to change orderId within the Basket call and to change the references within the payments/authorize call to the ones you received from the system.

When making a payments/{orderId}/charges call, use the paymentId that was retrieved by the payments/authorize call

curl -X GET 'https://api.unzer.com/v1/types/installment-secured/plans?amount=100&currency=EUR&orderDate=2019-03-21&effectiveInterest=5.99' \
  -u s-pub-2a10ifVINFAjpQJ9qW8jBe5OJPBx6Gxa:
curl https://api.unzer.com/v1/customers \
  -u s-pub-2a10ifVINFAjpQJ9qW8jBe5OJPBx6Gxa: \
  -d firstname=Manuel \
  -d lastname=Weißmann \
  -d salutation=mr \
  -d birthDate=1974-10-03 \
  -d email=info@unzer.com \
  -d phone=+4315136633600 \
  -d mobile=+43676123456789 \
  -d billingAddress.name="Manuel Weißmann" \
  -d billingAddress.street="Hugo-Junkers-Str. 5" \
  -d billingAddress.state="DE-BO" \
  -d billingAddress.zip=60386 \
  -d billingAddress.city="Frankfurt am Main" \
  -d billingAddress.country=DE \
  -d shippingAddress.name="Michaela Junghens" \
  -d shippingAddress.street="Burgstraße 106" \
  -d shippingAddress.state="DE-BO" \
  -d shippingAddress.zip=60389 \
  -d shippingAddress.city="Frankfurt am Main" \
  -d shippingAddress.country=DE
curl -X POST https://api.unzer.com/v1/baskets \
  -u s-pub-2a10ifVINFAjpQJ9qW8jBe5OJPBx6Gxa: \
  -H 'Content-Type: application/json' \
  -d '{
  "amountTotal": "100.00",
  "amountTotalDiscount": "0.00",
  "amountTotalVat": "20.00",
  "currencyCode": "EUR",
  "orderId": "136d24bf-xxx-12", 
  "note": "merchantwebshop.com basket for masterpass",
  "basketItems": [
    {
      "basketItemReferenceId": "xxxxx",
      "unit":"Pc.",
      "quantity": "1",
      "amountDiscount": "0.00",
      "vat": "20",
      "amountGross": "100.00",
      "amountVat": "20",
      "amountPerUnit": "80.00",
      "amountNet": "80.00",
      "title": "Macbook pro",
      "subTitle": "This is brand new Mid 2019 version",
      "imageUrl": "https://www.unzer.com/typo3conf/ext/Unzer_site/Resources/Public/Images/Unzer-Logo_weiss.svg"
    }
  ]
}'
curl https://api.unzer.com/v1/types/installment-secured \
  -u s-priv-2a102ZMq3gV4I3zJ888J7RR6u75oqK3n: \
  -d iban=DE89370400440532013000 \
  -d bic=COBADEFFXXX \
  -d accountHolder="Manuel Weißmann" \
  -d invoiceDate=2019-05-28 \
  -d invoiceDueDate=2019-12-10 \
  -d orderDate=2019-05-27 \
  -d numberOfRates=3 \
  -d dayOfPurchase=2019-09-10 \
  -d totalPurchaseAmount=100 \
  -d totalInterestAmount=0.97 \
  -d totalAmount=100.97 \
  -d effectiveInterestRate=5.99 \
  -d nominalInterestRate=5.88 \
  -d feeFirstRate=0 \
  -d feePerRate=0 \
  -d monthlyRate=33.66 \
  -d lastRate=33.65
curl -X PUT https://api.unzer.com/v1/types/installment-secured/s-ins-dd0rvba2tyba \
  -u s-pub-2a10ifVINFAjpQJ9qW8jBe5OJPBx6Gxa: \
  -d iban=DE89370400440532013000 \
  -d bic=COBADEFFXXX \
  -d accountHolder="Manuel Weißmann" \
  -d invoiceDate=2019-05-28 \
  -d invoiceDueDate=2019-12-10
curl https://api.unzer.com/v1/payments/authorize \
  -u s-priv-2a102ZMq3gV4I3zJ888J7RR6u75oqK3n: \
  -d amount=100.00 \
  -d currency=EUR \
  -d effectiveInterestRate=5.99 \
  -d returnUrl=https://www.unzer.com \
  -d resources.typeId=s-ins-dd0rvba2tyba \
  -d resources.basketId=s-bsk-6475 \
  -d resources.customerId=s-cst-2c1cdd196fc6
curl https://api.unzer.com/v1/payments/s-pay-178035/charges -X POST \
  -u s-priv-2a102ZMq3gV4I3zJ888J7RR6u75oqK3n:
curl https://api.unzer.com/v1/payments/s-pay-178035/shipments -X POST \
  -u s-priv-2a102ZMq3gV4I3zJ888J7RR6u75oqK3n:
  -d invoiceId=invoice-number-1

Implement the Unzer Instalment UI on your website

To quickly integrate Unzer Instalment into your website, implement our ready-made UI components.

To implement the Unzer Instalment UI on your website, follow the steps below.

Integration
For other integration methods, go to the integrate section.

Step 1: Load our JS script and CSS stylesheet

Include Unzer’s script and stylesheet on your website.

Always load the script and stylesheet directly from https://static.unzer.com:

<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>

Step 2: Create a heidelpayInstance

Create a heidelpayInstance with your public key:

var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

Step 3: Create your HTML form

Create an HTML form, into which the Unzer Instalment UI will be inserted.

<form id="payment-form-hirepurchase" class="heidelpayUI form heidelpayUI-hirepurchase__form" novalidate>
  <div id="example-installment-secured">
      <!-- The Unzer Instalment field UI Element will be inserted here -->
  </div>
  <button id="continue-button" class="heidelpayUI primary button fluid" type="submit" style="display: none" disabled>
    Continue
  </button> 
</form>
Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create a new Unzer Instalment resource

To create a new Unzer Instalment instance, call the heidelpayInstance.HirePurchase() method:

var HirePurchase = heidelpayInstance.HirePurchase()
The IDs must match
Make sure that the IDs in your HTML and JavaScript files match. For more information on how to create your HTML form correctly, go to web integration.

Step 5: Fetch available instalment plans

To fetch available instalment plans, call the HirePurchase.create() method:

var HirePurchase = heidelpayInstance.HirePurchase()

HirePurchase.create({
  containerId: 'example-installment-secured', // required
  amount: 500, // required
  currency: 'EUR', // required
  effectiveInterest: 4.5, // required
  orderDate: '2019-04-18', // optional
})
  .then(function(data){
  // if successful, notify the user that the list of instalments was fetched successfully
  // in case you were using a loading element during the fetching process,
  // you can remove it inside this callback function
  })
  .catch(function(error) {
  // sent an error message to the user (fetching instalment list failed)    
  })

The list of available instalment plans displays in the <div id=example-installment-secured> of the HTML form from step 3.

The HirePurchase.create() method returns a Promise with an object that contains either success data or error data.

In case of an error, the returned object contains an error key with the error data returned from the back end.

Step 6: Adjust the UI to custom events

Because the Unzer Instalment UI consists of two parts (List of instalment options and Chosen instalment details), you have to listen to a custom hirePurchaseEvent in order to either remove or enable/disable the submit button.

The custom event returns an object, with a key action. You should use the validate action for enabling/disabling the button, and the change-step action for displaying the button.

var HirePurchase = heidelpayInstance.HirePurchase()
var continueButton = document.getElementById('continue-button')

HirePurchase.addEventListener('hirePurchaseEvent', function(e) {
  if (e.action === 'validate') {
    if (e.success) {
      continueButton.removeAttribute('disabled')
    } else {
      continueButton.setAttribute('disabled', true)
    }
 }
  
  if (e.action === 'change-step') {
    if (e.currentSteep === 'plan-list') {
      continueButton.setAttribute('style', 'display: none')
            continueButton.setAttribute('disabled', true)
    } else {
      continueButton.setAttribute('style', 'display: block')
    }
  }
})

The validate action sends the results of the input fields validation. If all fields are valid, it returns a success value, which allows you to enable the button.

In addition, you should initially set the style of Continue button to display: none. The button should not be rendered during the plan-list step, but only for the plan-detail. Use the event’s currentStep value to show or hide the button.

Step 7: Submit the form

If the customer selects an instalment plan, correctly fills the input fields and presses the Continue button, call the HirePurchase.createResource() method:

// HirePurchase.createResource()
// Handling the form's submission.
var form = document.getElementById('installment-secured-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  HirePurchase.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    });
});

UI reference

Constructors

Constructor Description
heidelpayInstance.HirePurchase() Initializes the Unzer Instalment object.

Methods

Method Type Description Returns
create(Object) Promise Creates a Promise object and gets either resolved or rejected.

If resolved successfully , the method fetches the list of available instalment plans and mounts them onto the declared DOM element.

If rejected, the method returns an error object containing the error details returned from the HTTP request.
An object containing success or error details.

Success:
{action: String,
success: Boolean,
message: String}

Error:
{action: String,
success: Boolean,
message: String,
error: Object}
createResource() Promise Creates a Promise object for input validation. The method either gets resolved (validation passes) or rejected (validation doesn’t pass). An object containing the details of the chosen instalment plan and the partly hidden information from the form.

Success:
{id: String,
method: String,
bic: String,
monthlyRate: String,
numberOfRates: String,
...}

Error:
{details: Object,
message: String}
create properties
Property Required Type Default Description
containerId Yes String / The HTML id of the DOM element where the UI component will be inserted.
amount Yes Number / The gross amount of the goods intended to be purchased (excludes effectiveInterest).

Must be a positive number.
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format.
effectiveInterest Yes Number / Specifies the effective interest rate of the monthly instalment payments. The range is tied to your merchant configuration. It will affect the final amount the customer needs to pay.

The passed value must not be a negative number.
orderDate Optional String The purchase date The order date in the YYYY-MM-DD format.

Unzer API vs Unzer Insights

There are a few differences between the Unzer API and Unzer Insights:

Unzer API Unzer Insights
authorize (no entry in Unzer Insights)
charge reservation
cancel reversal
shipment finalize