Unzer Invoice

Unzer Invoice lets you issue an invoice and then collect the payment.

About Unzer Invoice

Unzer Invoice works in the following way:

  1. You send your customer an invoice.
  2. Your customer pays with a bank transfer.
  3. You receive a notification about the successful payment.

Accept an Unzer Invoice payment

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

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

Step 1: Create an invoice resource

First, create an invoice resource.

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

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

Body: {}
{
  "id": "s-ivc-yv4uza8xbapi",
  "method": "invoice",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "VN"
  }
}
Property Type Description
id String The ID of the invoice 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 resource that you created.

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

Parameter Required Type Default Description Example
amount Yes Number / The amount on the invoice. 12.4500
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
customerId Yes String / The ID of the customers resource. 51222
typeId Yes String / The newly-created payment type ID that you received in response to creating a invoice resource (Step 1). s-ivc-yv4uza8xbapi
POST https://api.unzer.com/v1/payments/charges
   
Body:
{
    "amount": "12.4500",
    "currency": "EUR",
    "resources": {
        "customerId": "",
        "typeId":  "s-ivc-yv4uza8xbapi",
    }
}
{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "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-ivc-yv4uza8xbapi"
    },
    "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 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 on the invoice

Make sure to put the following data on the invoice:

  • iban
  • bic
  • holder
  • descriptor

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

Implement the Unzer Invoice UI on your website

To quickly integrate Unzer Invoice into your website, implement 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 resource

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

var Invoice = heidelpayInstance.Invoice()

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 Invoice object. The Promise gets either resolved or rejected:

var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Invoice.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 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 instance
var Invoice = heidelpayInstance.Invoice()

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

UI reference

Constructors

Constructor Description
heidelpay.Invoice() Initializes the Invoice 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 resource ID.
method String The payment method.