HUB-3 Barcode API - Version 2

This is the current version of the API. Version 1 is deprecated and will be removed at a future date.

Contents:

Upgrading from Version 1
Endpoints
Request data
Barcode data
Encoding the data
Renderers
Errors

Upgrading from Version 1

This version contains several backward incompatible changes.

GET request data should be sent as base64-encoded JSON, this replaces the encoding described in version 1
Added required field data.currency to support transactions in EUR
data.amount changed from float to integer, it describes the desired amount multiplied by 100. To charge 123.45, the amount should be set to 12345
Options scale, ratio, and padding require integer values, string and float values are no longer accepted.
Added the text renderer

Endpoints

The HUB-3 Barcode API uses a single URL:

https://hub3-beta.bigfish.software/api/v2/barcode

It's possible to make a GET or POST request to this URL.

POST requests: data is sent JSON encoded in the request body.
GET requests: data is sent as base64-encoded JSON in the query string.

On success, the server returns a HTTP 200 OK response, with the barcode encoded in the response body. Content type depends on the renderer used.

Request data

The request data should contain an object with the following keys:

Key	Type	Description
renderer	string	Name of the renderer to use.
options	object	Renderer-specific configuration.
data	object	Data to be encoded into the barcode.

The renderer is the component which renders the barcode to the target format. This can be an image, an SVG document or something else. Each renderer has a set of options which configures its behaviour.

The request data in JSON would look like this:

{
    "renderer": "image",
    "options": {
        // Renderer options go here
    },
    "data": {
        // Barcode data goes here
    }
}

Barcode data

The data that will be encoded into a HUB-3 barcode. The data format is defined by the HUB-3 standard.

IMPORTANT: Since API Version 2, the transaction amount is given as an integer number and should be equal to the desired amount multiplied by 100. To charge 123.45, the amount should be 12345.

Key	Type	Description
amount	integer	Transaction amount multiplied by 100
currency	string (3)	ISO 4217 currency code
purpose	string (4)	Purpose code by ISO 20022 standard
description	string (35)	Transaction description
sender	object	Sender data
> sender.name	string (30)	Name and surname, or company name
> sender.street	string (27)	Address (street and number)
> sender.place	string (27)	Address (post code and place name)
receiver	object	Receiver data
> receiver.name	string (25)	Name and surname, or company name
> receiver.street	string (25)	Address (street and number)
> receiver.place	string (27)	Address (post code and place name)
> receiver.iban	string (21)	Account number (IBAN)
> receiver.model	string (2)	Payment reference model
> receiver.reference	string (22)	Payment reference

Strings should be UTF-8 encoded. Length limits are defined as number of characters, not number of bytes.

Example barcode data in JSON:

{
    "amount": 100000,
    "currency": "HRK",
    "sender": {
        "name": "Pero Perić",
        "street": "Aleja brijestova 13",
        "place": "10000 Zagreb"
    },
    "receiver": {
        "name": "Neka firma d.o.o.",
        "street": "Poslovna ulica bb",
        "place": "51000 Rijeka",
        "iban": "HR1234567890123456789",
        "model": "00",
        "reference": "123-456-789"
    },
    "purpose": "ANTS",
    "description": "Uplata po računu 123"
}

A note about receiver model and reference:

The payment reference is a string which is attached to the transaction and can be seen by the receiver. It typically contains information which helps the receiver identify the source and prupose of the transaction, such as a personal identification number (OIB) or a customer code. It typically contains one or more groups of numbers separated by dashes (e.g. 123-456-789), but this could change in the future.
The payment reference model is a 2 digit string which defines the format of the reference string.

For more details, check out the Croatian Financial Agency's specification (PDF).

Encoding the data

The above examples show how to encode the data in JSON for POST requests. For GET requests, the same data structure should be sent as a URL-encoded string in the query parameters.

JSON data is Base64 encoded and sent as the data query parameter.

For example, consider this full request in JSON:

{
    "renderer": "image",
    "options": {
        "format": "png",
        "color": "#000000"
    },
    "data": {
        "amount": 100000,
        "currency": "HRK",
        "sender": {
            "name": "Pero Perić",
            "street": "Aleja brijestova 13",
            "place": "10000 Zagreb"
        },
        "receiver": {
            "name": "Neka firma d.o.o.",
            "street": "Poslovna ulica bb",
            "place": "51000 Rijeka",
            "iban": "HR1234567890123456789",
            "model": "00",
            "reference": "123-456-789"
        },
        "purpose": "ANTS",
        "description": "Uplata po računu 123"
    }
}

The same data, base64-encoded:

    eyJyZW5kZXJlciI6ImltYWdlIiwib3B0aW9ucyI6eyJmb3JtYXQiOiJwbmciLCJzY2FsZSI6MywicmF0aW8iOjMsImNvbG9yIjoiIzJjM2U1MCIsImJnQ29sb3IiOiIjZWVlZWVlIiwicGFkZGluZyI6MjB9LCJkYXRhIjp7ImFtb3VudCI6MTAwMDAwLCJjdXJyZW5jeSI6IkhSSyIsInNlbmRlciI6eyJuYW1lIjoiUGVybyBQZXJpxIciLCJzdHJlZXQiOiJBbGVqYSBicmlqZXN0b3ZhIDEzIiwicGxhY2UiOiIxMDAwMCBaYWdyZWIifSwicmVjZWl2ZXIiOnsibmFtZSI6Ik5la2EgZmlybWEgZC5vLm8uIiwic3RyZWV0IjoiUG9zbG92bmEgdWxpY2EgYmIiLCJwbGFjZSI6IjUxMDAwIFJpamVrYSIsImliYW4iOiJIUjEyMzQ1Njc4OTAxMjM0NTY3ODkiLCJtb2RlbCI6IjAwIiwicmVmZXJlbmNlIjoiMTIzLTQ1Ni03ODkifSwicHVycG9zZSI6IkFOVFMiLCJkZXNjcmlwdGlvbiI6IlBvdnJhdCBkdWdhIn19

The encoded data is passed to the endpoint as a data query parameter to form the GET URL.

WARNING: Make sure you URL-encode the data because base64-encoded data may include the + sign which is otherwise interpreted as a space in the URL.

Renderers

Image Renderer

Returns the barcode as a JPG, PNG or GIF image.

Options

Name	Description	Type	Deafult
format	Image format. One of: `jpg`, `png`, or `gif`.	string	png
padding	Padding size in pixels.	integer	20
color	Barcode color as a hex code.	string	`#000000`
bgColor	Background color as a hex code.	string	`#ffffff`
scale	Width of the single unit in the barcode	integer	3
ratio	Width to height ratio of a single unit	integer	3

The scale and ratio will affect the size of the barcode image. Note that the HUB-3 specification requires the ratio to be 3. If you change it, it might not be readable by some devices.

Sample usage

{
    "renderer": "image",
    "options": {
        "format": "png",
        "color": "#00ff00"
    }
    "data": { ... }
}

Sample response

Content-Type: image/png

Sample HUB-3 barcode

SVG Renderer

Returns the barcode in SVG XML format.

Options

Name	Value	Deafult
scale	Width of the single unit in the barcode	3
ratio	Width to height ration of a single unit	3
color	Barcode color as a hex code.	`#000000`

Sample usage

{
    "renderer": "svg",
    "options": {
        "scale": 3,
        "ratio": 3,
        "color": "#000000"
    }
    "data": { ... }
}

Sample response (truncated)

Content-Type: image/svg+xml

<?xml version="1.0"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" height="477" width="513" version="1.1">
  <description>HUB3 barcode generated by /</description>
  <g id="barcode" fill="black" stroke="none">
    <rect x="0" y="0" width="3" height="9"/>
    <rect x="3" y="0" width="3" height="9"/>
    <rect x="6" y="0" width="3" height="9"/>
    <rect x="9" y="0" width="3" height="9"/>
    <rect x="12" y="0" width="3" height="9"/>
    ...
  </g>
</svg>

JSON Renderer

Returns the barcode pixel grid in JSON. This can be used to draw your own barcode.

This renderer does not take any options.

Sample usage

{
    "renderer": "json",
    "options": {},
    "data": { ... }
}

Sample response (truncated)

Content-Type: application/json

[
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,1,0,1,0,1,0,0,0,1,1,0,0,0,...],
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,1,1,1,0,1,0,1,1,0,1,1,0,0,...],
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,0,1,0,1,0,0,0,0,1,1,1,1,0,...],
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,1,1,1,0,1,0,0,1,0,1,1,1,1,...],
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,1,1,1,0,1,0,1,1,1,1,0,1,1,...],
    [1,1,1,1,1,1,1,1,0,1,0,1,0,1,0,0,0,1,1,1,1,0,1,0,1,1,1,1,1,0,1,...],
    ...
]

Text Renderer

Returns the data HUB3 data which is encoded inside the barcode as plain text. This is mostly useful for debugging purposes.

This renderer does not take any options.

Sample usage

{
    "renderer": "text",
    "options": {}
    "data": { ... }
}

Sample response

Content-Type: text/plain

HRVHUB30
HRK
000000000100000
Pero Perić
Aleja brijestova 13
10000 Zagreb
Neka firma d.o.o.
Poslovna ulica bb
51000 Rijeka
HR1234567890123456789
HR00
123-456-789
ANTS
Uplata po računu 123

Errors

The API will return HTTP 200 OK on success.

On error, it's possible to get one of the following:

HTTP 400 Bad Request

The data you sent doesn't pass validation. The response will contain a JSON encoded error message, and possibly an array of validation errors.

For example, if you send invalid barcode data, you might see something like this:

{
  "message": "Validation failed",
  "errors": [
    "data.amount: must be of integer type",
    "data.receiver.name: max length is 30"
  ]
}

Or if you send data which is not JSON:

{
  "message": "Data is not valid JSON"
}

HTTP 500 Internal Server Error

Congratulations, you found a bug. Please report it.