Unzer Invoice Secured

Unzer Invoice Secured lets you issue an invoice and then collect the payment, your payment is secured.

About Unzer Invoice Secured

Unzer Invoice Secured works similarly to Unzer Invoice, with one key difference: an insurance company guarantees your payment for customer defaults.

To guarantee the payment, the insurance company carries out a risk assessment in advance.

Unzer Invoice Secured works in the following way:

  1. You send your customer an invoice.
  2. In the background, an insurance company carries out a risk assessment of your customer.
  3. Your customer pays with a bank transfer, and you receive a notification about the successful payment.
    If your customer doesn’t pay within 40 days of issuing the invoice, you receive the payment from the insurance company.

Accept an Unzer Invoice Secured payment

To accept an Unzer Invoice Secured payment, follow the steps below.

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

Step 1: Create an invoice-secured resource

First, create an invoice-secured resource.

Make an empty-body POST call to types/invoice-secured:

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

Body: {}

{
    "id": "s-ivs-450mlccge87o",
    "method": "invoice-secured",
    "recurring": false,
    "geoLocation": {
        "clientIp": "127.0.0.1",
        "countryIsoA2": "DE"
    }
}
Property Type Description
id String The ID of the invoice-secured resource that you just created.
method String The payment method.
recurring Boolean Indicates if this is a recurring payment.
clientIp Boolean The IP address of the device used for the payment.
countryCode Boolean The country associated with clientIp, displayed in the ISO 3166-1 alpha-2 format.

Step 2: Make a charges call

Now, charge the invoice-secured resource that you created.

Make a POST call to payments/charges, with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Float / The amount on the invoice. 70.00
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
invoiceId Yes String / Your internal invoice ID. INV-12345
customerId Yes String / The ID of the customers resource.
The related customers resource must contain at least firstname, lastname, company, birthDate, email and billingAddress.
s-cst-ecb23128081f
basketId Yes String / The ID of the basket resource to be used. s-bsk-57640
typeId Yes String / The ID of the Payment types resource to be used. s-ivs-450mlccge87o
POST https://api.unzer.com/v1/payments/charges
   
Body:
{
    "amount": "70",
    "currency": "EUR",
    "returnUrl": "https://unzer.com",
    "resources": {
        "customerId": "{{customer_id}}",
        "basketId": "{{basket_id}}",
        "typeId": "{{payment_method_id}}"
    }
}

{
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isError": 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": "70.0000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com",
    "date": "2021-03-15 10:49:16",
    "resources": {
        "customerId": "s-cst-ecb23128081f",
        "paymentId": "s-pay-124374",
        "basketId": "s-bsk-57640",
        "traceId": "bd1c9471920bc1d4cf8d9353c7d96ef4",
        "typeId": "s-ivs-450mlccge87o"
    },
    "paymentReference": "",
    "processing": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "uniqueId": "31HA07BC8168A404783C87D9D00FA862",
        "shortId": "4797.3175.0831",
        "descriptor": "4797.3175.0831",
        "holder": "Maxmillian",
        "traceId": "bd1c9471920bc1d4cf8d9353c7d96ef4"
    }
}
Property Type Description
id String The transaction’s unique ID.
isSuccess Boolean Set to true if the transaction was successful.
isPending Boolean Set to true if the transaction is pending
(e.g. if a redirect to an external system is required).
isError Boolean Set to true if an error occurs.
code String A unique ID of the message.

For details, go to Error code structure.
customer String Message displayed to the customer.
amount Number The transaction 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 transaction.
invoiceId String The invoice ID.
customerId String The ID of the customers resource.
paymentId String The ID of the related payment resource.
metadataId String The ID of the related metadata resource.
typeId String The newly-created payment type ID that you received in response to creating a invoice-secured resource (Step 1).
iban String The customer’s IBAN.
bic String The customer BIC.
uniqueId String The ID of the transaction process.
shortId String The short ID of the transaction process.
descriptor String The transaction descriptor number.
holder String The account holder’s name.
Payment details of the invoice

You must add the following data for an invoice:

  • iban
  • bic
  • holder
  • descriptor

Infom your customer that they need to use descriptor when making an online bank transfer. The descriptor links the payment to the customer.

Step 3: (Optional) Cancel before shipment

If the customer cancels some of the goods before the shipment, then this amount is directly deducted from the charge amount. The shipment is now only applicable for the reduced charge amount. In the example above, if the customer cancels goods worth 15 EUR, it is deducted from the total amount of 70 EUR and 55 EUR is now the updated total amount.

Note that you must always specify a valid reason for the cancelation of an order.

Reason code Description
CANCEL The customer cancels the order
RETURN The customer returns the goods
CREDIT The merchant (you) gives credit to the customer
POST https://api.unzer.com/v1/payments/{{order_id}}/charges/{{charge_id}}/cancels
   
Body:
{
  "amount" : "15",
  "reasonCode": "RETURN"
}
{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isError": 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": "15.0000",
    "currency": "EUR",
    "date": "2021-03-15 10:49:57",
    "resources": {
        "customerId": "s-cst-ecb23128081f",
        "paymentId": "s-pay-124374",
        "basketId": "s-bsk-57640",
        "metadataId": "",
        "payPageId": "",
        "traceId": "bd1c9471920bc1d4cf8d9353c7d96ef4",
        "typeId": "s-ivs-450mlccge87o"
    }
    ...
}

Step 4: Make a shipments call

You can either have a partial shipment or a full shipment. For Invoice Secured, you can only have one shipment.

Option 1: Partial shipment

If you ship only some of the goods and make a partial shipment call, the balance amount from the charges is automatically canceled. In the example above, from the total charge of 55 EUR if you ship goods for 50 EUR, the balance 5 EUR is automatically canceled.

POST https://api.unzer.com/v1/payments/{{order_id}}/shipments
   
Body:
{
  "invoiceId" : "{{random_invoiceId}}",
  "amount" : "50"
}
{
    "id": "s-shp-1",
    "isSuccess": true,
    "isPending": false,
    "isError": 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": "50.0000",
    "currency": "EUR",
    "date": "2021-03-17 07:59:17",
    "resources": {
        "customerId": "s-cst-cd9f96e0ea2d",
        "paymentId": "s-pay-124995",
        "basketId": "s-bsk-58099",
        "metadataId": "",
        "payPageId": "",
        "traceId": "1907741f4dffb9e34998a7566fc177c8",
        "typeId": "s-ivs-6ssv6ec74thi"
    },
    ...
}

Option 2: Full shipment

When you ship all the products and make a shipments call, the total amount is charged. From this day onwards, the customer has 40 days to pay the invoice.

Make an empty-body POST call to payments/{paymentId}/shipments:

POST https://api.unzer.com/v1/payments/s-ivs-ovbpknonqa2y/shipments

Body: {}
{
    "id": "s-shp-1",
    "isSuccess": true,
    "isPending": false,
    "isError": 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": "70.0000",
    "currency": "EUR",
    "date": "",
    "resources": {
        "customerId": "s-cst-cd9f96e0ea2d",
        "paymentId": "s-pay-125491",
        "basketId": "s-bsk-58335",
        "metadataId": "",
        "payPageId": "",
        "traceId": "ad2f2f8baef8e00e695cd6dd9277d185",
        "typeId": "s-ivs-umhwcpaahjoa"
    },
    ...
}

Step 5: (Optional) Cancel after shipment

If the customer requests a refund or cancels the order, you can execute a cancel-charges and this amount is deducted from the transaction amount. In the example above, if the customer returns the goods for 15 EUR, this is shown as canceled amount. The leftover 55 EUR will be the charged amount. You can view the transactions for each step as shown below.

POST https://api.unzer.com)/payments/{{order_id}}/charges/{{charge_id}}/cancels
{
  "amount" : "15",
  "reasonCode": "RETURN"
}
{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isError": 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": "15.0000",
    "currency": "EUR",
    ...
 }    

Step 6: Verify the payment details

Once the payment is made, you can make a GET call to view the payment details.

GET https://api.unzer.com/v1/payments/{{order_id}}
{
    "id": "s-pay-124374",
    "state": {
        "id": 1,
        "name": "completed"
    },
    "amount": {
        "total": "55.0000",
        "charged": "40.0000",
        "canceled": "15.0000",
        "remaining": "0.0000"
    },
    ...
    "transactions": [
        {
            "date": "2021-03-15 10:49:16",
            "type": "charge",
            "status": "pending",
            "url": "https://api.unzer.com/v1/payments/s-pay-124374/charges/s-chg-1",
            "amount": "70.0000"
        },
        {
            "date": "2021-03-15 10:49:57",
            "type": "cancel-charge",
            "status": "success",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124374/charges/s-chg-1/cancels/s-cnl-1",
            "amount": "15.0000"
        },
        {
            "date": "2021-03-15 10:58:26",
            "type": "shipment",
            "status": "success",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124374/shipments/s-shp-1",
            "amount": "55.0000"
        },
        {
            "date": "2021-03-15 10:59:02",
            "type": "cancel-charge",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-124374/charges/s-chg-1/cancels/s-cnl-2",
            "amount": "15.0000"
        }
    ]
}
GET https://api.unzer.com/v1/payments/{{order_id}}
{
    "id": "s-pay-124995",
    "state": {
        "id": 1,
        "name": "completed"
    },
    "amount": {
        "total": "50.0000",
        "charged": "50.0000",
        "canceled": "0.0000",
        "remaining": "0.0000"
    },
    ...
    "transactions": [
        {
            "date": "2021-03-17 07:58:00",
            "type": "charge",
            "status": "pending",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124995/charges/s-chg-1",
            "amount": "70.0000"
        },
        {
            "date": "2021-03-17 07:58:20",
            "type": "cancel-charge",
            "status": "success",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124995/charges/s-chg-1/cancels/s-cnl-1",
            "amount": "15.0000"
        },
        {
            "date": "2021-03-17 07:59:16",
            "type": "cancel-charge",
            "status": "success",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124995/charges/s-chg-1/cancels/s-cnl-2",
            "amount": "5.0000"
        },
        {
            "date": "2021-03-17 07:59:17",
            "type": "shipment",
            "status": "success",
            "url": "https://stg-api.unzer.com/v1/payments/s-pay-124995/shipments/s-shp-1",
            "amount": "50.0000"
        }
    ]
}

Implement the Unzer Invoice Secured UI on your website

To quickly integrate Unzer Invoice Secured into your website, impement our ready-made UI components.

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

Because your customer doesn’t need to enter any information, you just need to create a simple HTML button::

<form id="payment-form">
  <button type="submit">Pay</button>
</form>
Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create a new Unzer Invoice Secured resource

To create a new Unzer Invoice Secured instance, call the heidelpayInstance.InvoiceSecured() method:

var Invoice = heidelpayInstance.InvoiceSecured()

Step 5: Add an event listener and submit the form

Now get the HTML form by its unique ID and add an event listener.

Inside, create a Promise on the InvoiceSecured object. The Promise gets either resolved or rejected:

var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  InvoiceSecured.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

Step 6: Review the code

View the complete code samples that you can use to implement the Unzer Invoice Secured UI on your website.

Make sure to import your own JavaScript and CSS files, as well as unzer.js and unzer.css.

<form id="payment-form">
  <button type="submit">Pay</button>
</form>
// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an Invoice Secured instance
var Invoice = heidelpayInstance.InvoiceSecured()

// Handle payment form submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  InvoiceSecured.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    })
});

UI reference

Constructors

Constructor Description
heidelpay.InvoiceSecured() Initializes the InvoiceSecured object.

Methods

Method Type Description Returns
createResource() Promise Creates a Promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass). An object containing success or error details.

Success:
{id: String,
method: String}

Error:
{}
Property Type Description
id String The returned /types/invoice-secured resource ID.
method String The payment method.