Governance & Adoption
- Audience: ISVs, Gateways, Processors, Networks, Acquiring Banks
- License: MIT (permissive, adoption-first)
- Compatibility:
- Backward compatible by default
- Explicit versioning (
v1,v1.1,v2) - Industry Profiles (Retail, Automotive, Dental, eCom, Retail, etc.)
Core Architecture of the Standard
Every transaction is:
- Event-driven
- State-machine backed
- Ledger-representable
This avoids the classic mess of:
- “auth table”
- “capture table”
- “settlement report”
- “deposit CSV”
All are views of the same object.
Transaction Lifecycle (State Machine)
Explicit intents (all first-class):
- SALE
- AUTHORIZATION
- CAPTURE
- INCREMENTAL_AUTH
- REVERSAL
- VOID
- REFUND
- CHARGEBACK
- REPRESENTMENT
- SETTLEMENT
- FUNDING
Partial actions are native:
- Partial capture
- Partial refund
- Split tender
- Multi-currency settlement
Each state transition:
- Creates an event
- Produces an immutable amount snapshot
- Optionally posts to a ledger
This is critical for:
- Reconciliation
- Audits
- AI replay/simulation
Payment Instruments (Abstracted, Extensible)
First-class abstractions:
- Card
- BankAccount
- Wallet
- CryptoWallet
- NetworkToken
- Cash
- BNPLAccount
- ElectronicCheck
- InternalToken
Each instrument carries capability flags:
- supports_pin
- supports_signature
- supports_cashback
- supports_installments
- supports_offline
Note: Signature debit vs PIN debit Modeled as different rails entirely, not a flag. This is huge for routing, cost, and compliance.
Networks as First-Class Entities
Networks are not strings. They are objects and supported explicitly:
- Visa
- Mastercard
- American Express
- Discover
- UnionPay
- Maestro
Each transaction carries:
- Intended network
- Eligible networks
- Actual routed network
- Optimization decision rationale
This enables:
- Cost optimization
- Regulated debit compliance
- AI explainability
Network Programs (Modeled Explicitly)
Examples:
- Visa CPS
- Visa Preferred
- Regulated Debit
- Amex ESA
- Visa Direct
These are qualifiers, not metadata. A transaction can say:
“I qualified for CPS but downgraded because field X missing.”
Note: That’s gold for savings, debugging, merchant education and AI recommendations.
Pricing, Fees & Amounts (Where Money Is Won)
Pricing Models (Explicit)
- Interchange++
- Flat
- Tiered
- Dual Pricing
- Surcharge
Chosen at onboarding per MID, but:
- Fee responsibility is per transaction
- Merchant-paid
- Customer-paid
- Split
- Subsidized
Fees as Line Items
- Line items
- Adjustments
- Never hidden in net numbers
This allows clean reconciliation, accurate statements, and transparent AI analysis.
Amounts & Currency (Strict Rules)
- Minor units only (pennies)
- ISO currency codes (USD, CAD, etc.)
- Banking-grade rounding rules
- FX conversion timestamps required
Every amount has a semantic role:
- Base
- Tax
- Tip
- Donation
- Cashback
- Surcharge
- Discount
- Network fee
Every lifecycle step creates an immutable snapshot.
Security, Fraud & Trust (Normalized)
Security Signals (Normalized)
- AVS
- CVV
- 3DS (frictionless vs challenge)
- SCA exemptions
3DS (Minimum Required)
- Version 2.2
- Directory Server
- Challenge indicators
- Liability shift result
Fraud Signals
- Embedded in transaction
- External references allowed
This supports AI fraud normalization and cross-processor risk models.
AI-First Capabilities (The Real Differentiator)
This standard is AI-native, not AI-compatible.
Built-in AI Hooks
- Optimization hints:
- “PIN debit eligible”
- “Lower interchange possible if field X present”
- “Tokenization recommended”
- Explainable decisions:
- Why this network?
- Why downgrade?
- Why surcharge disallowed?
- Training-ready fields:
- Risk vectors
- Merchant behavior
- Transaction patterns
AI Agents Can:
- Simulate transactions
- Replay history
- Recommend configuration changes
- Predict savings, risk, downgrades
Note: This is what allows AI to actually understand payments, not just classify them.
Extensibility & Future Rails
- Custom namespaces
- Vendor extensions
- Industry profiles
Supported rails:
- Crypto
- Stablecoins
- RTP / Real-time payments
- Cross-border wallets
Github Project
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "pmsai:payments:v1/Transaction.schema.json",
"title": "PMSAI Transaction",
"type": "object",
"additionalProperties": false,
"required": [
"standard",
"transaction_id",
"created_at",
"intent",
"channel",
"merchant",
"instrument",
"events",
"state",
"amounts",
"currency",
"routing",
"pricing",
"security"
],
"properties": {
"standard": {
"type": "object",
"additionalProperties": false,
"required": ["name", "version", "profile"],
"properties": {
"name": { "const": "PMSAI" },
"version": { "type": "string", "pattern": "^1\\.[0-9]+\\.[0-9]+$" },
"profile": {
"type": "string",
"description": "Industry profile identifier. Use 'core' if none.",
"examples": ["core", "retail.v1", "auto.v1", "dental.v1", "ecom.v1"]
}
}
},
"transaction_id": { "type": "string", "description": "Stable id across lifecycle." },
"idempotency_key": { "type": "string" },
"created_at": { "type": "string", "format": "date-time" },
"updated_at": { "type": "string", "format": "date-time" },
"intent": {
"type": "string",
"description": "Explicit transaction intent.",
"enum": [
"SALE",
"AUTHORIZATION",
"CAPTURE",
"INCREMENTAL_AUTH",
"REVERSAL",
"VOID",
"REFUND",
"CHARGEBACK",
"REPRESENTMENT",
"SETTLEMENT",
"FUNDING"
]
},
"channel": {
"type": "string",
"enum": ["CARD_PRESENT", "CARD_NOT_PRESENT", "MOTO", "ECOM", "WALLET", "API", "IN_APP", "POS"]
},
"state": {
"type": "string",
"description": "Lifecycle state (state-machine).",
"enum": [
"CREATED",
"AUTHORIZED",
"CAPTURED",
"REVERSED",
"VOIDED",
"REFUNDED",
"SETTLED",
"FUNDED",
"DISPUTED",
"CLOSED",
"FAILED"
]
},
"merchant": {
"type": "object",
"additionalProperties": false,
"required": ["merchant_id", "acquirer"],
"properties": {
"merchant_id": { "type": "string" },
"mid": { "type": "string" },
"mcc": { "type": "string" },
"acquirer": {
"type": "object",
"additionalProperties": false,
"required": ["acquirer_id"],
"properties": {
"acquirer_id": { "type": "string" },
"processor_id": { "type": "string" },
"sponsor_bank_id": { "type": "string" }
}
}
}
},
"instrument": {
"type": "object",
"additionalProperties": false,
"required": ["type", "capabilities"],
"properties": {
"type": {
"type": "string",
"enum": [
"CARD",
"BANK_ACCOUNT",
"ELECTRONIC_CHECK",
"WALLET",
"CRYPTO_WALLET",
"NETWORK_TOKEN",
"INTERNAL_TOKEN",
"BNPL_ACCOUNT",
"CASH"
]
},
"token": {
"type": "object",
"additionalProperties": false,
"properties": {
"internal_token_id": { "type": "string" },
"network_token_id": { "type": "string" },
"tokenization_method": {
"type": "string",
"enum": ["NONE", "NETWORK_TOKENIZATION", "GATEWAY_TOKENIZATION", "WALLET_TOKENIZATION"]
}
}
},
"card": {
"type": "object",
"additionalProperties": false,
"properties": {
"brand": {
"type": "string",
"enum": ["VISA", "MASTERCARD", "AMEX", "DISCOVER", "UNIONPAY", "MAESTRO", "OTHER"]
},
"funding_type": { "type": "string", "enum": ["CREDIT", "DEBIT", "PREPAID", "UNKNOWN"] },
"rail": {
"type": "string",
"description": "Different rails entirely for signature vs PIN debit.",
"enum": ["CREDIT_RAIL", "SIGNATURE_DEBIT_RAIL", "PIN_DEBIT_RAIL", "UNKNOWN"]
},
"bin": { "type": "string" },
"last4": { "type": "string" },
"expiration": { "type": "string", "pattern": "^(0[1-9]|1[0-2])/[0-9]{2}$" }
}
},
"capabilities": {
"type": "object",
"additionalProperties": false,
"required": ["supports_pin", "supports_cashback", "supports_installments", "supports_offline"],
"properties": {
"supports_pin": { "type": "boolean" },
"supports_cashback": { "type": "boolean" },
"supports_installments": { "type": "boolean" },
"supports_offline": { "type": "boolean" }
}
}
}
},
"currency": {
"type": "string",
"description": "ISO-4217 alpha-3",
"pattern": "^[A-Z]{3}$",
"examples": ["USD", "CAD", "EUR"]
},
"amounts": {
"type": "object",
"additionalProperties": false,
"required": ["minor_unit", "exponent", "snapshots"],
"properties": {
"minor_unit": {
"type": "string",
"const": "MINOR_ONLY",
"description": "Enforces pennies/minor units only."
},
"exponent": {
"type": "integer",
"description": "Currency exponent (USD=2, JPY=0, KWD=3)."
},
"snapshots": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": ["snapshot_id", "at", "lifecycle_step", "components"],
"properties": {
"snapshot_id": { "type": "string" },
"at": { "type": "string", "format": "date-time" },
"lifecycle_step": {
"type": "string",
"enum": [
"CREATED",
"AUTHORIZED",
"CAPTURED",
"SETTLED",
"FUNDED",
"REFUNDED",
"VOIDED",
"REVERSED",
"DISPUTED"
]
},
"rounding_rule": {
"type": "string",
"enum": ["BANKERS_ROUNDING", "ROUND_HALF_UP", "ROUND_DOWN", "PROCESSOR_SPECIFIC"]
},
"fx": {
"type": "object",
"additionalProperties": false,
"properties": {
"converted_from_currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
"conversion_rate": { "type": "number" },
"converted_at": { "type": "string", "format": "date-time" }
}
},
"components": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": ["role", "amount_minor"],
"properties": {
"role": {
"type": "string",
"enum": [
"BASE",
"TAX",
"TIP",
"DONATION",
"CASHBACK",
"SURCHARGE_FEE",
"DISCOUNT",
"NETWORK_FEE",
"PROCESSOR_FEE",
"ADJUSTMENT"
]
},
"amount_minor": { "type": "integer" },
"description": { "type": "string" }
}
}
}
}
}
}
}
},
"routing": {
"type": "object",
"additionalProperties": false,
"required": ["eligible_networks", "intended_network", "routed_network", "decision"],
"properties": {
"eligible_networks": {
"type": "array",
"minItems": 1,
"items": { "type": "string" }
},
"intended_network": { "type": "string" },
"routed_network": { "type": "string" },
"decision": {
"type": "object",
"additionalProperties": false,
"required": ["mode", "rationale"],
"properties": {
"mode": {
"type": "string",
"enum": ["MERCHANT_PREFERENCE", "COST_OPTIMIZATION", "NETWORK_MANDATE", "FALLBACK"]
},
"rationale": { "type": "string" },
"programs": {
"type": "array",
"items": {
"type": "string",
"description": "Network programs applied or evaluated (CPS, Visa Preferred, Amex ESA, Regulated Debit, Visa Direct, etc.)"
}
}
}
}
}
},
"pricing": {
"type": "object",
"additionalProperties": false,
"required": ["model", "program", "fee_responsibility", "fee_items", "disclosures"],
"properties": {
"model": {
"type": "string",
"enum": ["INTERCHANGE_PLUS", "FLAT", "TIERED", "DUAL_PRICING", "SURCHARGE"]
},
"program": {
"type": "string",
"description": "Chosen at onboarding by MID (but recorded on transaction)."
},
"fee_responsibility": {
"type": "string",
"enum": ["MERCHANT", "CUSTOMER", "SPLIT", "SUBSIDIZED"]
},
"fee_items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["type", "amount_minor"],
"properties": {
"type": {
"type": "string",
"enum": ["SURCHARGE", "PROCESSOR", "NETWORK", "ACQUIRER", "ADJUSTMENT", "DISCOUNT"]
},
"amount_minor": { "type": "integer" },
"as_adjustment": { "type": "boolean", "default": true },
"description": { "type": "string" }
}
}
},
"disclosures": {
"type": "object",
"additionalProperties": false,
"required": ["pre_auth_surcharge_display", "dual_pricing_visibility", "cash_vs_card_labels"],
"properties": {
"pre_auth_surcharge_display": { "type": "boolean" },
"dual_pricing_visibility": { "type": "boolean" },
"cash_vs_card_labels": { "type": "boolean" }
}
}
}
},
"security": {
"type": "object",
"additionalProperties": false,
"required": ["avs", "cvv", "three_ds", "sca"],
"properties": {
"avs": {
"type": "object",
"additionalProperties": false,
"properties": {
"result": { "type": "string" },
"raw": { "type": "string" }
}
},
"cvv": {
"type": "object",
"additionalProperties": false,
"properties": {
"result": { "type": "string" },
"raw": { "type": "string" }
}
},
"three_ds": {
"type": "object",
"additionalProperties": false,
"required": ["used", "version"],
"properties": {
"used": { "type": "boolean" },
"version": { "type": "string", "enum": ["2.2", "OTHER"] },
"directory_server": { "type": "string" },
"flow": { "type": "string", "enum": ["FRICTIONLESS", "CHALLENGE", "NOT_APPLICABLE"] },
"challenge_indicator": { "type": "string" },
"liability_shift": { "type": "boolean" }
}
},
"sca": {
"type": "object",
"additionalProperties": false,
"properties": {
"applied": { "type": "boolean" },
"exemption": { "type": "string" }
}
}
}
},
"fraud": {
"type": "object",
"additionalProperties": false,
"properties": {
"embedded_signals": { "type": "object" },
"external_references": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["provider", "reference_id"],
"properties": {
"provider": { "type": "string" },
"reference_id": { "type": "string" }
}
}
}
}
},
"ai": {
"type": "object",
"additionalProperties": false,
"properties": {
"optimization_hints": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["hint_type", "message"],
"properties": {
"hint_type": {
"type": "string",
"enum": ["LOWER_INTERCHANGE_IF", "PIN_DEBIT_ELIGIBLE", "TOKENIZATION_RECOMMENDED", "DATA_MISSING", "ROUTING_SUGGESTION"]
},
"message": { "type": "string" },
"required_fields": { "type": "array", "items": { "type": "string" } }
}
}
},
"explainability": {
"type": "object",
"additionalProperties": false,
"properties": {
"network_choice_reason": { "type": "string" },
"interchange_downgrade_reason": { "type": "string" },
"surcharge_disallowed_reason": { "type": "string" }
}
},
"training_fields": {
"type": "object",
"additionalProperties": true,
"description": "Risk vectors, merchant behavior, transaction patterns (feature-ready)."
}
}
},
"events": {
"type": "array",
"minItems": 1,
"items": { "$ref": "pmsai:payments:v1/TransactionEvent.schema.json" }
},
"ledger": {
"type": "object",
"additionalProperties": false,
"properties": {
"entries": {
"type": "array",
"items": { "$ref": "pmsai:payments:v1/LedgerEntry.schema.json" }
}
}
},
"extensions": {
"type": "object",
"description": "Vendor extensions + custom namespaces. Keys should be namespaced (e.g., 'strictly:*', 'elavon:*').",
"additionalProperties": true
}
}
}