{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base",
  "info": {
    "title": "Neo provider API",
    "version": "2026-07-20",
    "summary": "Monitoring and signed provider callback contract for Neo.",
    "description": "Neo is a WhatsApp-first commerce service. This contract intentionally documents only the machine-facing HTTP boundary: service health, readiness, operational summaries, provider verification, and signed callbacks. Buyer, seller, creator, and operator journeys are WhatsApp or protected server-rendered web flows rather than a public CRUD API. Callback availability does not imply that the related provider capability is enabled or certified.",
    "contact": {
      "name": "Neo engineering documentation",
      "url": "https://staging-docs.withneo.app"
    },
    "license": {
      "name": "Proprietary"
    },
    "x-logo": {
      "url": "https://staging-docs.withneo.app/assets/brand/neo/neo-logo.png",
      "altText": "Neo"
    }
  },
  "servers": [
    {
      "url": "https://staging-api.withneo.app",
      "description": "Production API origin"
    }
  ],
  "externalDocs": {
    "description": "Neo engineering documentation",
    "url": "https://staging-docs.withneo.app"
  },
  "tags": [
    {
      "name": "Service",
      "description": "API discovery, liveness, and database-backed readiness."
    },
    {
      "name": "Operations",
      "description": "Public-safe provider and durable-queue summaries for operators."
    },
    {
      "name": "WhatsApp",
      "description": "Meta verification and signed WhatsApp callback receipt."
    },
    {
      "name": "Payments",
      "description": "Signed Paystack and Flutterwave payment or adjustment callbacks."
    },
    {
      "name": "Logistics",
      "description": "Signed Kwik and Sendbox shipment-tracking callbacks."
    },
    {
      "name": "Payouts",
      "description": "Signed payout-provider transfer callbacks. Live transfer enablement remains separately gated."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiIndex",
        "tags": [
          "Service"
        ],
        "summary": "Discover the Neo API",
        "description": "Returns canonical links for health, readiness, and engineering documentation when requested on the configured API host.",
        "responses": {
          "200": {
            "description": "API discovery document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Service"
        ],
        "summary": "Check service liveness and beta state",
        "description": "Reports process liveness plus public-safe environment and closed-beta state. A successful response does not prove database readiness or provider certification.",
        "responses": {
          "200": {
            "description": "The process is live.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/ready": {
      "get": {
        "operationId": "getReadiness",
        "tags": [
          "Service"
        ],
        "summary": "Check database-backed readiness",
        "description": "Executes a lightweight database query. Deployment health checks should use this operation.",
        "responses": {
          "200": {
            "description": "The process can reach its database.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/health/providers": {
      "get": {
        "operationId": "getProviderHealth",
        "tags": [
          "Operations"
        ],
        "summary": "Inspect provider configuration and public certification health",
        "description": "Returns selected provider names, public-safe exact-target certification state, and in-process observations. It excludes credentials and private certification evidence.",
        "responses": {
          "200": {
            "description": "Provider configuration and observed health.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderHealthResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/health/queues": {
      "get": {
        "operationId": "getQueueHealth",
        "tags": [
          "Operations"
        ],
        "summary": "Inspect durable inbox and outbox counts",
        "description": "Returns counts by queue state and the oldest unfinished timestamps. It does not return payloads or customer data.",
        "responses": {
          "200": {
            "description": "Public-safe durable queue snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueHealthResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/whatsapp": {
      "get": {
        "operationId": "verifyWhatsAppWebhook",
        "tags": [
          "WhatsApp"
        ],
        "summary": "Complete Meta webhook verification",
        "description": "Meta calls this operation during callback registration. Neo returns the supplied challenge only when mode, challenge, and the configured verification token match.",
        "security": [
          {
            "MetaVerifyToken": []
          }
        ],
        "parameters": [
          {
            "name": "hub.mode",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "const": "subscribe"
            },
            "description": "Meta verification mode."
          },
          {
            "name": "hub.challenge",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Opaque challenge that Neo echoes after verification."
          }
        ],
        "responses": {
          "200": {
            "description": "The verified Meta challenge.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "operationId": "receiveWhatsAppWebhook",
        "tags": [
          "WhatsApp"
        ],
        "summary": "Receive a signed WhatsApp event",
        "description": "Verifies the signature against the raw body, normalizes a message or delivery-status event, durably records it before work, and acknowledges duplicates safely. Status-only callbacks are acknowledged as ignored after verification.",
        "security": [
          {
            "MetaWebhookSignature": []
          },
          {
            "NeoWhatsAppSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Provider-owned Meta webhook envelope. The signature is calculated over the exact raw JSON bytes.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetaWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/whatsapp/flows": {
      "post": {
        "operationId": "exchangeWhatsAppFlowData",
        "tags": [
          "WhatsApp"
        ],
        "summary": "Exchange encrypted buyer-checkout Flow data",
        "description": "Accepts Meta's signed encrypted data-exchange envelope for the default-off buyer_checkout@1 Flow. Neo decrypts and validates the request, performs authoritative read or quote work, and encrypts the response. Flow completion can stage a cart and pending confirmation only; it cannot create an order, payment, inventory reservation, or shipment.",
        "security": [
          {
            "MetaWebhookSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Meta encrypted WhatsApp Flow data-exchange envelope. The signature covers the exact raw JSON bytes.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetaFlowDataExchangeEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Encrypted Flow data-exchange response.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Base64-encoded AES-GCM ciphertext."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "421": {
            "$ref": "#/components/responses/BadRequest"
          },
          "427": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "432": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/payout": {
      "post": {
        "operationId": "receivePayoutWebhook",
        "tags": [
          "Payouts"
        ],
        "summary": "Receive a signed payout-transfer event",
        "description": "The selected payout adapter must verify and parse the callback. The disabled production adapter accepts no callbacks. Receipt does not enable payout delivery.",
        "security": [
          {
            "PayoutWebhookSignature": []
          },
          {
            "PaystackWebhookSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Normalized payout-provider transfer event.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayoutWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/paystack": {
      "post": {
        "operationId": "receivePaystackWebhook",
        "tags": [
          "Payments",
          "Payouts"
        ],
        "summary": "Receive a signed Paystack event",
        "description": "Available when Paystack is selected. Supports payment confirmation/failure, Pay with Transfer rejection, refund/dispute events, and signed payout-transfer events from Paystack's single configured webhook URL.",
        "security": [
          {
            "PaystackWebhookSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Paystack payment, adjustment, or payout-transfer envelope. The signature is calculated over the exact raw JSON bytes.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/flutterwave": {
      "post": {
        "operationId": "receiveFlutterwaveWebhook",
        "tags": [
          "Payments"
        ],
        "summary": "Receive a signed Flutterwave event",
        "description": "Available only when Flutterwave is the selected payment adapter. The current signature header is preferred; the documented legacy verification header remains accepted by the adapter.",
        "security": [
          {
            "FlutterwaveWebhookSignature": []
          },
          {
            "FlutterwaveLegacySignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Flutterwave payment, refund, or chargeback event envelope.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/kwik": {
      "post": {
        "operationId": "receiveKwikWebhook",
        "tags": [
          "Logistics"
        ],
        "summary": "Receive a signed Kwik tracking event",
        "description": "Available only when Kwik is the selected logistics adapter. Verified events enter the durable inbox before shipment and order state are synchronized.",
        "security": [
          {
            "KwikWebhookSignature": []
          },
          {
            "KwikLegacyWebhookSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Kwik-owned shipment tracking event.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LogisticsWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/webhooks/sendbox": {
      "post": {
        "operationId": "receiveSendboxWebhook",
        "tags": [
          "Logistics"
        ],
        "summary": "Receive an authenticated Sendbox tracking event",
        "description": "Available only when Sendbox is the selected logistics adapter. Prefer the signature header; the provider callback-token query form is retained for provider compatibility and must be treated as a secret.",
        "security": [
          {
            "SendboxWebhookSignature": []
          },
          {
            "SendboxCallbackToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Sendbox-owned shipment tracking event.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LogisticsWebhookEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signed event was acknowledged. Duplicate delivery is safe and reported explicitly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookAcknowledgement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "MetaVerifyToken": {
        "type": "apiKey",
        "in": "query",
        "name": "hub.verify_token",
        "description": "Server-configured Meta verification token. Never place a real value in shared examples or logs."
      },
      "MetaWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-hub-signature-256",
        "description": "Meta HMAC signature over the exact raw body."
      },
      "NeoWhatsAppSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-neo-whatsapp-signature",
        "description": "Compatibility signature header for the selected WhatsApp adapter."
      },
      "PayoutWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-neo-payout-signature",
        "description": "Signature verified by the selected payout adapter."
      },
      "PaystackWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-paystack-signature",
        "description": "Paystack HMAC signature over the exact raw body."
      },
      "FlutterwaveWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "flutterwave-signature",
        "description": "Current Flutterwave webhook signature."
      },
      "FlutterwaveLegacySignature": {
        "type": "apiKey",
        "in": "header",
        "name": "verif-hash",
        "description": "Legacy Flutterwave verification header accepted for compatibility."
      },
      "KwikWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-kwik-signature",
        "description": "Kwik webhook signature."
      },
      "KwikLegacyWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-kwik-webhook-signature",
        "description": "Alternate Kwik webhook signature header."
      },
      "SendboxWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-sendbox-signature",
        "description": "Preferred Sendbox callback signature header."
      },
      "SendboxCallbackToken": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "Provider callback token retained for Sendbox compatibility. Treat it as a secret."
      }
    },
    "schemas": {
      "OkResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ApiIndex": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "status",
          "health",
          "ready",
          "docs"
        ],
        "properties": {
          "name": {
            "type": "string",
            "const": "Neo API"
          },
          "status": {
            "type": "string",
            "const": "ok"
          },
          "health": {
            "type": "string",
            "format": "uri",
            "example": "https://staging-api.withneo.app/health"
          },
          "ready": {
            "type": "string",
            "format": "uri",
            "example": "https://staging-api.withneo.app/ready"
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "example": "https://staging-docs.withneo.app"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "appEnv",
          "applicationRelease",
          "providerEnvironment",
          "mockProvidersEnabled",
          "closedBeta"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "appEnv": {
            "type": "string",
            "enum": [
              "local",
              "test",
              "staging",
              "production"
            ]
          },
          "applicationRelease": {
            "type": "string",
            "description": "Immutable non-secret build or commit label reported by the running process."
          },
          "providerEnvironment": {
            "type": "string",
            "description": "Non-secret exact-target environment label used for provider evidence."
          },
          "mockProvidersEnabled": {
            "type": "boolean"
          },
          "closedBeta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "enabled",
              "testerCount",
              "linkEnrollment",
              "sandboxLogistics",
              "sandboxPayouts"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "testerCount": {
                "type": "integer",
                "minimum": 0
              },
              "linkEnrollment": {
                "type": "boolean"
              },
              "sandboxLogistics": {
                "type": "boolean"
              },
              "sandboxPayouts": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "ProviderHealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "configured",
          "certification",
          "observed"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "configured": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "ai",
              "identity",
              "logistics",
              "payment",
              "whatsapp"
            ],
            "properties": {
              "ai": {
                "type": "string"
              },
              "identity": {
                "type": "string"
              },
              "logistics": {
                "type": "string"
              },
              "payment": {
                "type": "string"
              },
              "whatsapp": {
                "type": "string"
              }
            }
          },
          "certification": {
            "type": "array",
            "description": "Public-safe exact-target certification summaries.",
            "items": {
              "$ref": "#/components/schemas/ProviderCertificationHealth"
            }
          },
          "observed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProviderObservation"
            }
          }
        }
      },
      "ProviderCertificationHealth": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "capability",
          "provider",
          "required",
          "certified"
        ],
        "properties": {
          "capability": {
            "type": "string",
            "enum": [
              "whatsapp",
              "meta_catalogue",
              "payment",
              "refund",
              "logistics",
              "object_storage",
              "payout"
            ]
          },
          "provider": {
            "type": "string"
          },
          "required": {
            "type": "boolean"
          },
          "certified": {
            "type": "boolean"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProviderObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "provider",
          "operationCount",
          "successCount",
          "errorCount"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "operationCount": {
            "type": "integer",
            "minimum": 0
          },
          "successCount": {
            "type": "integer",
            "minimum": 0
          },
          "errorCount": {
            "type": "integer",
            "minimum": 0
          },
          "lastEventAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastOk": {
            "type": "boolean"
          },
          "lastOperation": {
            "type": "string"
          },
          "lastStatus": {
            "type": "integer"
          },
          "lastError": {
            "type": "string"
          }
        }
      },
      "QueueHealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "inbox",
          "outbox"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "inbox": {
            "$ref": "#/components/schemas/QueueCounts"
          },
          "outbox": {
            "$ref": "#/components/schemas/QueueCounts"
          },
          "oldestInboxAt": {
            "type": "string",
            "format": "date-time"
          },
          "oldestOutboxAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "QueueCounts": {
        "type": "object",
        "additionalProperties": {
          "type": "integer",
          "minimum": 0
        }
      },
      "WebhookAcknowledgement": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "duplicate": {
            "type": "boolean",
            "description": "True when the durable event already existed."
          },
          "inboxEventId": {
            "type": "string",
            "format": "uuid",
            "description": "Opaque durable receipt identifier."
          },
          "ignored": {
            "type": "boolean",
            "description": "True for an acknowledged WhatsApp status event that requires no conversation work."
          }
        }
      },
      "MetaWebhookEnvelope": {
        "type": "object",
        "required": [
          "object",
          "entry"
        ],
        "properties": {
          "object": {
            "type": "string",
            "example": "whatsapp_business_account"
          },
          "entry": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true,
        "description": "Provider-owned Meta envelope. Neo accepts supported message and status change shapes and keeps the raw payload private."
      },
      "MetaFlowDataExchangeEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "encrypted_flow_data",
          "encrypted_aes_key",
          "initial_vector"
        ],
        "properties": {
          "encrypted_flow_data": {
            "type": "string",
            "description": "Base64-encoded AES-GCM encrypted Flow request."
          },
          "encrypted_aes_key": {
            "type": "string",
            "description": "Base64-encoded RSA-OAEP encrypted session key."
          },
          "initial_vector": {
            "type": "string",
            "description": "Base64-encoded AES-GCM initialization vector."
          }
        }
      },
      "PaymentWebhookEnvelope": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "description": "Paystack event name."
          },
          "type": {
            "type": "string",
            "description": "Flutterwave event name."
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true,
        "description": "Provider-owned payment, adjustment, or Paystack payout-transfer envelope. Exact supported event families are described on each operation."
      },
      "LogisticsWebhookEnvelope": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "trackingNumber": {
            "type": "string"
          },
          "tracking_code": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "status_code": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "description": "Provider-owned tracking envelope. Field names vary by the selected logistics adapter."
      },
      "PayoutWebhookEnvelope": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "eventId",
          "status",
          "amount",
          "currency",
          "occurredAt"
        ],
        "properties": {
          "eventId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed"
            ]
          },
          "providerReference": {
            "type": "string"
          },
          "idempotencyKey": {
            "type": "string"
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "description": "Amount in integer minor units."
          },
          "currency": {
            "type": "string",
            "const": "NGN"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed payload, unsupported event, or callback/provider mismatch.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The callback signature or authentication token is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The verification token or requested operation is not permitted.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The request exceeded the configured boundary. Retry after the number of seconds in the response header.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds until the rate-limit window permits another request.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The request body exceeded the six-megabyte server limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalError": {
        "description": "The request could not be completed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}