{ "openapi": "3.0.3", "info": { "title": "Payment Processing API", "version": "1.0.0" }, "servers": [ { "url": "https://localhost:8443" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/payments": { "post": { "operationId": "submitPayment", "description": "Requires payments:write and account debit authorization. Exact JOD decimal input. Duplicate ID and equivalent canonical payload replay original receipt or rejection. Altered payload returns 409. Only purpose and notes trimmed. Date offsets and decimal scale canonicalized. Maximum default body 64 KiB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "paymentId": "d92192df-f79a-4553-8120-5660d2eb1294", "fromAccount": "ACC-1001", "toAccount": "ACC-2002", "amount": "125.750", "date": "2026-10-28T13:30:00+03:00", "purpose": "Invoice INV-2048" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": "d92192df-f79a-4553-8120-5660d2eb1294ACC-1001ACC-2002125.7502026-10-28T13:30:00+03:00Invoice INV-2048" } } }, "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN or TLS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "First committed transfer", "headers": { "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "200": { "description": "Original completed receipt replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } } } } }, "/api/v1/payments/{paymentId}": { "get": { "operationId": "getPayment", "description": "Requires payments:read; original requester or administrator. Returns original COMPLETED or REJECTED outcome. Hidden and unknown payments return 404.", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN or TLS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Stored outcome", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Receipt" }, { "$ref": "#/components/schemas/Error" } ] } }, "application/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Receipt" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/accounts/{accountId}/balance": { "get": { "operationId": "getBalance", "description": "Requires payments:read and account ownership/view/debit grant. Unknown and hidden accounts both return 404.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN or TLS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Persisted balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Balance" } } } } } } }, "/api/v1/admin/reconciliation": { "get": { "operationId": "reconcile", "description": "Requires payments:admin. Consistent snapshot of ledger/account discrepancies.", "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN or TLS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Reconciliation snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Payment": { "type": "object", "additionalProperties": false, "xml": { "name": "payment" }, "required": [ "paymentId", "fromAccount", "toAccount", "amount", "date", "purpose" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "fromAccount": { "type": "string", "minLength": 1, "maxLength": 128 }, "toAccount": { "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "oneOf": [ { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, "multipleOf": 0.001 }, { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,3})?$" } ] }, "date": { "type": "string", "format": "date-time" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 255 }, "notes": { "type": "string", "maxLength": 1000, "nullable": true } } }, "Receipt": { "type": "object", "xml": { "name": "receipt" }, "required": [ "paymentId", "status", "fromAccount", "toAccount", "amount", "currency", "processedAt" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "fromAccount": { "type": "string", "minLength": 1, "maxLength": 128 }, "toAccount": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "COMPLETED" ] }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] }, "processedAt": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "xml": { "name": "error" }, "required": [ "status", "code", "message", "issues", "correlationId", "timestamp" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ERROR", "REJECTED" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "correlationId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" } } }, "Balance": { "type": "object", "properties": { "accountId": { "type": "string" }, "availableBalance": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] } } }, "Reconciliation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "BALANCED", "MISMATCH" ] }, "findings": { "type": "array", "items": { "type": "object" } } } } } } }