@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)