NBS

NBS integration connects your project to the National Bank of Serbia APIs for IPS QR code generation, validation, and company search.

Note

This integration is geolocked to Serbia (RS).

Overview

Key characteristics:

IPS QR code generation — generate NBS-compliant IPS QR codes for instant payments
IPS QR code validation — validate and parse QR code strings into structured payment data
Company search — look up companies by VAT number through the NBS registry

Generating an IPS QR Code

SDKHTTP (cURL)

import { NBS } from "@ptkl/sdk/beta"

const nbs = new NBS()
const result = await nbs.getNbsIpsQrCode({
  TransactionType: "PR",
  Version: "01",
  CharacterSet: "1",
  RecipientAccountNumber: "265000000000000123",
  RecipientName: "Primer d.o.o.",
  AmountInLocalCurrency: "1500.00",
  PayerInformation: "Kupac d.o.o.",
  PaymentPurposeCode: "289",
  PurposeOfPayment: "Uplata po fakturi 123",
  PaymentOrderNumber: "INV-2024-0001",
}, 300)

console.log(result.data.Base64EncodedImage) // PNG as base64
console.log(result.data.Status)             // { StatusCode, StatusDescription }

curl -X POST https://lemon.protokol.io/luma/integrations/v1/karadjordje/nbs/ips-qr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "code": {
      "TransactionType": "PR",
      "Version": "01",
      "CharacterSet": "1",
      "RecipientAccountNumber": "265000000000000123",
      "RecipientName": "Primer d.o.o.",
      "AmountInLocalCurrency": "1500.00",
      "PayerInformation": "Kupac d.o.o.",
      "PaymentPurposeCode": "289",
      "PurposeOfPayment": "Uplata po fakturi 123",
      "PaymentOrderNumber": "INV-2024-0001"
    },
    "size": 300
  }'

QR Code Request Fields

Field	Type	Required	Description
`TransactionType`	`string`	Yes	Transaction type code (e.g. `"PR"` for payment)
`Version`	`string`	Yes	QR code version (e.g. `"01"`)
`CharacterSet`	`string`	Yes	Character encoding set (e.g. `"1"`)
`RecipientAccountNumber`	`string`	Yes	Recipient bank account number
`RecipientName`	`string`	Yes	Recipient name
`AmountInLocalCurrency`	`string`	Yes	Payment amount in RSD
`PayerInformation`	`string`	No	Payer name or reference
`PaymentPurposeCode`	`string`	Yes	NBS payment purpose code
`PurposeOfPayment`	`string`	No	Free text payment description
`PaymentOrderNumber`	`string`	No	Payment reference number

Response

{
  "Status": {
    "StatusCode": 0,
    "StatusDescription": "OK"
  },
  "Base64EncodedImage": "iVBORw0KGgo...",
  "OriginalQRCodeString": "PR|01|1|265000000000000123|..."
}

Validating an IPS QR Code

SDKHTTP (cURL)

import { NBS } from "@ptkl/sdk/beta"

const nbs = new NBS()
const result = await nbs.validateNbsIpsQrCode(
  "PR|01|1|265000000000000123|Primer d.o.o.|RSD1500,00|289|Uplata"
)

console.log(result.data.ParsedData)  // parsed payment fields
console.log(result.data.Status)      // { StatusCode, StatusDescription }

curl -X POST https://lemon.protokol.io/luma/integrations/v1/karadjordje/nbs/ips-qr/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "qrCodeString": "PR|01|1|265000000000000123|Primer d.o.o.|RSD1500,00|289|Uplata"
  }'

Company Search

Search for registered companies in the NBS registry by VAT number.

SDKHTTP (cURL)

import { NBS } from "@ptkl/sdk/beta"

const nbs = new NBS()
const results = await nbs.nbsSearch({
  vatNumber: "123456789",
})

console.log(results) // company details

curl -X GET "https://lemon.protokol.io/luma/integrations/v1/karadjordje/nbs/search?vatNumber=123456789" \
  -H "Authorization: Bearer $TOKEN"

Using in Platform Functions

const { NBS } = $sdk.version('0.10')
const nbs = new NBS()

// Generate QR code for an invoice payment
const qr = await nbs.getNbsIpsQrCode({
  TransactionType: "PR",
  Version: "01",
  CharacterSet: "1",
  RecipientAccountNumber: $input.body.account,
  RecipientName: $input.body.recipient,
  AmountInLocalCurrency: $input.body.amount,
  PaymentPurposeCode: "289",
  PurposeOfPayment: $input.body.purpose,
  PaymentOrderNumber: $input.body.reference,
}, 300)

response.json({
  qr_image: qr.data.Base64EncodedImage,
})

SDK Reference

The NBS class is available via the SDK:

import { NBS } from "@ptkl/sdk/beta"

// Or via the Integrations facade
import { Integrations } from "@ptkl/sdk/beta"
const integrations = new Integrations()
const nbs = integrations.getNBS()

Method	Description
`nbs.getNbsIpsQrCode(code, size, lang?)`	Generate an IPS QR code image
`nbs.validateNbsIpsQrCode(qrCodeString, lang?)`	Validate and parse an IPS QR code string
`nbs.nbsSearch(params)`	Search companies by VAT number