{ "openapi": "3.0.3", "info": { "title": "Payment Processing Backend", "version": "1.0.0", "description": "Internal JOD transfers, exact decimal scale 3, synchronous PostgreSQL commit." }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/payments": { "post": { "operationId": "submitPayment", "summary": "Transfer funds atomically", "description": "Requires payments:submit scope, debit ownership/grant and allowed destination. Existing rejection is replayed. Infrastructure failures are transient: query or retry the same UUID.", "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 or VALIDATION_FAILED", "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", "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, or 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" } } }, "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" } } }, "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" } } } }, "201": { "description": "First completed transfer; committed before this response.", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Location": { "schema": { "type": "string" }, "description": "/api/v1/payments/{paymentId}" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "200": { "description": "Same canonical payload replays the original receipt. A stored rejected outcome replays its original rejection status.", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } } } } }, "/api/v1/payments/{paymentId}": { "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "retrievePayment", "summary": "Retrieve an authorized stored outcome", "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "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", "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, or 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" } } }, "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" } } }, "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" } } } }, "200": { "description": "Stored COMPLETED receipt or REJECTED error 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": { "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getBalance", "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "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", "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, or 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" } } }, "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" } } }, "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" } } } }, "200": { "description": "Current persisted balance; requires accounts:read and account ownership.", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Balance" } } } } } } }, "/api/v1/admin/reconciliation": { "get": { "operationId": "reconcile", "responses": { "400": { "description": "MALFORMED_MESSAGE or VALIDATION_FAILED", "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", "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, or 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" } } }, "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" } } }, "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" } } } }, "200": { "description": "Read-only consistent snapshot; requires admin group.", "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } }, "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": { "PaymentInstruction": { "type": "object", "additionalProperties": false, "required": [ "paymentId", "fromAccount", "toAccount", "amount", "date", "purpose" ], "properties": { "paymentId": { "type": "string", "format": "uuid" }, "fromAccount": { "type": "string", "maxLength": 128, "minLength": 1 }, "toAccount": { "type": "string", "maxLength": 128, "minLength": 1 }, "amount": { "oneOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,3})?$" }, { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, "multipleOf": 0.001 } ] }, "date": { "type": "string", "format": "date-time" }, "purpose": { "type": "string", "maxLength": 255 }, "notes": { "type": "string", "maxLength": 1000 } }, "xml": { "name": "payment" } }, "Receipt": { "type": "object", "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}$", "example": "125.750" }, "currency": { "type": "string", "enum": [ "JOD" ] }, "processedAt": { "type": "string", "format": "date-time" } }, "xml": { "name": "response" } }, "Error": { "type": "object", "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" } }, "xml": { "name": "response" } }, "Balance": { "type": "object", "properties": { "accountId": { "type": "string" }, "balance": { "type": "string", "example": "500.000" }, "currency": { "type": "string", "enum": [ "JOD" ] } } }, "Reconciliation": { "type": "object", "properties": { "balanced": { "type": "boolean" }, "paymentDiscrepancies": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "accountDiscrepancies": { "type": "array", "items": { "type": "string" } } } } } } }