{ "openapi": "3.1.0", "info": { "title": "MAN API", "version": "5.29.2", "description": "MAN API by MAN SYSTEMS GROUP. Secure payment creation, OTP confirmation, status tracking, webhooks and fulfillment through one unified MAN interface." }, "servers": [ { "url": "https://api.man.ps/api/v1" } ], "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "MAN API Key" }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp", "description": "10-digit Unix timestamp" }, "Signature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Lowercase HMAC-SHA256 hex of METHOD, path, timestamp and raw body hash" } }, "parameters": { "PaymentReference": { "name": "payment_reference", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 80 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 160, "pattern": "^[A-Za-z0-9_.:-]+$" } } }, "schemas": { "Payment": { "type": "object", "required": [ "success", "payment_reference", "external_reference", "status", "amount", "currency" ], "properties": { "success": { "type": "boolean", "const": true }, "payment_reference": { "type": "string" }, "external_reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "next_action": { "type": [ "string", "null" ], "examples": [ "confirm_otp" ] }, "max_otp_attempts": { "type": "integer" }, "otp_attempts_remaining": { "type": [ "integer", "null" ] }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "const": "ILS" }, "failure_reason": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "fulfillment": { "$ref": "#/components/schemas/Fulfillment" } } }, "PaymentStatus": { "type": "string", "enum": [ "created", "otp_sent", "requires_action", "processing", "paid", "failed", "expired", "cancelled", "refunded" ] }, "Fulfillment": { "type": [ "object", "null" ], "properties": { "status": { "$ref": "#/components/schemas/FulfillmentStatus" }, "delivery_reference": { "type": [ "string", "null" ] }, "attempt_count": { "type": "integer", "minimum": 0 }, "failure_code": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FulfillmentStatus": { "type": "string", "enum": [ "waiting_payment", "ready", "processing", "delivered", "failed", "review", "cancelled" ] }, "Error": { "type": "object", "required": [ "success", "error_code", "message", "request_id" ], "properties": { "success": { "type": "boolean", "const": false }, "error_code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": {} } } }, "responses": { "Unauthorized": { "description": "Missing, expired or invalid API authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Validation": { "description": "Validation or payment-state error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Payment was not found for this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/merchant": { "get": { "summary": "Validate MAN credentials and inspect merchant readiness", "responses": { "200": { "description": "MAN merchant identity, limits and readiness", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments": { "post": { "summary": "Create a payment through MAN API", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "mobile", "external_reference" ], "properties": { "amount": { "type": [ "number", "string" ], "examples": [ "5.00" ] }, "currency": { "type": "string", "const": "ILS", "default": "ILS" }, "mobile": { "type": "string", "pattern": "^(059|056)[0-9]{7}$" }, "external_reference": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Payment completed immediately", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "201": { "description": "Payment created; inspect status and next_action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Replay or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "description": "API rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payments/{payment_reference}/confirm": { "post": { "summary": "Confirm customer OTP", "parameters": [ { "$ref": "#/components/parameters/PaymentReference" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "otp" ], "properties": { "otp": { "type": "string", "pattern": "^\\d{4,8}$" } } } } } }, "responses": { "200": { "description": "Current payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Validation" } } } }, "/payments/{payment_reference}": { "get": { "summary": "Read the latest MAN payment state", "parameters": [ { "$ref": "#/components/parameters/PaymentReference" } ], "responses": { "200": { "description": "Current payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/{payment_reference}/cancel": { "post": { "summary": "Cancel an open payment, or accept Cards-confirmed cancellation after 3 minutes", "parameters": [ { "$ref": "#/components/parameters/PaymentReference" } ], "responses": { "200": { "description": "Cancelled or current payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Validation" }, "409": { "description": "Cancellation confirmation arrived before the configured hold window elapsed" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed": { "type": "boolean", "description": "Set true only when the client project has definitively cancelled the order after the configured hold window." }, "reason": { "type": "string", "maxLength": 500 } } } } } } } }, "/payments/{payment_reference}/fulfillment": { "post": { "summary": "Acknowledge product delivery after a paid payment", "description": "The merchant backend calls this endpoint. MAN never receives card credentials or delivers the product itself.", "parameters": [ { "$ref": "#/components/parameters/PaymentReference" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "processing", "delivered", "failed" ] }, "delivery_reference": { "type": "string", "maxLength": 180, "description": "Required for delivered; never send card username or password" }, "failure_code": { "type": "string", "maxLength": 80 }, "failure_reason": { "type": "string", "maxLength": 500, "description": "Required for failed" } } } } } }, "responses": { "200": { "description": "Current fulfillment state", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Idempotency or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/Validation" } } } } } }