{ "openapi": "3.0.3", "info": { "title": "Internal JOD Payment Service", "version": "1.0.0", "description": "All responses support JSON or XML. Correlation IDs are generated per request; no public header is trusted. TLS and OIDC are required in production." }, "servers": [ { "url": "https://payments.example.test" } ], "paths": { "/api/v1/payments": { "post": { "summary": "Submit an internal JOD transfer; requires payments:write. First completion 201, identical replay 200. Durable rejections replay their original status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stored result, including a durable REJECTED result for lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED, HTTPS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND (concealed resources)", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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", "example": 2 } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE; query/retry same ID", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Committed transfer", "headers": { "Location": { "schema": { "type": "string" } }, "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } } }, "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 payment INV-2048", "notes": "October services" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": "d92192df-f79a-4553-8120-5660d2eb1294ACC-1001ACC-2002125.7502026-10-28T13:30:00+03:00Invoice payment INV-2048October services" } } } } }, "/api/v1/payments/{paymentId}": { "get": { "summary": "Get a stored payment result; requires payments:read. Unrelated principals receive 404.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stored result, including a durable REJECTED result for lookup", "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" } ] } } } }, "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED, HTTPS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND (concealed resources)", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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", "example": 2 } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE; query/retry same ID", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/accounts/{accountId}/balance": { "get": { "summary": "Read an owned or explicitly granted account; requires accounts:read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stored result, including a durable REJECTED result for lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED, HTTPS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND (concealed resources)", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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", "example": 2 } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE; query/retry same ID", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ] } }, "/api/v1/admin/reconciliation": { "get": { "summary": "Consistent snapshot reconciliation; requires payments:admin.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stored result, including a durable REJECTED result for lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED, HTTPS_REQUIRED", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ACCOUNT_NOT_FOUND or PAYMENT_NOT_FOUND (concealed resources)", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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", "example": 2 } } }, "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" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE; query/retry same ID", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Payment": { "type": "object", "xml": { "name": "payment" }, "additionalProperties": false, "required": [ "paymentId", "fromAccount", "toAccount", "amount", "date", "purpose" ], "properties": { "paymentId": { "type": "string", "format": "uuid", "description": "Canonical lowercase UUID; not trimmed" }, "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": "^\\d+(\\.\\d{1,3})?$" } ], "description": "Parsed as BigDecimal. Decimal string or number; ordinary decimal notation, no exponent; no rounding." }, "date": { "type": "string", "format": "date-time", "description": "Explicit UTC offset required; maximum 5 minutes future / 30 days old by default." }, "purpose": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Trimmed before fingerprinting." }, "notes": { "type": "string", "maxLength": 1000, "description": "Trimmed; absent/null and empty canonicalize to empty." } } }, "Receipt": { "type": "object", "xml": { "name": "response" }, "required": [ "paymentId", "status", "fromAccount", "toAccount", "amount", "currency", "processedAt" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "COMPLETED" ] }, "fromAccount": { "type": "string" }, "toAccount": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] }, "processedAt": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "xml": { "name": "response" }, "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", "required": [ "field", "code", "message" ], "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": "^\\d+\\.\\d{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] } } }, "Reconciliation": { "type": "object", "properties": { "healthy": { "type": "boolean" }, "paymentAnomalies": { "type": "array", "items": { "type": "object" } }, "balanceAnomalies": { "type": "array", "items": { "type": "object" } }, "checkedAt": { "type": "string", "format": "date-time" } } } } } }