{
  "openapi": "3.1.0",
  "info": {
    "title": "Adpay Hosted Payments API",
    "version": "1.0.0",
    "description": "Operation-envelope API for hosted payments on connected Wix sites.\n\n## Adpay Standard Auth (Bearer + HMAC)\n1. **Identity** — send your API key as `Authorization: Bearer <api_key>`.\n2. **Authorization proof** — sign the canonical string `timestamp.METHOD.path.sha256(body)` with your HMAC secret (HMAC-SHA256, hex) and send it as `X-Adpay-Signature`, with the Unix timestamp in `X-Adpay-Timestamp` (±300s window).\n3. **Instance binding** — every request targets exactly one Wix site, identified by `tenant.siteKey` (or `X-Adpay-Site-Key`). The key must be allowed for your API key.\n\nEvery response carries `X-Adpay-Version` and `X-Adpay-Key-Id` headers so you can see which key and protocol version served the request.\n\nUse `POST /api/functions/hostedApiAuthVerify` to formally verify credentials and inspect key scopes and allowed sites."
  },
  "servers": [
    {
      "url": "https://base44-dispatcher-production.base44.workers.dev"
    }
  ],
  "security": [
    {
      "AdpayBearer": [],
      "AdpaySignature": []
    }
  ],
  "paths": {
    "/api/functions/hostedPaymentsApi": {
      "post": {
        "operationId": "invokeHostedPaymentOperation",
        "summary": "Invoke a hosted payment operation",
        "description": "Single signed endpoint. The `operation` field in the envelope selects one of the supported operations. Write operations require an `Idempotency-Key` header.",
        "parameters": [
          {
            "name": "X-Adpay-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unix timestamp (seconds) used in the canonical signing string"
          },
          {
            "name": "X-Adpay-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "HMAC-SHA256 hex signature of the canonical string"
          },
          {
            "name": "X-Adpay-Site-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Site key (alternative to tenant.siteKey in the body)"
          },
          {
            "name": "X-Adpay-Environment",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sandbox",
                "production"
              ]
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for write operations"
          },
          {
            "name": "X-Correlation-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation succeeded",
            "headers": {
              "X-Adpay-Version": {
                "schema": {
                  "type": "string"
                },
                "description": "API protocol version that served the request"
              },
              "X-Adpay-Key-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Key prefix of the authenticated API key"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed (bearer, signature, or timestamp)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Key suspended/revoked or missing scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/functions/hostedApiAuthVerify": {
      "post": {
        "operationId": "verifyCredentials",
        "summary": "Verify API credentials (Adpay Standard Auth)",
        "description": "Send a signed empty JSON body (`{}`) to verify your Bearer key + HMAC secret and receive the formal key identity document (scopes, allowed sites, expiry).",
        "parameters": [
          {
            "name": "X-Adpay-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Adpay-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credentials verified; key identity returned",
            "headers": {
              "X-Adpay-Version": {
                "schema": {
                  "type": "string"
                },
                "description": "API protocol version that served the request"
              },
              "X-Adpay-Key-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Key prefix of the authenticated API key"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthVerifyResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AdpayBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Adpay-Key",
        "description": "Your Adpay API key (e.g. adpay_live_xxxxxxxx_...). Identifies the API consumer."
      },
      "AdpaySignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Adpay-Signature",
        "description": "HMAC-SHA256 hex signature of `timestamp.METHOD.path.sha256(body)` using your HMAC secret. Proves request authorization."
      }
    },
    "schemas": {
      "RequestEnvelope": {
        "type": "object",
        "required": [
          "operation",
          "tenant",
          "payload"
        ],
        "properties": {
          "version": {
            "type": "string",
            "default": "v1"
          },
          "operation": {
            "type": "string",
            "enum": [
              "capabilities.get",
              "checkout.create",
              "checkout.get",
              "paymentLink.create",
              "paymentLink.get",
              "booking.create",
              "booking.checkout.create",
              "booking.paymentLink.create",
              "order.create",
              "order.payment.add",
              "order.get",
              "refund.create",
              "transaction.get",
              "transactions.list",
              "report.summary"
            ],
            "description": "Operation to invoke"
          },
          "tenant": {
            "type": "object",
            "required": [
              "siteKey"
            ],
            "properties": {
              "siteKey": {
                "type": "string",
                "description": "Site key binding this request to a single Wix instance"
              }
            }
          },
          "payload": {
            "type": "object",
            "description": "Operation-specific payload"
          },
          "meta": {
            "type": "object",
            "properties": {
              "adpayEnvironment": {
                "type": "string",
                "enum": [
                  "sandbox",
                  "production"
                ]
              }
            }
          },
          "idempotencyKey": {
            "type": "string",
            "description": "Alternative to the Idempotency-Key header for write operations"
          }
        }
      },
      "AuthVerifyResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "verified": {
            "type": "boolean"
          },
          "protocol": {
            "type": "object"
          },
          "key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "key_prefix": {
                "type": "string"
              },
              "display_name": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "environment": {
                "type": "string"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "allowed_site_keys": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_used_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "x-adpay-operations": [
    {
      "operation": "capabilities.get",
      "group": "Capabilities",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "Get provider capabilities for a site"
    },
    {
      "operation": "checkout.create",
      "group": "Checkout",
      "write": true,
      "requiredScopes": [
        "checkout.write"
      ],
      "summary": "Create a hosted checkout session"
    },
    {
      "operation": "checkout.get",
      "group": "Checkout",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "Get a checkout session"
    },
    {
      "operation": "paymentLink.create",
      "group": "Payment Links",
      "write": true,
      "requiredScopes": [
        "paymentLinks.write"
      ],
      "summary": "Create a payment link"
    },
    {
      "operation": "paymentLink.get",
      "group": "Payment Links",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "Get a payment link"
    },
    {
      "operation": "booking.create",
      "group": "Bookings",
      "write": true,
      "requiredScopes": [
        "bookings.write"
      ],
      "summary": "Create a booking"
    },
    {
      "operation": "booking.checkout.create",
      "group": "Bookings",
      "write": true,
      "requiredScopes": [
        "bookings.write"
      ],
      "summary": "Create a booking checkout"
    },
    {
      "operation": "booking.paymentLink.create",
      "group": "Bookings",
      "write": true,
      "requiredScopes": [
        "bookings.write",
        "paymentLinks.write"
      ],
      "summary": "Create a booking payment link"
    },
    {
      "operation": "order.create",
      "group": "Orders",
      "write": true,
      "requiredScopes": [
        "orders.write"
      ],
      "summary": "Create an order"
    },
    {
      "operation": "order.payment.add",
      "group": "Orders",
      "write": true,
      "requiredScopes": [
        "orders.write"
      ],
      "summary": "Add a payment to an order"
    },
    {
      "operation": "order.get",
      "group": "Orders",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "Get an order"
    },
    {
      "operation": "refund.create",
      "group": "Refunds",
      "write": true,
      "requiredScopes": [
        "orders.write"
      ],
      "summary": "Create a refund"
    },
    {
      "operation": "transaction.get",
      "group": "Transactions",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "Get a transaction"
    },
    {
      "operation": "transactions.list",
      "group": "Transactions",
      "write": false,
      "requiredScopes": [
        "transactions.read"
      ],
      "summary": "List transactions"
    },
    {
      "operation": "report.summary",
      "group": "Reporting",
      "write": false,
      "requiredScopes": [
        "reporting.read"
      ],
      "summary": "Get a reporting summary"
    }
  ]
}