Unzer Invoice Secured

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

About Unzer Invoice Secured

Unzer Invoice Secured works similarly to Unzer Invoice, with one key difference: an insurance company guarantees that you receive the payment even if the customer doesn’t pay up.

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 on 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-yv4uza8xbapi",
  "method": "invoice-secured",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "VN"
  }
}
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. 12.20
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 to be used.
The related customers 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. s-bsk-1192
typeId Yes String / The ID of the Payment types resource to be used. s-hdd-5m68opwdspge
POST https://api.unzer.com/v1/payments/charges
   
Body:
{
    "amount": "50.0000",                                    
    "currency": "EUR",
    "invoiceId" : "INV-12345",
    "resources": {
        "customerId": "s-cst-d6c49cecab8d",
        "basketId": "s-bsk-173",
        "typeId":  "s-ivs-ovbpknonqa2y",
    }
}
{
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "customer": "Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "https://www.unzer.com",
    "date": "2018-09-26 13:31:12",
    "invoiceId": "any-iv-id",
    "resources": {
        "customerId": "s-cst-138b70861e6c",
        "paymentId": "s-pay-7785",
        "metadataId": "",
        "typeId": "s-ivs-ovbpknonqa2y"
    },
    "processing": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "uniqueId": "31HA07BC8137E7B23DE93994780BD507",
        "shortId": "4018.9507.2850",
        "descriptor": "4018.9507.2850",
        "holder": "Merchant Thuan"
    }
}
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 the invoice

Make sure to put the following data on the invoice:

  • iban
  • bic
  • holder
  • descriptor

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

Step 3: Make a shipments call

When you send out the goods to the customer, make a shipments call. From this point on, 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: {}

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.