{ "openapi": "3.0.3", "info": { "title": "Payment Processing API", "version": "1.0.0", "description": "Exact internal JOD transfers. Signed OAuth/OIDC JWT required; issuer, audience, expiry and scopes validated. Scope payments:write for POST, payments:read for GET, payments:admin for reconciliation." }, "servers": [ { "url": "https://localhost:8443" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/payments": { "post": { "summary": "Submit an atomic transfer", "description": "First success 201; identical canonical replay 200; changed payload 409. Durable rejected outcomes repeat the original error. Unknown/unauthorized sources return FORBIDDEN without disclosure. Request size 64 KiB. Duplicate JSON keys/XML elements and unknown fields are errors. DTD/entities/namespaces/nested XML are forbidden.", "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 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 INV-2048October services" } } }, "responses": { "201": { "description": "Completed and committed first instruction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "/api/v1/payments/{paymentId}" }, "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "200": { "description": "Original completed receipt on replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "/api/v1/payments/{paymentId}" }, "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/payments/{paymentId}": { "get": { "summary": "Retrieve stored outcome for originating caller", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stored completed or rejected receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/accounts/{accountId}/balance": { "get": { "summary": "Read owned or explicitly view-authorized balance", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current persisted balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/admin/reconciliation": { "get": { "summary": "Privileged consistent accounting report", "description": "Requires payments:admin scope.", "responses": { "200": { "description": "Reconciliation snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "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", "minLength": 1, "maxLength": 128 }, "toAccount": { "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "oneOf": [ { "type": "number", "exclusiveMinimum": 0, "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 } }, "xml": { "name": "payment" } }, "Receipt": { "type": "object", "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", "REJECTED" ] }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] }, "processedAt": { "type": "string", "format": "date-time" }, "rejectionCode": { "type": "string" } }, "xml": { "name": "receipt" } }, "Issue": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "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", "enum": [ "MALFORMED_MESSAGE", "VALIDATION_FAILED", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "ACCOUNT_NOT_FOUND", "NOT_ACCEPTABLE", "ACCOUNT_NOT_ACTIVE", "INSUFFICIENT_FUNDS", "IDEMPOTENCY_CONFLICT", "PAYMENT_LIMIT_EXCEEDED", "UNSUPPORTED_MEDIA_TYPE", "RATE_LIMITED", "TEMPORARILY_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "correlationId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" } }, "xml": { "name": "error" } }, "Balance": { "type": "object", "properties": { "accountId": { "type": "string" }, "balance": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{3}$" }, "currency": { "type": "string", "enum": [ "JOD" ] } }, "xml": { "name": "balance" } }, "Reconciliation": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "clean": { "type": "boolean" }, "invalidPayments": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "balanceMismatches": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "Error400": { "description": "Malformed structure or invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error401": { "description": "Missing or invalid JWT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error404": { "description": "Unknown or undisclosed record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error406": { "description": "Unsupported response format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error409": { "description": "Business rejection or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error413": { "description": "HTTP request body limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error415": { "description": "Unsupported input format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error429": { "description": "Principal rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error500": { "description": "Unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } }, "Error503": { "description": "Database unavailable or outcome uncertain; retry same ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Correlation-ID": { "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; emitted for 429/503" } } } } } }