{ "openapi": "3.0.3", "info": { "title": "Internal JOD Payment Processing API", "version": "1.0.0", "description": "All financial endpoints require TLS and validated bearer JWTs. Responses default to JSON; Accept application/xml requests XML. Scope strings are space-delimited OAuth permissions. Local development may explicitly disable TLS enforcement." }, "servers": [ { "url": "https://payments.example.invalid" } ], "paths": { "/api/v1/payments": { "post": { "operationId": "submitPayment", "summary": "Atomically transfer JOD between internal accounts", "description": "The caller must own or be explicitly authorized to debit the source; destination must permit receipt. Duplicate properties/elements, coercion and unsafe XML are rejected. The body is bounded to 64 KiB by default. Rejections are durable and corrected instructions require a new payment ID. Identical normalized payload replay returns the original outcome.", "security": [ { "oauth2": [ "payments:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInstruction" }, "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/PaymentInstruction" }, "example": "d92192df-f79a-4553-8120-5660d2eb1294ACC-1001ACC-2002125.7502026-10-28T13:30:00+03:00Invoice payment INV-2048October services" } } }, "responses": { "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN, HTTPS_REQUIRED (protected account existence is concealed)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND, ACCOUNT_NOT_FOUND (only when disclosure is safe)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE (retry or query using the original payment ID)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "First successful transfer, committed before response", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" }, "description": "/api/v1/payments/{paymentId}" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "paymentId": "d92192df-f79a-4553-8120-5660d2eb1294", "fromAccount": "ACC-1001", "toAccount": "ACC-2002", "amount": "125.750", "status": "COMPLETED", "currency": "JOD", "processedAt": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "200": { "description": "Identical successful replay; no funds moved again", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "paymentId": "d92192df-f79a-4553-8120-5660d2eb1294", "fromAccount": "ACC-1001", "toAccount": "ACC-2002", "amount": "125.750", "status": "COMPLETED", "currency": "JOD", "processedAt": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } } } } }, "/api/v1/payments/{paymentId}": { "get": { "operationId": "getPayment", "summary": "Retrieve a durable completed or rejected outcome", "security": [ { "oauth2": [ "payments:read" ] } ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN, HTTPS_REQUIRED (protected account existence is concealed)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND, ACCOUNT_NOT_FOUND (only when disclosure is safe)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE (retry or query using the original payment ID)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Stored outcome. Unknown and unauthorized payment existence is concealed with 404.", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "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", "summary": "Read an authorized persisted account balance", "security": [ { "oauth2": [ "payments:read" ] } ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN, HTTPS_REQUIRED (protected account existence is concealed)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND, ACCOUNT_NOT_FOUND (only when disclosure is safe)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE (retry or query using the original payment ID)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Authorized balance", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "accountId": "ACC-1001", "balance": "374.250", "currency": "JOD" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Balance" } } } } } } }, "/api/v1/operations/reconciliation": { "get": { "operationId": "reconcile", "summary": "Privileged repeatable-read ledger and opening-baseline reconciliation", "security": [ { "oauth2": [ "payments:admin" ] } ], "responses": { "400": { "description": "MALFORMED_MESSAGE, VALIDATION_FAILED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "FORBIDDEN, HTTPS_REQUIRED (protected account existence is concealed)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND, ACCOUNT_NOT_FOUND (only when disclosure is safe)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "406": { "description": "NOT_ACCEPTABLE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ACCOUNT_NOT_ACTIVE, INSUFFICIENT_FUNDS, IDEMPOTENCY_CONFLICT, PAYMENT_LIMIT_EXCEEDED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "TEMPORARILY_UNAVAILABLE (retry or query using the original payment ID)", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } }, "Retry-After": { "description": "Suggested delay in seconds", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": "ERROR", "code": "VALIDATION_FAILED", "message": "The request could not be completed.", "issues": [ { "field": "amount", "code": "INVALID_AMOUNT", "message": "Amount must be positive, at most three decimals, and within the payment maximum." } ], "correlationId": "84b2e7b7-df46-4a7e-aa50-87352a37fd4f", "timestamp": "2026-10-28T10:30:01Z" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Report discrepancies; no automatic repair", "headers": { "X-Correlation-ID": { "description": "Generated ID, or an ID accepted from a configured trusted ingress", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" }, "example": { "consistent": true, "issues": [] } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://identity.example.invalid/oauth/token", "scopes": { "payments:write": "Submit permitted payments", "payments:read": "Read authorized receipts and balances", "payments:admin": "Run operational reconciliation and metrics" } } } } }, "schemas": { "PaymentInstruction": { "type": "object", "additionalProperties": false, "xml": { "name": "payment" }, "required": [ "paymentId", "fromAccount", "toAccount", "amount", "date", "purpose" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "fromAccount": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" }, "toAccount": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" }, "amount": { "description": "Positive JOD decimal; at most three fractional digits, default maximum 10000.000. Numeric exponent notation is rejected.", "oneOf": [ { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, "multipleOf": 0.001 }, { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,3})?$" } ] }, "date": { "type": "string", "format": "date-time", "description": "Offset required; default window: past 30 days through future 5 minutes" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required nonblank text, trimmed" }, "notes": { "type": "string", "maxLength": 1000, "description": "Optional trimmed text; empty allowed, explicit null rejected" } } }, "Receipt": { "type": "object", "xml": { "name": "receipt" }, "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": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] }, "processedAt": { "type": "string", "format": "date-time" } } }, "Issue": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "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": { "$ref": "#/components/schemas/Issue" }, "xml": { "wrapped": true } }, "correlationId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "Balance": { "type": "object", "xml": { "name": "balance" }, "properties": { "accountId": { "type": "string" }, "balance": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] } } }, "Reconciliation": { "type": "object", "xml": { "name": "reconciliation" }, "properties": { "consistent": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PAYMENT_LEDGER", "ACCOUNT_BALANCE", "LEDGER_SNAPSHOT" ] }, "reference": { "type": "string" } } } } } } } } }