Technical Specifications

Comprehensive technical documentation for implementing the payware universal payment standard. Built on open standards, designed for developers.

API Protocol Specifications

The payware API is built on modern RESTful principles with open standards for global interoperability.

RESTful API Architecture

Protocol

  • Transport: HTTPS/TLS 1.3
  • Authentication: Signature-based with partner identifier
  • Format: JSON (application/json, UTF-8)
  • Versioning: Header-based (Api-Version: 1)
  • Encoding: UTF-8

HTTP Methods

  • POST: Create transaction, process transaction
  • GET: Query transaction status and history
  • PATCH: Cancel transaction
  • Timestamps: UNIX timestamp format
  • Currency: ISO 3-letter codes, decimal format

Example Request

POST /api/transactions
Api-Version: 1
Content-Type: application/json

{
  "account": "GB29NWBK60161331926810",
  "friendlyName": "Your Favorite Shop",
  "callbackUrl": "https://merchant.com/callback",
  "trData": {
    "amount": "150.00",
    "currency": "GBP",
    "reasonL1": "Payment"
  },
  "trOptions": {
    "type": "QR",
    "timeToLive": 120
  }
}

Callback System

Real-time transaction status notifications via HTTPS POST to your callback URL.

Callback Types

  • • TRANSACTION_FINALIZED

Transaction Status

  • • CONFIRMED - Payment successful
  • • DECLINED - Payment declined by user
  • • FAILED - Payment processing error
  • • CANCELLED - Transaction cancelled

Delivery Guarantees

  • • 15 retry attempts (once per second)
  • • Requires 200 HTTP status response
  • • HTTPS-only callback URLs
  • • Idempotency support via passbackParams

Security & Cryptography

Encryption Standards

Transport Layer

TLS 1.3 with perfect forward secrecy, ECDHE key exchange

Data at Rest

AES-256-GCM encryption for stored sensitive data

Message Signing

HMAC-SHA256 and RSA-2048 digital signatures

Account Tokenization

Sensitive account information is never transmitted. Instead, tokens represent payment with limited scope and lifetime.

Lifespan: Multi-use or time-limited (2 minutes default)

Scope: Partner-specific, amount-limited

Payment Method Technical Details

Method Technology Data Format Range/Specs
QR Code 2D barcode scanning Encoded transaction data Up to 2KB payload, error correction
Barcode 1D/2D optical scanning Numeric/alphanumeric data Code 128, configurable dimensions
NFC Contactless transmission Transaction data via NFC tap 0-10cm proximity, ISO 14443 compatible
BLE Bluetooth proximity Transaction data via Bluetooth 0-50m range, Bluetooth 5.0+ support
Soundbite Human-hearable audio signature Registered sound triggers Any audible sound (music, jingles, effects)
Link HTTPS deep linking URL with payment parameters Secure HTTPS URLs, URL-safe encoding
Text Alphanumeric code entry 10-character payment code Any medium: SMS, messaging, email, paper

Integration Requirements

Minimum Requirements

  • HTTPS/TLS support for secure communication
  • Api-Version header in all API requests (Api-Version: 1)
  • HTTPS callback URL for receiving transaction updates
  • JSON message parsing (UTF-8 encoding)
  • Partner identifier and signature for API authentication

Recommended Best Practices

  • Use sandbox.payware.eu for integration and testing
  • Return HTTP 200 for callback acknowledgment
  • Poll transaction status via GET /transactions-history if callback fails
  • Set appropriate timeToLive for your use case (60-600 seconds)
  • Use passbackParams for idempotency and order tracking

Official SDKs & Libraries

Pre-built libraries for rapid integration across popular programming languages.

JavaScript / Node.js

npm install @payware/sdk

  • • TypeScript support
  • • Promise-based async
  • • React Native compatible

Python

pip install payware

  • • Async/await support
  • • Django integration
  • • Type hints included

Java

Maven/Gradle dependency

  • • Spring Boot starter
  • • Reactive streams
  • • Android support

PHP

composer require payware/php

  • • PSR-7/18 compatible
  • • Laravel package
  • • WordPress plugin

Ruby

gem install payware

  • • Rails integration
  • • RSpec test helpers
  • • ActiveRecord support

Go

go get payware.io/sdk

  • • Context-aware
  • • Zero dependencies
  • • Concurrent-safe

API Versioning & Lifecycle

Versioning Strategy

API version is specified via the Api-Version HTTP header. Minor/patch updates are backward-compatible.

Current: Api-Version: 1 (stable)

Method: Header-based versioning

Support: Minimum 24 months

Notice: 12 months before deprecation

Change Log Access

All API changes are documented with migration guides and example code.

  • Real-time changelog feed
  • Email notifications
  • Migration tooling

Ready to Start Building?

Access complete API documentation, code examples, and developer tools

View Developer Docs Contact Technical Team