{
  "openapi": "3.1.0",
  "info": {
    "title": "Rihuum Commerce Standard API",
    "version": "1.0.0",
    "description": "Product-scoped payment-intent, provider-readiness and verified-webhook contract for Rihuum products. An implemented adapter is not evidence of a connected merchant account or live settlement."
  },
  "servers": [
    {
      "url": "https://rihuum.com"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "summary": "List the controlled Rihuum product register",
        "responses": {
          "200": {
            "description": "Product register"
          }
        }
      }
    },
    "/api/payments/providers": {
      "get": {
        "summary": "List provider implementation and runtime readiness",
        "responses": {
          "200": {
            "description": "Provider readiness with explicit activation disclosure"
          }
        }
      }
    },
    "/api/payments/initialize": {
      "post": {
        "summary": "Create or replay an idempotent payment intent",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment intent created"
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Origin is not allowlisted"
          },
          "503": {
            "description": "Ledger, credential, verified destination or provider contract is unavailable"
          }
        }
      }
    },
    "/api/payments/intents/{reference}": {
      "get": {
        "summary": "Read a redacted payment-intent status",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Redacted payment intent"
          },
          "404": {
            "description": "Payment intent not found"
          }
        }
      }
    },
    "/api/payments/webhooks/{provider}": {
      "post": {
        "summary": "Receive, deduplicate and independently verify a signed provider event",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "paystack",
                "squad",
                "flutterwave"
              ]
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Event recorded or safely ignored"
          },
          "401": {
            "description": "Invalid signature"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PaymentRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "productId",
          "provider",
          "amountMinor",
          "currency",
          "email"
        ],
        "properties": {
          "productId": {
            "type": "string"
          },
          "provider": {
            "type": "string",
            "enum": [
              "paystack",
              "squad",
              "flutterwave",
              "globalpay",
              "bank_transfer",
              "cryptocurrency"
            ]
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 100,
            "maximum": 100000000000
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "description": {
            "type": "string",
            "maxLength": 160
          },
          "callbackUrl": {
            "type": "string",
            "format": "uri"
          },
          "requestedBank": {
            "type": "string"
          },
          "asset": {
            "type": "string"
          },
          "network": {
            "type": "string"
          }
        }
      }
    }
  }
}