{
  "components": {
    "responses": {
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "code": {
                  "type": "string"
                },
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "description": "Bad request"
      },
      "Forbidden": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "description": "Forbidden"
      },
      "InternalError": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "timestamp": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "description": "Internal server error"
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "description": "Unauthorized"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send the Foxpay merchant API key as Authorization: Bearer <key> for custom integration endpoints."
      },
      "UserAuth": {
        "bearerFormat": "JWT",
        "description": "User session bearer token.",
        "scheme": "bearer",
        "type": "http"
      },
      "WebhookSignature": {
        "description": "Foxpay webhook signature header. Custom integration deliveries use `X-Foxpay-Signature: sha256=<hex>` where `<hex>` is the HMAC-SHA256 of the exact raw JSON request body using the shop webhook secret.",
        "in": "header",
        "name": "X-Foxpay-Signature",
        "type": "apiKey"
      }
    }
  },
  "externalDocs": {
    "description": "Foxpay developer documentation, quickstarts, samples, and implementation guides.",
    "url": "https://docs.foxpay.it"
  },
  "info": {
    "contact": {
      "name": "Foxpay Development Team",
      "url": "https://app.foxpay.it"
    },
    "description": "Foxpay provides hosted checkout and payment APIs for merchants that need a direct server-side integration.\n\n## Custom integration flow\n\n1. Authenticate server-side requests with `Authorization: Bearer <apiKey>`.\n2. Create a hosted checkout handoff with `POST /payments/initialize`.\n3. Persist `paymentId`, `orderId`, `merchantId`, `amountCents`, `currency`, and `testMode`.\n4. Redirect the buyer to the returned `paymentUrl`.\n5. Poll `GET /payments/{paymentId}/status` for buyer-facing progress.\n6. Fetch `GET /payments/{paymentId}/bank-details` only when manual transfer instructions are needed.\n7. Reconcile final order state on your backend from signed webhook delivery.\n\n## Custom webhooks\n\nCustom API webhooks are merchant-hosted callbacks. You configure your HTTPS webhook URL and Foxpay posts status changes to that URL with `X-Foxpay-Signature`, `X-Foxpay-Event`, and `X-Foxpay-Delivery` headers. This is separate from the WooCommerce plugin webhook URL and should not point to a WooCommerce plugin endpoint.\n\n## Amounts and environments\n\nAll custom integration monetary amounts are integer cents. For example, `12345` means EUR 123.45. Use production credentials only against `https://app.foxpay.it/api`; use staging credentials against `https://staging.app.foxpay.it/api`.",
    "title": "Foxpay API",
    "version": "0.1.0-beta.1",
    "x-foxpay-docs-profile": "public",
    "x-foxpay-export-contract": "v1",
    "x-foxpay-legacy-swagger": "pre-production-only",
    "x-foxpay-source": "route-annotations",
    "x-logo": {
      "altText": "Foxpay",
      "url": "https://docs.foxpay.it/images/Foxpay-Full-White.svg"
    }
  },
  "openapi": "3.0.3",
  "paths": {
    "/health": {
      "get": {
        "description": "Check the health status of the Foxpay platform including database connectivity and system status",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "services": {
                      "properties": {
                        "application": {
                          "example": "running",
                          "type": "string"
                        },
                        "database": {
                          "example": "connected",
                          "type": "string"
                        },
                        "environment": {
                          "example": "production",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "status": {
                      "example": "healthy",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "uptime": {
                      "description": "Application uptime in seconds",
                      "type": "number"
                    },
                    "version": {
                      "example": "2.0.0",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "System is healthy"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "description": "Error details",
                      "type": "string"
                    },
                    "services": {
                      "properties": {
                        "application": {
                          "example": "running",
                          "type": "string"
                        },
                        "database": {
                          "example": "disconnected",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "status": {
                      "example": "unhealthy",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "System is unhealthy"
          }
        },
        "summary": "System health check",
        "tags": [
          "System"
        ]
      }
    },
    "/orders/{order_key}": {
      "get": {
        "description": "Validates the order key, verifies the associated store can accept payments, and returns a sanitized order payload for the checkout UI.",
        "parameters": [
          {
            "description": "WooCommerce order key in `wc_order_*` format.",
            "in": "path",
            "name": "order_key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Store identifier used to resolve the WooCommerce installation.",
            "in": "query",
            "name": "shopId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "metadata": {
                      "properties": {
                        "fetchedAt": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "orderKey": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        },
                        "shopId": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "order": {
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "currencySymbol": {
                          "type": "string"
                        },
                        "customer": {
                          "properties": {
                            "email": {
                              "format": "email",
                              "type": "string"
                            },
                            "fullName": {
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "id": {
                          "type": "integer"
                        },
                        "lineItems": {
                          "items": {
                            "properties": {
                              "id": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "quantity": {
                                "type": "integer"
                              },
                              "total": {
                                "type": "number"
                              }
                            },
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "orderKey": {
                          "type": "string"
                        },
                        "payment": {
                          "properties": {
                            "method": {
                              "type": "string"
                            },
                            "methodTitle": {
                              "type": "string"
                            },
                            "needsPayment": {
                              "type": "boolean"
                            }
                          },
                          "type": "object"
                        },
                        "shop": {
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "logo": {
                              "format": "uri",
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "url": {
                              "format": "uri",
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "status": {
                          "type": "string"
                        },
                        "total": {
                          "description": "Order total in major currency units.",
                          "type": "number"
                        }
                      },
                      "type": "object"
                    },
                    "success": {
                      "example": true,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Sanitized order and storefront details"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "details": {
                      "type": "object"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid order key or shop identifier"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Shop not approved for payment processing",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Store is not approved for payment processing"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Shop not found",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Store not found"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "details": {
                      "type": "object"
                    },
                    "error": {
                      "example": "Rate limit exceeded",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Rate limit exceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Fetch WooCommerce order details for hosted checkout",
        "tags": [
          "Orders",
          "WooCommerce",
          "Checkout"
        ]
      }
    },
    "/payments/{paymentId}/bank-details": {
      "get": {
        "operationId": "getPaymentBankDetails",
        "description": "Returns the beneficiary, IBAN, BIC, reference, and transaction summary used for manual bank transfer checkout. In a custom integration, call this only after initialization when the buyer needs bank-transfer instructions. The current lookup resolves the transaction by `orderId`.",
        "parameters": [
          {
            "description": "Payment identifier from the hosted checkout URL.",
            "in": "path",
            "name": "paymentId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Merchant order identifier for the transaction.",
            "in": "query",
            "name": "orderId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "bankDetails": {
                      "properties": {
                        "accountHolder": {
                          "type": "string"
                        },
                        "amount": {
                          "description": "Transfer amount in cents.",
                          "example": 2599,
                          "type": "integer"
                        },
                        "bankName": {
                          "example": "Deutsche Bank AG",
                          "type": "string"
                        },
                        "bic": {
                          "example": "DEUTDEDB",
                          "type": "string"
                        },
                        "currency": {
                          "example": "EUR",
                          "type": "string"
                        },
                        "iban": {
                          "example": "DE89370400440532013000",
                          "type": "string"
                        },
                        "reference": {
                          "example": "FP-252-ABC12345",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "transaction": {
                      "properties": {
                        "amount": {
                          "description": "Transaction amount in cents.",
                          "example": 2599,
                          "type": "integer"
                        },
                        "currency": {
                          "example": "EUR",
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "order_id": {
                          "type": "string"
                        },
                        "status": {
                          "example": "pending",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                },
                "examples": {
                  "transfer": {
                    "summary": "Manual transfer instructions",
                    "value": {
                      "transaction": {
                        "id": "tx_123",
                        "order_id": "order_1001",
                        "status": "pending",
                        "amount": 12345,
                        "currency": "EUR"
                      },
                      "bankDetails": {
                        "bankName": "Deutsche Bank AG",
                        "accountHolder": "Foxpay Demo Merchant GmbH",
                        "iban": "DE89370400440532013000",
                        "bic": "DEUTDEDB",
                        "reference": "FP-1001-ABC12345",
                        "amount": 12345,
                        "currency": "EUR"
                      }
                    }
                  }
                }
              }
            },
            "description": "Bank transfer details"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Transaction not found",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction not found"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Fetch bank transfer instructions for a payment",
        "tags": [
          "Custom Integration",
          "Payments",
          "Checkout"
        ]
      }
    },
    "/payments/{paymentId}/status": {
      "get": {
        "operationId": "getPaymentStatus",
        "description": "Returns the current checkout flow status for a Foxpay payment session or a synthetic test transaction. In a custom integration, use this endpoint for buyer-facing progress while your backend still treats durable reconciliation as authoritative.",
        "parameters": [
          {
            "description": "Foxpay payment transaction identifier.",
            "in": "path",
            "name": "paymentId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "orderId": {
                      "description": "Merchant order identifier associated with the payment.",
                      "type": "string"
                    },
                    "status": {
                      "description": "Checkout flow status mapped from the underlying transaction state.",
                      "enum": [
                        "pending",
                        "scanning",
                        "transferring",
                        "confirming",
                        "completed",
                        "failed"
                      ],
                      "type": "string"
                    },
                    "testMode": {
                      "description": "Present for synthetic test transactions only.",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "orderId",
                    "status"
                  ],
                  "type": "object"
                },
                "examples": {
                  "pending": {
                    "summary": "Pending checkout state",
                    "value": {
                      "orderId": "order_1001",
                      "status": "pending"
                    }
                  },
                  "completed": {
                    "summary": "Completed checkout state",
                    "value": {
                      "orderId": "order_1001",
                      "status": "completed"
                    }
                  }
                }
              }
            },
            "description": "Current checkout status"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENT_NOT_FOUND",
                      "type": "string"
                    },
                    "error": {
                      "example": "Payment not found",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment not found"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Poll hosted checkout payment status",
        "tags": [
          "Custom Integration",
          "Payments",
          "Checkout"
        ]
      }
    },
    "/payments/initialize": {
      "post": {
        "tags": [
          "Custom Integration",
          "Payments"
        ],
        "summary": "Initialize a custom payment session",
        "description": "Create a Foxpay payment session for a custom REST integration. By default this returns a Foxpay hosted checkout URL with all active payment methods. Advanced integrations can request `paymentMethod: open_bank_transfer` with `checkoutMode: direct_provider` to create a direct Calytics A2A/OBT session. A successful response means Foxpay accepted the session and returned a buyer handoff target; it does not mean the payment is complete.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "orderId",
                  "amountCents",
                  "currency"
                ],
                "oneOf": [
                  {
                    "required": [
                      "merchantId"
                    ]
                  },
                  {
                    "required": [
                      "shopId"
                    ]
                  }
                ],
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "Canonical public merchant identifier.",
                    "example": "merchant_fxp_ABC12345"
                  },
                  "shopId": {
                    "type": "string",
                    "description": "Temporary compatibility alias for `merchantId`.",
                    "example": "merchant_fxp_ABC12345"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "Merchant order identifier",
                    "example": "order_1001"
                  },
                  "amountCents": {
                    "type": "integer",
                    "description": "Payment amount in cents.",
                    "minimum": 1,
                    "example": 12345
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO 4217 currency code",
                    "pattern": "^[A-Z]{3}$",
                    "example": "EUR"
                  },
                  "customerEmail": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email address",
                    "example": "buyer@example.com"
                  },
                  "customerName": {
                    "type": "string",
                    "description": "Customer display name for checkout metadata.",
                    "example": "Jane Doe"
                  },
                  "returnUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional buyer return URL after checkout.",
                    "example": "https://merchant.example/orders/order_1001/return"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Free-form merchant metadata preserved for reconciliation.",
                    "additionalProperties": true
                  },
                  "paymentMethod": {
                    "type": "string",
                    "description": "Optional requested payment method. Omit to show all active methods in Foxpay checkout. Use `open_bank_transfer` for direct OBT when checkoutMode is `direct_provider`.",
                    "enum": [
                      "qr_pay",
                      "open_bank_transfer",
                      "bank_transfer",
                      "manual_transfer",
                      "manual_pay",
                      "manual"
                    ],
                    "example": "qr_pay"
                  },
                  "checkoutMode": {
                    "type": "string",
                    "description": "Checkout handoff mode. Omit for Foxpay hosted checkout. Use `direct_provider` only with supported methods such as open_bank_transfer.",
                    "enum": [
                      "foxpay_checkout",
                      "direct_provider"
                    ],
                    "default": "foxpay_checkout",
                    "example": "foxpay_checkout"
                  },
                  "provider": {
                    "type": "string",
                    "description": "Provider for direct provider sessions. Currently only `calytics` is supported for open_bank_transfer.",
                    "enum": [
                      "calytics"
                    ],
                    "example": "calytics"
                  },
                  "customerCountry": {
                    "type": "string",
                    "description": "Buyer country as ISO 3166-1 alpha-2. Required for direct open_bank_transfer sessions.",
                    "minLength": 2,
                    "maxLength": 2,
                    "example": "DE"
                  },
                  "senderName": {
                    "type": "string",
                    "description": "Account holder name for direct open_bank_transfer sessions.",
                    "example": "Jane Doe"
                  },
                  "senderIban": {
                    "type": "string",
                    "description": "Buyer IBAN for direct open_bank_transfer sessions.",
                    "example": "DE89370400440532013000"
                  },
                  "remittanceInfo": {
                    "type": "string",
                    "description": "Optional SEPA remittance/payment reference. If omitted, Foxpay generates a reference. This is separate from metadata.",
                    "maxLength": 140,
                    "example": "ORDER-1001"
                  }
                }
              },
              "examples": {
                "hostedCheckout": {
                  "summary": "Hosted Foxpay checkout",
                  "value": {
                    "merchantId": "merchant_fxp_ABC12345",
                    "orderId": "order_1001",
                    "amountCents": 12345,
                    "currency": "EUR",
                    "customerEmail": "buyer@example.com",
                    "returnUrl": "https://merchant.example/orders/order_1001/return",
                    "remittanceInfo": "ORDER-1001"
                  }
                },
                "directObt": {
                  "summary": "Direct Calytics Open Bank Transfer",
                  "value": {
                    "merchantId": "merchant_fxp_ABC12345",
                    "orderId": "order_1001",
                    "amountCents": 12345,
                    "currency": "EUR",
                    "paymentMethod": "open_bank_transfer",
                    "checkoutMode": "direct_provider",
                    "provider": "calytics",
                    "customerCountry": "DE",
                    "senderName": "Jane Doe",
                    "senderIban": "DE89370400440532013000",
                    "remittanceInfo": "ORDER-1001",
                    "returnUrl": "https://merchant.example/orders/order_1001/return"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment initialized successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "paymentUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Hosted checkout URL the buyer should be redirected to for Foxpay checkout sessions.",
                      "example": "https://app.foxpay.it/payment/order_1001?version=v2&transactionId=tx_123&source=custom_api"
                    },
                    "redirectUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Direct provider redirect URL for direct_provider sessions."
                    },
                    "sessionUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Compatibility alias for direct provider redirect URL."
                    },
                    "paymentId": {
                      "type": "string",
                      "description": "Foxpay transaction identifier.",
                      "example": "tx_123"
                    },
                    "orderId": {
                      "type": "string",
                      "description": "Merchant order identifier.",
                      "example": "order_1001"
                    },
                    "merchantId": {
                      "type": "string",
                      "description": "Resolved Foxpay merchant identifier.",
                      "example": "merchant_fxp_ABC12345"
                    },
                    "amount": {
                      "type": "integer",
                      "description": "Payment amount in cents.",
                      "example": 12345
                    },
                    "amountCents": {
                      "type": "integer",
                      "description": "Payment amount in cents.",
                      "example": 12345
                    },
                    "currency": {
                      "type": "string",
                      "example": "EUR"
                    },
                    "customerEmail": {
                      "type": "string",
                      "format": "email",
                      "example": "buyer@example.com"
                    },
                    "status": {
                      "type": "string",
                      "example": "pending"
                    },
                    "paymentMethod": {
                      "type": "string",
                      "example": "open_bank_transfer"
                    },
                    "checkoutMode": {
                      "type": "string",
                      "enum": [
                        "foxpay_checkout",
                        "direct_provider"
                      ],
                      "example": "direct_provider"
                    },
                    "provider": {
                      "type": "string",
                      "example": "calytics"
                    },
                    "remittanceInfo": {
                      "type": "string",
                      "example": "ORDER-1001"
                    },
                    "remittanceInfoSource": {
                      "type": "string",
                      "enum": [
                        "merchant",
                        "generated"
                      ],
                      "example": "merchant"
                    },
                    "testMode": {
                      "type": "boolean",
                      "description": "Whether the authenticated API key resolved to test mode."
                    },
                    "returnUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "message": {
                      "type": "string",
                      "description": "Present when an existing pending transaction is reused."
                    },
                    "paymentData": {
                      "type": "object",
                      "properties": {
                        "orderId": {
                          "type": "string",
                          "example": "order_1001"
                        },
                        "merchantId": {
                          "type": "string",
                          "example": "merchant_fxp_ABC12345"
                        },
                        "amountCents": {
                          "type": "integer",
                          "example": 12345
                        },
                        "currency": {
                          "type": "string",
                          "example": "EUR"
                        },
                        "customerEmail": {
                          "type": "string",
                          "format": "email",
                          "example": "buyer@example.com"
                        },
                        "customerName": {
                          "type": "string",
                          "example": "Jane Doe"
                        },
                        "paymentMethod": {
                          "type": "string",
                          "example": "qr_pay"
                        },
                        "paymentMode": {
                          "type": "string",
                          "enum": [
                            "test",
                            "production"
                          ]
                        },
                        "metadata": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "hostedCheckout": {
                    "summary": "Hosted checkout handoff",
                    "value": {
                      "success": true,
                      "paymentUrl": "https://app.foxpay.it/payment/order_1001?version=v2&transactionId=tx_123&source=custom_api",
                      "paymentId": "tx_123",
                      "orderId": "order_1001",
                      "merchantId": "merchant_fxp_ABC12345",
                      "amount": 12345,
                      "amountCents": 12345,
                      "currency": "EUR",
                      "customerEmail": "buyer@example.com",
                      "status": "pending",
                      "paymentMethod": "qr_pay",
                      "checkoutMode": "foxpay_checkout",
                      "remittanceInfo": "ORDER-1001",
                      "remittanceInfoSource": "merchant",
                      "testMode": false,
                      "returnUrl": "https://merchant.example/orders/order_1001/return"
                    }
                  },
                  "directObt": {
                    "summary": "Direct Calytics OBT handoff",
                    "value": {
                      "success": true,
                      "paymentId": "obt_123",
                      "orderId": "order_1001",
                      "merchantId": "merchant_fxp_ABC12345",
                      "amount": 12345,
                      "amountCents": 12345,
                      "currency": "EUR",
                      "status": "pending",
                      "paymentMethod": "open_bank_transfer",
                      "checkoutMode": "direct_provider",
                      "provider": "calytics",
                      "redirectUrl": "https://provider.example/session/abc",
                      "sessionUrl": "https://provider.example/session/abc",
                      "remittanceInfo": "ORDER-1001",
                      "remittanceInfoSource": "merchant",
                      "testMode": false,
                      "returnUrl": "https://merchant.example/orders/order_1001/return"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Merchant or payment mode is not eligible to initialize the payment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "KYC validation required",
                        "KYC validation failed",
                        "Shop verification required",
                        "Payment method unavailable"
                      ]
                    },
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "KYC_USER_ASSOCIATION_MISSING",
                        "KYC_SUBMISSION_MISSING",
                        "KYC_USER_MISMATCH",
                        "SHOP_NOT_VERIFIED"
                      ]
                    },
                    "currentStatus": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Merchant not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid merchant ID"
                    },
                    "details": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "initializeCustomPaymentSession"
      }
    },
    "/version": {
      "get": {
        "description": "Returns comprehensive version information for the Foxpay platform including build details, compliance status, and deployment information",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "apiVersion": {
                      "example": "v1.0",
                      "type": "string"
                    },
                    "build": {
                      "example": "1234",
                      "type": "string"
                    },
                    "buildDate": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "buildTimestamp": {
                      "type": "number"
                    },
                    "config": {
                      "properties": {
                        "codeName": {
                          "example": "Thunderbird",
                          "type": "string"
                        },
                        "criticalFeatures": {
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "deploymentType": {
                          "enum": [
                            "beta",
                            "production",
                            "staging"
                          ],
                          "type": "string"
                        },
                        "displayName": {
                          "example": "Beta Release",
                          "type": "string"
                        },
                        "securityLevel": {
                          "enum": [
                            "standard",
                            "enhanced",
                            "enterprise"
                          ],
                          "type": "string"
                        },
                        "shortName": {
                          "example": "BETA",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "databaseVersion": {
                      "example": "1.0.0",
                      "type": "string"
                    },
                    "deployment": {
                      "properties": {
                        "environment": {
                          "enum": [
                            "development",
                            "staging",
                            "production"
                          ],
                          "type": "string"
                        },
                        "isOperational": {
                          "type": "boolean"
                        },
                        "lastDeployment": {
                          "type": "string"
                        },
                        "supportedUntil": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "environment": {
                      "enum": [
                        "development",
                        "staging",
                        "production"
                      ],
                      "type": "string"
                    },
                    "gitBranch": {
                      "example": "main",
                      "type": "string"
                    },
                    "gitCommit": {
                      "example": "abc123def",
                      "type": "string"
                    },
                    "major": {
                      "example": 1,
                      "type": "number"
                    },
                    "minor": {
                      "example": 0,
                      "type": "number"
                    },
                    "patch": {
                      "example": 0,
                      "type": "number"
                    },
                    "pciCompliance": {
                      "example": "PCI DSS 4.0.1",
                      "type": "string"
                    },
                    "prerelease": {
                      "example": "beta.1",
                      "type": "string"
                    },
                    "releaseStage": {
                      "enum": [
                        "alpha",
                        "beta",
                        "rc",
                        "stable"
                      ],
                      "type": "string"
                    },
                    "version": {
                      "example": "1.0.0-beta.1",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Version information retrieved successfully"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Failed to retrieve version information",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Server error retrieving version information"
          }
        },
        "summary": "Get application version information",
        "tags": [
          "System"
        ]
      }
    },
    "/version/check": {
      "post": {
        "description": "Compare client version with server version and determine compatibility and update requirements",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "clientVersion": {
                    "description": "Client application version",
                    "example": "1.0.0-beta.1",
                    "type": "string"
                  },
                  "environment": {
                    "description": "Client environment",
                    "enum": [
                      "development",
                      "staging",
                      "production"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "clientVersion"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "clientVersion": {
                      "description": "Submitted client version",
                      "example": "1.0.0-beta.1",
                      "type": "string"
                    },
                    "compatible": {
                      "description": "Whether client version is compatible with server",
                      "type": "boolean"
                    },
                    "deprecationWarning": {
                      "description": "Whether client version is deprecated",
                      "type": "boolean"
                    },
                    "forceUpdate": {
                      "description": "Whether update is mandatory",
                      "type": "boolean"
                    },
                    "message": {
                      "description": "Human-readable message about version status",
                      "type": "string"
                    },
                    "requiresUpdate": {
                      "description": "Whether client should update",
                      "type": "boolean"
                    },
                    "securityUpdate": {
                      "description": "Whether this is a security-related update",
                      "type": "boolean"
                    },
                    "serverVersion": {
                      "description": "Current server version",
                      "example": "1.0.0-beta.2",
                      "type": "string"
                    },
                    "severity": {
                      "description": "Severity of the version difference",
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "critical"
                      ],
                      "type": "string"
                    },
                    "supportedUntil": {
                      "description": "When client version support ends",
                      "format": "date",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "updateAvailable": {
                      "description": "Whether a newer version is available",
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Version compatibility check completed"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "clientVersion is required",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid request parameters"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Failed to perform version check",
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Server error during version check"
          }
        },
        "summary": "Check version compatibility",
        "tags": [
          "System"
        ]
      }
    },
    "/woocommerce/connect/register": {
      "post": {
        "description": "Used by the WooCommerce plugin auto-connect flow to register credentials for a store. The request must include Foxpay HMAC headers and a recent timestamp.",
        "parameters": [
          {
            "description": "Hex-encoded HMAC SHA-256 signature of `{timestamp}.{rawBody}`.",
            "in": "header",
            "name": "X-Foxpay-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Unix timestamp in seconds.",
            "in": "header",
            "name": "X-Foxpay-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Store identifier whose credentials should be registered.",
            "in": "header",
            "name": "X-Store-ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "consumer_key": {
                    "example": "ck_1234567890abcdef",
                    "type": "string"
                  },
                  "consumer_secret": {
                    "example": "cs_1234567890abcdef",
                    "type": "string"
                  },
                  "plugin_version": {
                    "example": "1.4.0",
                    "type": "string"
                  },
                  "site_url": {
                    "format": "uri",
                    "type": "string"
                  }
                },
                "required": [
                  "consumer_key",
                  "consumer_secret",
                  "site_url",
                  "plugin_version"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "registered": {
                      "example": true,
                      "type": "boolean"
                    },
                    "success": {
                      "example": true,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Credentials registered successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Missing headers, malformed JSON, or invalid credential payload"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Signature invalid or timestamp expired"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Unknown store",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Store not found"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "example": "Rate limit exceeded. Maximum 5 registrations per hour.",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Registration rate limit exceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Register or rotate WooCommerce API credentials",
        "tags": [
          "WooCommerce"
        ]
      }
    },
    "/woocommerce/initiate-payment": {
      "get": {
        "description": "Returns lightweight service metadata for the WooCommerce payment initialization route. Use it for plugin diagnostics and availability checks; custom API integrations should use `POST /payments/initialize` instead.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "timestamp": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Service metadata"
          }
        },
        "summary": "Check WooCommerce payment API availability",
        "tags": [
          "WooCommerce"
        ]
      },
      "post": {
        "description": "Creates a Foxpay transaction for a WooCommerce order and returns redirect URLs for the hosted checkout flow. Request amounts are sent in major currency units and persisted internally in cents.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount": {
                    "description": "Order amount in major currency units.",
                    "example": 25.99,
                    "type": "number"
                  },
                  "currency": {
                    "example": "EUR",
                    "type": "string"
                  },
                  "customerEmail": {
                    "format": "email",
                    "type": "string"
                  },
                  "customerName": {
                    "type": "string"
                  },
                  "orderId": {
                    "type": "string"
                  },
                  "orderItems": {
                    "items": {
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "number"
                        },
                        "quantity": {
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "paymentMethod": {
                    "example": "qr",
                    "type": "string"
                  },
                  "returnUrl": {
                    "format": "uri",
                    "type": "string"
                  },
                  "shopId": {
                    "description": "Store UUID, merchant ID, or resolvable domain.",
                    "type": "string"
                  }
                },
                "required": [
                  "orderId",
                  "amount",
                  "currency",
                  "customerEmail",
                  "returnUrl",
                  "shopId"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "redirectUrl": {
                      "format": "uri",
                      "type": "string"
                    },
                    "returnUrl": {
                      "format": "uri",
                      "type": "string"
                    },
                    "status": {
                      "example": "pending",
                      "type": "string"
                    },
                    "success": {
                      "example": true,
                      "type": "boolean"
                    },
                    "transactionId": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment session created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "required": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Required fields missing"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Store could not be resolved or found"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Initialize a WooCommerce payment session",
        "tags": [
          "WooCommerce",
          "Payments"
        ]
      }
    },
    "/woocommerce/payment-status": {
      "get": {
        "description": "Looks up a Foxpay transaction by transaction ID or merchant order ID and returns its current state.",
        "parameters": [
          {
            "in": "query",
            "name": "transactionId",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "orderId",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "success": {
                      "example": true,
                      "type": "boolean"
                    },
                    "transaction": {
                      "properties": {
                        "amount": {
                          "description": "Transaction amount in cents.",
                          "type": "integer"
                        },
                        "createdAt": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "customerEmail": {
                          "format": "email",
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "orderId": {
                          "type": "string"
                        },
                        "paymentMethod": {
                          "type": "string"
                        },
                        "platform": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "format": "date-time",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction status payload"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Missing transactionId or orderId"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction not found"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Get WooCommerce transaction status",
        "tags": [
          "WooCommerce",
          "Payments"
        ]
      },
      "post": {
        "description": "Returns the same transaction lookup as the GET endpoint and includes hosted checkout QR metadata when available.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "orderId": {
                    "type": "string"
                  },
                  "transactionId": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "paymentUrl": {
                      "nullable": true,
                      "type": "string"
                    },
                    "qrCode": {
                      "nullable": true,
                      "type": "string"
                    },
                    "success": {
                      "example": true,
                      "type": "boolean"
                    },
                    "transaction": {
                      "properties": {
                        "amount": {
                          "description": "Transaction amount in cents.",
                          "type": "integer"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "orderId": {
                          "type": "string"
                        },
                        "paymentMethod": {
                          "type": "string"
                        },
                        "shopId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction status with checkout artifacts"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Missing transactionId or orderId"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "example": false,
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction not found"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Fetch transaction status plus checkout artifacts",
        "tags": [
          "WooCommerce",
          "Payments"
        ]
      }
    },
    "/woocommerce/webhook": {
      "post": {
        "description": "Accepts Foxpay payment status updates from WooCommerce integrations. Requests may authenticate with the signed `x-foxpay-signature` header or the legacy `x-woocommerce-webhook-secret` header.",
        "parameters": [
          {
            "description": "Signed webhook header in `t=timestamp,v1=signature` format.",
            "in": "header",
            "name": "x-foxpay-signature",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Legacy shared-secret header for backward compatibility.",
            "in": "header",
            "name": "x-woocommerce-webhook-secret",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount": {
                    "description": "Amount reported by the webhook sender.",
                    "type": "number"
                  },
                  "currency": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object"
                  },
                  "orderId": {
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "pending",
                      "completed",
                      "failed",
                      "cancelled",
                      "refunded"
                    ],
                    "type": "string"
                  },
                  "transactionId": {
                    "type": "string"
                  }
                },
                "required": [
                  "transactionId",
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "success": {
                      "example": true,
                      "type": "boolean"
                    },
                    "transactionId": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Webhook processed or already handled"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Unsupported content type or invalid payload"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Missing or invalid webhook authentication"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Transaction not found"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Webhook rate limit exceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "summary": "Receive WooCommerce payment status webhooks",
        "tags": [
          "WooCommerce",
          "Webhooks"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production API",
      "url": "https://app.foxpay.it/api"
    },
    {
      "description": "Staging API",
      "url": "https://staging.app.foxpay.it/api"
    },
    {
      "description": "Local development API",
      "url": "http://localhost:3000/api"
    }
  ],
  "tags": [
    {
      "name": "Custom Integration",
      "description": "Direct REST integration for merchants that are not using a Foxpay commerce plugin. The complete public flow is: initialize a payment session, redirect the buyer to hosted checkout, poll status for buyer-facing progress, fetch bank-transfer details when needed, and reconcile final order state from Foxpay-signed webhook delivery to your own webhook URL. Use `Authorization: Bearer <apiKey>` and send all custom integration amounts as integer cents."
    },
    {
      "name": "Payments",
      "description": "Payment-session operations shared by custom and commerce integrations. These endpoints expose checkout initialization, status inspection, and payment-method-specific details. Store Foxpay identifiers returned by these APIs for support and reconciliation."
    },
    {
      "name": "Checkout",
      "description": "Buyer-facing hosted checkout support endpoints. Use these to render order context, reflect checkout progress, and show transfer instructions; do not treat buyer-facing polling as the authoritative settlement source."
    },
    {
      "name": "WooCommerce",
      "description": "Plugin-oriented routes for WooCommerce stores. Use these endpoints only when integrating through the WooCommerce plugin or plugin credential-registration flow; custom integrations should not reuse the WooCommerce webhook target."
    },
    {
      "name": "Orders",
      "description": "Read-only order lookup endpoints used to prepare hosted checkout and validate order context before payment handoff."
    },
    {
      "name": "Webhooks",
      "description": "Server-to-server callback handling for payment status updates. For custom API integrations, the webhook is merchant-hosted: Foxpay sends signed `transaction.status_changed` deliveries to the configured custom webhook URL. The WooCommerce webhook is plugin-specific and separate."
    },
    {
      "name": "System",
      "description": "Health, version, and compatibility endpoints for operational checks, monitoring, and release validation."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Integrate",
      "tags": [
        "Custom Integration",
        "Payments",
        "Checkout"
      ]
    },
    {
      "name": "Commerce Plugins",
      "tags": [
        "WooCommerce",
        "Orders",
        "Webhooks"
      ]
    },
    {
      "name": "Operations",
      "tags": [
        "System"
      ]
    }
  ]
}