@spayd/core NPM

@spayd/core

A TypeScript library for generating Short Payment Descriptor (SPAYD) strings, a standardized format for encoding payment information into QR codes.

What is SPAYD?

SPAYD (Short Payment Descriptor) is a standardized format for encoding payment information into QR codes. It was developed by the Czech Banking Association and is widely used in Central European countries for initiating bank transfers via QR codes.

Installation

# npm
npm install @spayd/core

# yarn
yarn add @spayd/core

# pnpm
pnpm add @spayd/core

Usage

import { createShortPaymentDescriptor } from '@spayd/core'

// Create a payment descriptor
const spayd = createShortPaymentDescriptor({
  acc: 'CZ6508000000192000145399+GIBACZPX',
  am: '123.45',
  cc: 'CZK',
  msg: 'Payment for services',
  rf: '1234567890',
  rn: 'John Doe',
  dt: new Date('2024-12-31'),
  x: {
    vs: '1234567890', // Variable symbol (specific to Czech/Slovak payments)
    ss: '0987654321', // Specific symbol
    ks: '0308' // Constant symbol
  }
})

console.log(spayd)
// Output: SPD*1.0*ACC:CZ6508000000192000145399+GIBACZPX*AM:123.45*CC:CZK*MSG:Payment for services*RF:1234567890*RN:John Doe*DT:20241231*X-VS:1234567890*X-SS:0987654321*X-KS:0308

API

`createShortPaymentDescriptor(attributes: SpaydPaymentAttributes, transliterateParams?: boolean): string`

Creates a SPAYD string from the provided payment attributes.

Parameters

Parameter	Type	Description
`attributes`	`SpaydPaymentAttributes`	Payment information object. See below for structure.
`transliterateParams`	`boolean`	Optional. Whether to transliterate special characters in text fields.

Returns

Returns a SPAYD-formatted string that can be encoded into a QR code.

Payment Attributes (`SpaydPaymentAttributes`)

Attribute	Type	Required	Description	Format/Validation
`acc`	`string`	Yes	Primary account number (IBAN + optional BIC/SWIFT)	`'CZ6508000000192000145399+GIBACZPX'` or IBAN only
`altAcc`	`string[]`	No	Alternative account numbers	Same format as `acc`. Max 2 recommended.
`am`	`string`	No	Payment amount	Decimal with 2 places (max 10 chars). e.g., `'123.45'`
`cc`	`string`	No	Currency code	ISO 4217 code (3 chars). e.g., `'CZK'`
`rf`	`string`	No	Payment reference	Max 16 digits. e.g., `'1234567890'`
`rn`	`string`	No	Recipient name	Max 35 chars. e.g., `'John Doe'`
`dt`	`Date`	No	Due date	JavaScript `Date` object
`pt`	`string`	No	Payment type	Max 3 chars. `'IP'` for immediate payment
`msg`	`string`	No	Message for recipient	Max 60 chars
`nt`	`'E'\\|'P'`	No	Notification type	`'E'` for email, `'P'` for phone
`nta`	`string`	No	Notification address	Email or phone number (max 320 chars)

Extended Attributes (`x`)

Czech-specific payment attributes:

Attribute	Type	Description	Format/Validation
`x.per`	`string`	Payment retry period	0-30 days. e.g., `'7'`
`x.vs`	`string`	Variable symbol	Max 10 digits
`x.ss`	`string`	Specific symbol	Max 10 digits
`x.ks`	`string`	Constant symbol	Max 10 digits
`x.id`	`string`	Payment identifier	Max 20 chars
`x.url`	`string`	Related URL	Max 140 chars, valid HTTP(S) URL

Validation

The library includes built-in validation for all fields:

IBAN validation using ibantools
Currency code validation against ISO 4217
Length and format validation for all fields
URL validation for x.url
Notification format validation (email/phone)

ibantools

0.0.3

9 months ago

0.0.2