API docs by Redocly

by square API (3.0.1)

Support: info@bysquare.com

The by square API is a REST API for generating and retrieving by square QR payloads, including PAY, SPAYD, and invoice formats.

Base URL

https://api.bysquare.com

Authentication

Authentication is required on every request. Provide your API key either:

  • in the Authorization header (recommended), or
  • as a key query parameter

In the Authorization header, the Bearer prefix is optional and not required.

Recommended (header-based)

Authorization: YOUR_API_KEY

Alternative (http request parameter)

https://api.bysquare.com/...?...&key=YOUR_API_KEY

Security note: Avoid sending API keys in URLs when possible, since query parameters can be logged (browser history, proxies, server logs). Treat your API key like a password. Do not embed it in client-side applications (browser-based web apps, mobile apps, desktop apps), where it can be extracted. Always call the API from a trusted backend/server and keep the key in server-side configuration (for example, environment variables or a secrets manager).

You can generate and manage API keys in the by square portal dashboard.

Account

Get account information

Returns plan name, reset time, and remaining generation/read credits.

Authorizations:
Using HTTP Authorization header

Responses

Request samples 

curl --request GET \
  --url https://api.bysquare.com/info \
  --header 'Authorization: YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "companyName": "My Company",
  • "planName": "Wise",
  • "nextReset": 1771296662,
  • "generations": {
    • "available": 27400,
    • "remaining": 2952,
    • "used": 24448
    },
  • "reads": {
    • "available": 2400,
    • "remaining": 1480,
    • "used": 920
    }
}

Generate

Generate payment QR

Generates by square PAY and/or SPAYD payloads based on the provided payment document. Provide formats to choose outputs. If Accept includes image/png, the response is a raw PNG for the first generated format and includes X-Format header.

PAY QR sample SPAYD QR sample

Note for SPAYD: only the fields below are used when generating the SPAYD payload.

SPAYD field mapping
SPAYD key Meaning Pay By Square field Note
ACC Counterparty identification BankAccounts Uses the first account from the list.
ALT-ACC Alternative accounts BankAccounts Uses all accounts except the first one.
AM Payment amount Amount
CC Payment currency CurrencyCode
DT Due date PaymentDueDate
MSG Message for recipient PaymentNote
X-VS Variable symbol VariableSymbol
X-SS Specific symbol SpecificSymbol
X-KS Constant symbol ConstantSymbol
RN Recipient name BeneficiaryName

Format specification:

Authorizations:
Using HTTP Authorization header
query Parameters
formats
string
Example: formats=pay,spayd

Comma-separated list of requested output formats. Supported tokens: pay, spayd. Examples:

  • /generate/pay?formats=spayd
  • /generate/pay?formats=pay,spayd
Request Body schema: application/json
invoiceId
string
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
Example
{
  • "payments": [
    • {
      • "amount": 12.34,
      • "currencyCode": "EUR",
      • "bankAccounts": [
        • {
          • "iban": "SK8975000000000012345671"
          }
        ],
      • "beneficiaryName": "A",
      • "paymentNote": "Monthly subscription",
      • "variableSymbol": "1234567890"
      }
    ]
}

Response samples

Content type
Example
{
  • "contentType": "image/png",
  • "format": "pay",
  • "image": "iVBORw0KG...base64 encoded PNG image data",
  • "payload": "0003G000FQ5D2ING92PTN9NSUVOENM25ALB59SIMJKNBAJQ244S31UOGUAH7C4ULCGBEGV34FG00"
}

Generate payment QR

Fast, single-request endpoint that returns a PNG QR image instantly. All inputs are passed as GET query parameters. Set format=pay or format=spayd. Authentication is done via the key query parameter. Alternatively, you can provide the API key in the Authorization header.

query Parameters
key
required
string
Example: key=YOUR_API_KEY

API key (query parameter authorization).

iban
required
string^[A-Z]{2}[0-9]{2}[A-Z0-9]{0,30}$
Example: iban=SK8975000000000012345671

Beneficiary IBAN.

bic
string^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
Example: bic=CEKOSKBX

Beneficiary BIC.

beneficiary
required
string non-empty \S
Example: beneficiary=A

Beneficiary name.

amount
required
number
Example: amount=1

Payment amount.

currency
required
string^[A-Z]{3}$
Example: currency=EUR

Currency code.

vs
string^[0-9]{0,10}$
Example: vs=12345

Variable symbol.

ks
string^[0-9]{0,4}$
Example: ks=0308

Constant symbol.

ss
string^[0-9]{0,10}$
Example: ss=0001

Specific symbol.

invoice
string
Example: invoice=INV-2026-0001

Invoice number.

string or string
Example: due=2025-01-31

Payment due date (YYYY-MM-DD or RFC3339/RFC3339Nano).

note
string
Example: note=payment note

Payment note (can be empty).

format
string
Default: "pay"
Enum: "pay" "spayd"

Output format.

Responses

Request samples 

https://api.bysquare.com/generate/pay?key=YOUR_API_KEY&iban=SK8975000000000012345671&beneficiary=A&amount=1&currency=EUR&vs=12345&note=payment%20note&format=pay

Response samples

Content type
image/png
PNG image

Generate invoice QR

Generates a by square invoice QR payload. If Accept includes image/png, the response is a raw PNG; otherwise JSON with base64-encoded image data is returned.

Invoice QR sample
Authorizations:
Using HTTP Authorization header
Request Body schema: application/json
invoiceId
required
string
required
string or string

YYYY-MM-DD or RFC3339/RFC3339Nano.

string or string

YYYY-MM-DD or RFC3339/RFC3339Nano.

orderId
string
deliveryNoteId
string
localCurrencyCode
required
string^[A-Z]{3}$
foreignCurrencyCode
string^[A-Z]{3}$
currRate
number
referenceCurrRate
number
required
object
required
object
numberOfInvoiceLines
integer >= 0

Cannot be combined with singleInvoiceLine.

invoiceDescription
string
object
required
Array of objects non-empty
paymentMeans
Array of integers non-empty unique
Items Enum: 1 2 4 8 16 32 64

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "INV-2025-0001",
  • "issueDate": "2025-01-15",
  • "taxPointDate": "2025-01-15",
  • "orderId": "ORD-2025-0042",
  • "deliveryNoteId": "DN-2025-0007",
  • "localCurrencyCode": "EUR",
  • "supplierParty": {
    • "partyName": "Example Supplier s.r.o.",
    • "companyTaxId": "12345678",
    • "companyVatId": "SK1234567890",
    • "postalAddress": {
      • "streetName": "Main Street",
      • "buildingNumber": "12",
      • "cityName": "Bratislava",
      • "postalZone": "81101",
      • "country": "SVK"
      },
    • "contact": {
      • "name": "Billing",
      • "telephone": "+421900000000",
      • "email": "billing@example.com"
      }
    },
  • "customerParty": {
    • "partyName": "Example Customer a.s.",
    • "companyTaxId": "87654321",
    • "companyVatId": "SK0987654321",
    • "partyIdentification": "CUSTOMER-001"
    },
  • "invoiceDescription": "Consulting services",
  • "singleInvoiceLine": {
    • "itemName": "Vedenie účtovníctva za 2Q 2013",
    • "periodFromDate": null,
    • "periodToDate": null,
    • "invoicedQuantity": 2,
    • "unitPriceTaxExclusiveAmount": 50,
    • "unitPriceTaxInclusiveAmount": 60,
    • "unitPriceTaxAmount": 10
    },
  • "taxCategorySummaries": [
    • {
      • "classifiedTaxCategory": 20,
      • "taxExclusiveAmount": 100,
      • "taxInclusiveAmount": 120,
      • "taxAmount": 20
      }
    ]
}

Response samples

Content type
{
  • "image": "iVBORw0KG...base64 encoded PNG image data",
  • "contentType": "image/png",
  • "payload": "0003G00..."
}

Read

Decode QR payload

Decodes a by square payload string into its structured document, including invoice and SPAYD QR codes. If keep is true, the decoded document is stored on the server.

Authorizations:
Using HTTP Authorization header
query Parameters
keep
boolean
Default: false

Store decoded documents on the server when true. Example:

  • /read?keep=1
Request Body schema: application/json
payload
required
string

Responses

Request samples

Content type
application/json
{
  • "payload": "0003G000FQ5D2ING92PTN9NSUVOENM25ALB59SIMJKNBAJQ244S31UOGUAH7C4ULCGBEGV34FG00"
}

Response samples

Content type
application/json
{
  • "payload": "0003G000FQ5D2ING92PTN9NSUVOENM25ALB59SIMJKNBAJQ244S31UOGUAH7C4ULCGBEGV34FG00",
  • "format": "pay",
  • "document": {
    • "payments": [
      • {
        • "paymentOptions": [
          • "paymentorder"
          ],
        • "amount": 1,
        • "currencyCode": "EUR",
        • "bankAccounts": [
          • {
            • "iban": "SK8975000000000012345671"
            }
          ],
        • "beneficiaryName": "A"
        }
      ]
    }
}

Decode QR image/file

Upload a file (multipart/form-data) or send raw binary data containing a QR code. If keep is true, decoded documents are stored on the server.

Authorizations:
Using HTTP Authorization header
query Parameters
keep
boolean
Default: false

Store decoded documents on the server when true. Example:

  • /read/file?keep=1
Request Body schema:
file
required
string <binary>

Responses

Request samples 

curl --request POST \
  --url https://api.bysquare.com/read/file \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@qr.png'

Response samples

Content type
application/json
[
  • {
    • "payload": "0003G000FQ5D2ING92PTN9NSUVOENM25ALB59SIMJKNBAJQ244S31UOGUAH7C4ULCGBEGV34FG00",
    • "format": "pay",
    • "document": {
      • "payments": [
        • {
          • "paymentOptions": [
            • "paymentorder"
            ],
          • "amount": 1,
          • "currencyCode": "EUR",
          • "bankAccounts": [
            • {
              • "iban": "SK8975000000000012345671"
              }
            ],
          • "beneficiaryName": "A"
          }
        ]
      }
    }
]