HUB-3 Barcode API

The HUB-3 Barcode API uses a single URL:

```boldhttps://hub-api.morgancode.com/api/v1/barcode


It's possible to make GET or POST request to that URL.
* GET requests: data is sent **URL-encoded** in the query string.
* POST requests: data is sent **JSON encoded** in the request body.

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:

```javascript
{
    "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": 100000,
    "sender": {
        "name": "Ivan Habunek",
        "street": "Savska cesta 13",
        "place": "10000 Zagreb"
    },
    "receiver": {
        "name": "Big Fish Software d.o.o.",
        "street": "Savska cesta 13",
        "place": "10000 Zagreb",
        "iban": "HR6623400091110651272",
        "model": "00",
        "reference": "123-456-789"
    },
    "purpose": "ANTS",
    "description": "Developing a HUB-3 API"
}

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, Croatian).

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": "Ivan Habunek",
            "street": "Savska cesta 13",
            "place": "10000 Zagreb"
        },
        "receiver": {
            "name": "Big Fish Software d.o.o.",
            "street": "Savska cesta 13",
            "place": "10000 Zagreb",
            "iban": "HR6623400091110651272",
            "model": "00",
            "reference": "123-456-789"
        },
        "purpose": "ANTS",
        "description": "Developing a HUB-3 API"
    }
}

The same data, prepared for URL-encoding:

renderer=image
options[format]=png
options[color]=#000000
data[amount]=100000
data[sender][name]=Ivan Habunek
data[sender][street]=Savska cesta 13
data[sender][place]=10000 Zagreb
data[receiver][name]=Big Fish Software d.o.o.
data[receiver][street]=Savska cesta 13
data[receiver][place]=10000 Zagreb
data[receiver][iban]=HR6623400091110651272
data[receiver][model]=00
data[receiver][reference]=123-456-789
data[purpose]=ANTS
data[description]=Developing a HUB-3 API

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=Ivan+Habunek&data%5Bsender%5D%5Bstreet%5D=Savska+cesta+13&data%5Bsender%5D%5Bplace%5D=10000+Zagreb&data%5Breceiver%5D%5Bname%5D=Big+Fish+Software+d.o.o.&data%5Breceiver%5D%5Bstreet%5D=Savska+cesta+13&data%5Breceiver%5D%5Bplace%5D=10000+Zagreb&data%5Breceiver%5D%5Biban%5D=HR6623400091110651272&data%5Breceiver%5D%5Bmodel%5D=00&data%5Breceiver%5D%5Breference%5D=123-456-789&data%5Bpurpose%5D=ANTS&data%5Bdescription%5D=Developing+a+HUB-3+API

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 byhttps://hub-api.morgancode.com/</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.