HUB-3 Barcode API - Version 1

This version of the API is deprecated and will be removed in near future. You should switch to Version 2.

The HUB-3 Barcode API uses a single URL:

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

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

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, a SVG document or something else. Each renderer has a set of options which configures it's behaviour.

The request data in JSON would look like this:

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

Barcode data

This is the data that will be encoded into the HUB-3 barcode. The data format is defined by the HUB-3 standard. Note that "special characters" like č, ć, ž, š and đ are counted as 2.

Key Type Description
amount decimal (15,2) Transaction amount in HRK
purpose text (4) Purpose code by ISO 20022 standard
description text (35) Transaction description
sender object Sender data
> sender.name text (30) Name and surname, or company name
> sender.street text (30) Address (street and number)
> sender.place text (27) Address (post code and place name)
receiver object Receiver data
> receiver.name text (30) Name and surname, or company name
> receiver.street text (27) Address (street and number)
> receiver.place text (27) Address (post code and place name)
> receiver.iban text (21) Account number (IBAN)
> receiver.model text (2) Payment reference model
> receiver.reference text (21) Payment reference

Example barcode data in JSON:

{
    "amount": 1000.00,
    "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:

It typically contains one or more groups of numbers separated by dashes (e.g. 123-456-789), but this could change in the future.

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

The data is validated by a JSON schema which is available here.

Encoding the data

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

For example, consider this full request in JSON:

{
    "renderer": "image",
    "options": {
        "format": "png",
        "color": "#000000"
    },
    "data": {
        "amount": 100000,
        "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, prepared for URL-encoding:

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

These lines, URL-encoded and joined with & produce the query string used for GET requests.

renderer=image&options%5Bformat%5D=png&options%5Bcolor%5D=%23000000&data%5Bamount%5D=100000&data%5Bsender%5D%5Bname%5D=Pero+Peri%C4%87&data%5Bsender%5D%5Bstreet%5D=Aleja+brijestova+13&data%5Bsender%5D%5Bplace%5D=10000+Zagreb&data%5Breceiver%5D%5Bname%5D=Neka+firma+d.o.o.&data%5Breceiver%5D%5Bstreet%5D=Poslovna+ulica+bb&data%5Breceiver%5D%5Bplace%5D=51000+Rijeka&data%5Breceiver%5D%5Biban%5D=HR1234567890123456789&data%5Breceiver%5D%5Bmodel%5D=00&data%5Breceiver%5D%5Breference%5D=123-456-789&data%5Bpurpose%5D=ANTS&data%5Bdescription%5D=Uplata+po+ra%C4%8Dunu+123

Finally, add the query string to the API endpoint to form the GET URL.

Renderers

Image Renderer

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

Options

Name Value Deafult
format Image format. One of: jpg, png, or gif. png
padding Padding size in pixels. 20
color Barcode color as a hex code. #000000
bgColor Background color as a hex code. #ffffff
scale Width of the single unit in the barcode 3
ratio Width to height ratio of a single unit 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,...],
    ...
]

Errors

The API will always return HTTP 200 OK on success.

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

HTTP 400 Bad Request

This means 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: string value found, but a number is required",
        "data.sender.name: must be at most 30 characters long"
    ]
}

Or if you attempt to use a non-existing renderer:

{
    "message": "Unknown renderer \"foo\".",
}

HTTP 500 Internal Server Error

Congratulations, you found a bug. Please report it.