x9-spec

name: x9-spec description: X9.150 Secure Payment QR Code specification reference — OpenAPI schemas, field constraints, EMVCo TLV tags, JWS security, payment lifecycle user-invocable: false

X9.150 Specification Reference

You are an expert on the ANSI X9.150 Secure Payment QR Code standard. Use this knowledge when answering questions about X9.150, payment QR codes, JWS security in payments, or EMVCo QR structures.

Three-Server Architecture

Payment Lifecycle

1. Template → qr_generator.py reads templates/*.json, builds EMVCo QR string + JSON payload
2. QR Scan → Payer scans QR, extracts URL from Tag 26 Subtag 01
3. Fetch → POST /fetch/<id> with JWS-wrapped FetchRequestPayload → receives JWS-wrapped PaymentRequest
4. Payment → Payer executes payment on the selected network (e.g., Solana USDC)
5. Notify → POST /notify/<id> with JWS-wrapped NotificationPayload → receives JWS-wrapped SignedStatusCodePayload

Payment Status Lifecycle

ACTIVE → PAYMENT_INITIATED → PAID
   ↓
CANCELLED

• ACTIVE — payload available for payment
• PAYMENT_INITIATED — payment started (pre-commit notification, no transactionId yet)
• PAID — payment confirmed (second notification includes transactionId)
• CANCELLED — payload cancelled

OpenAPI Schemas

PaymentRequest (root container)

Required fields: id, revision, qrCodeContent, createdAt, revisedAt, sentAt, validUntil, status, creditor, bill, paymentMethods

Timestamp Format

• UTC RFC 3339 with mandatory millisecond precision: 2024-04-30T12:00:00.000Z
• Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
• Max length: 24

Creditor

Required: MCC, name, address

Address

Required: city, country

• US: country: "US", postalCode: ^\d{5}(-\d{4})?$
• International: country: ^[A-Z]{2}$, postalCode: ^[ -~]*$ max 20

Bill

Required: paymentTiming, amountDue

• paymentTiming: immediate or deferred
• If deferred → invoice with dueDate is required
• amountDue: required amount (MonetaryAmount) + currency (CurrencyCode)
• tip.allowed: if true → range required (min/max 0–999, representing percentage × 10)
• tip.presets: array of 1–10 integers (suggested tip percentages × 10)
• adjustments: array of {explanation, amount (SignedMonetaryAmount), validUntil}

MonetaryAmount Encoding

• Integer in minor currency units (e.g., cents for USD)
• amount: 56 = $0.56 USD
• amount: 560000 = 560,000 USDC base units (6 decimals)
• Positive values represent surcharges; negative values represent discounts (SignedMonetaryAmount)

PaymentMethod

Required: currency, amount, validUntil, networks

TraditionalNetworkDetails

Required: routingNumber, accountNumber, protectionType

• routingNumber: ^\d{9}$
• accountNumber: ^\d{1,17}$
• protectionType: tokenized, encrypted, or plaintext

FetchRequestPayload

Required: qrCodeContent

• qrCodeContent: ^[a-zA-Z0-9_-]{0,1024}$

NotificationPayload

Required: id, payment

• payment.amount (MonetaryAmount), payment.currency (CurrencyCode), payment.network (string max 35) — all required
• payment.transactionId (string max 128) — absent on initiation, present on completion
• payment.tipAmount (MonetaryAmount) — optional
• payer — flexible object, payer.info optional
• expectedDate — optional Timestamp

SignedStatusCodePayload

Required: statusCode (integer, mirrors HTTP status)

JWS Security Layer

Protected Header (JWSHeader)

Required: iat, ttl, correlationId, crit

Certificate Discovery Priority

1. x5t#S256 — thumbprint lookup in local cache
2. x5c — certificate chain embedded in JWS header (X9 Financial PKI)
3. jku — fetch JWKS from URL (self-signed ECC certs)

Freshness Validation

• iat must not be in future (60s clock skew allowed)
• iat must not be older than 8 minutes (480s)
• ttl (milliseconds) must not have passed
• correlationId in response must match request (non-repudiation)

Content-Type

All JWS endpoints use Content-Type: application/jose

EMVCo QR Code Structure (TLV)

TLV Encoding

• Each field: [Tag:2][Length:2][Value:Length]
• Tag 63 (CRC) must be last — CRC covers everything before its value
• Tag 26 uses nested TLV for subtags
• URL in Tag 26.01 omits https:// to save space

CRC-16 Algorithm

• Polynomial: 0x1021 (CRC-16/CCITT-FALSE)
• Initial: 0xFFFF
• Input: entire QR string including 6304 prefix, excluding the 4-char CRC value

Testing Flags

Key Files

• spec/openapi.yaml — authoritative OpenAPI schema
• qr_server.py — canonical JWS sign/verify implementation
• qr_payer.py — full payer flow (scan → fetch → verify → pay → notify)
• qr_parser.py — EMVCo TLV parser
• keygen.py — ECC key pair + self-signed certificate generation
• templates/*.json — payment request templates