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

This version contains several backward incompatible changes.

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.

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:

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.

To facilitate this, the JSON data is Base64 encoded and sent as 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.

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.