# MockCard public API — the single source of truth for every SDK.
# Author: Arixeva Labs <hello@arixevalabs.com>
openapi: 3.1.0
info:
  title: MockCard API
  version: "2.0.0"
  description: |
    Payment failure testing: generate test cards and outcomes, run chaos scenarios against your webhook
    handler (pull mode in CI, push mode against staging), and probe production safely.

    **Errors** always use one envelope: `{ "error": { "code": "...", "message": "..." } }`.

    **Production probes** carry `MockCard-Probe: 1` and `MockCard-Signature: t=<unix>,v1=<hex>` where
    `v1 = HMAC-SHA256(probe_secret, "<t>.<raw body>")`. A handler that verifies the signature should
    skip all processing and answer 2xx with the header `MockCard-Probe-Ack: skipped`.
  contact: { name: Arixeva Labs, email: hello@arixevalabs.com, url: https://www.mockcard.io/contact }
servers:
  - url: https://www.mockcard.io
security:
  - apiKey: []
tags:
  - { name: Runs, description: "Chaos runs: pull (CI), push (staging) and probe (production)" }
  - { name: Projects, description: One project per app or client }
  - { name: Checks, description: Health check and card generation }
  - { name: Monitors, description: Scheduled checks of staging and production }
  - { name: Keys, description: API keys }

paths:
  /api/v1/runs:
    post:
      tags: [Runs]
      summary: Create a run (paid plans)
      description: |
        `pull` (default) returns signed deliveries for the SDK to deliver to your app locally, then report
        to `/api/v1/runs/{runId}/results`. `push` delivers them to `target_url` and scores the run itself.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project_id]
              properties:
                project_id: { type: string, example: prj_3f9a1c2b7d4e5f60 }
                mode: { type: string, enum: [pull, push], default: pull }
                scenarios: { type: array, items: { $ref: "#/components/schemas/RunScenario" } }
                target_url: { type: string, format: uri, description: "Required for push. Public https:// URL." }
                time_scale: { type: number, minimum: 0, maximum: 1, default: 0.2, description: "Pull only: shrinks waits so CI is fast." }
                trigger: { type: string, enum: [ci, api], default: api }
                commit_sha: { type: string, maxLength: 64 }
                branch: { type: string, maxLength: 200 }
      responses:
        "201":
          description: Pull run created
          content:
            application/json:
              schema:
                type: object
                properties:
                  run: { $ref: "#/components/schemas/RunSummary" }
                  deliveries: { type: array, items: { $ref: "#/components/schemas/PlannedDelivery" } }
                  expectations: { type: array, items: { $ref: "#/components/schemas/Expectation" } }
        "202":
          description: Push run started
          content: { application/json: { schema: { type: object, properties: { run: { $ref: "#/components/schemas/RunSummary" } } } } }
        "4XX": { $ref: "#/components/responses/Error" }
    get:
      tags: [Runs]
      summary: List recent runs
      parameters:
        - { name: project_id, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
      responses:
        "200": { description: Runs, content: { application/json: { schema: { type: object, properties: { runs: { type: array, items: { $ref: "#/components/schemas/Run" } } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/runs/{runId}:
    get:
      tags: [Runs]
      summary: Get a run with its score and checks
      parameters: [{ name: runId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: The run, content: { application/json: { schema: { type: object, properties: { run: { $ref: "#/components/schemas/Run" } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/runs/{runId}/results:
    post:
      tags: [Runs]
      summary: Report pull-run results (once per run)
      parameters: [{ name: runId, in: path, required: true, schema: { type: string } }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [deliveries]
              properties:
                deliveries: { type: array, items: { $ref: "#/components/schemas/DeliveryResult" } }
                assertions: { type: array, maxItems: 200, items: { $ref: "#/components/schemas/AssertionResult" } }
      responses:
        "200": { description: Scored run, content: { application/json: { schema: { type: object, properties: { run: { $ref: "#/components/schemas/Run" } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/projects:
    get:
      tags: [Projects]
      summary: List projects
      responses:
        "200": { description: Projects, content: { application/json: { schema: { type: object, properties: { projects: { type: array, items: { $ref: "#/components/schemas/Project" } } } } } } }
    post:
      tags: [Projects]
      summary: Create a project (account-scoped key)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, maxLength: 80 }
                gateway: { $ref: "#/components/schemas/Gateway" }
      responses:
        "201":
          description: Created. `probe_secret` is shown only in this response.
          content: { application/json: { schema: { type: object, properties: { project: { $ref: "#/components/schemas/Project" }, probe_secret: { type: string } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/projects/{projectId}:
    parameters: [{ name: projectId, in: path, required: true, schema: { type: string } }]
    get:
      tags: [Projects]
      summary: Get a project
      responses:
        "200": { description: The project, content: { application/json: { schema: { type: object, properties: { project: { $ref: "#/components/schemas/Project" } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }
    patch:
      tags: [Projects]
      summary: Update a project (account-scoped key)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 80 }
                gateway: { $ref: "#/components/schemas/Gateway" }
                signing_secret:
                  type: [string, "null"]
                  description: Your gateway's test-mode webhook secret. Events are then signed exactly as the gateway signs them. Write-only; null removes it.
      responses:
        "200": { description: Updated, content: { application/json: { schema: { type: object, properties: { project: { $ref: "#/components/schemas/Project" } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }
    delete:
      tags: [Projects]
      summary: Delete a project and its runs (account-scoped key)
      responses:
        "200": { description: Deleted }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/projects/{projectId}/probe-secret:
    post:
      tags: [Projects]
      summary: Rotate the probe secret (shown once)
      parameters: [{ name: projectId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: New secret, content: { application/json: { schema: { type: object, properties: { probe_secret: { type: string } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/projects/{projectId}/probe:
    post:
      tags: [Projects]
      summary: Send one production probe now and check the acknowledgement
      parameters: [{ name: projectId, in: path, required: true, schema: { type: string } }]
      requestBody:
        required: true
        content: { application/json: { schema: { type: object, required: [url], properties: { url: { type: string, format: uri } } } } }
      responses:
        "200": { description: Probe result, content: { application/json: { schema: { type: object, properties: { run: { $ref: "#/components/schemas/Run" }, acked: { type: boolean } } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/audit/quick:
    post:
      tags: [Checks]
      summary: Webhook health check (5 probes, scored out of 100)
      security: [{ apiKey: [] }, {}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [webhook_url]
              properties:
                webhook_url: { type: string, format: uri }
                gateway: { $ref: "#/components/schemas/Gateway" }
      responses:
        "200": { description: Probe results with score, grade and share_token }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/generate:
    post:
      tags: [Checks]
      summary: Generate a test card and payment outcome
      security: [{ apiKey: [] }, {}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                brand: { type: string, enum: [visa, mastercard, rupay, amex], default: visa }
                scenario: { type: string, enum: [success, insufficient_funds, do_not_honor, expired_card, incorrect_cvv, 3ds_challenge, network_timeout, 3ds_abandoned, limbo, latency], default: success }
                gateway: { $ref: "#/components/schemas/Gateway" }
                amount: { type: integer, minimum: 1, maximum: 100000000, default: 1000 }
                currency: { type: string, minLength: 3, maxLength: 3, default: inr }
                webhook_url: { type: string, format: uri, description: Paid plans deliver the signed event here. }
                return_url: { type: string }
                simulate_race: { type: boolean, description: Paid plans. Deliver the event twice. }
      responses:
        "201": { description: Card and outcome }
        "402": { description: Decline scenarios (by design) or a paid feature requested on a free plan }
        "504": { description: network_timeout scenario }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/keys:
    get:
      tags: [Keys]
      summary: List API keys (prefixes only)
      responses:
        "200": { description: Keys }
    post:
      tags: [Keys]
      summary: Create an API key (full key shown once)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 60 }
                scope: { type: string, enum: [ci, account], default: ci }
      responses:
        "201": { description: "`key` is shown only in this response" }

  /api/keys/{keyId}:
    delete:
      tags: [Keys]
      summary: Revoke an API key
      parameters: [{ name: keyId, in: path, required: true, schema: { type: integer } }]
      responses:
        "200": { description: Revoked }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/monitors:
    get:
      tags: [Monitors]
      summary: List monitors (paid plans)
      responses:
        "200": { description: Monitors, content: { application/json: { schema: { type: object, properties: { monitors: { type: array, items: { $ref: "#/components/schemas/Monitor" } } } } } } }
    post:
      tags: [Monitors]
      summary: Create a monitor (runs once its domain is verified)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project_id, url, environment]
              properties:
                project_id: { type: string }
                url: { type: string, format: uri }
                environment: { type: string, enum: [staging, production], description: "production sends only signed probes, after one has been acknowledged" }
                interval_minutes: { type: integer, enum: [60, 360, 1440], default: 1440 }
                scenarios: { type: array, items: { $ref: "#/components/schemas/RunScenario" } }
                alert_email: { type: boolean, default: true }
                slack_webhook_url: { type: [string, "null"] }
      responses:
        "201":
          description: Created, with the DNS record or file that verifies the domain
          content: { application/json: { schema: { type: object, properties: { monitor: { $ref: "#/components/schemas/Monitor" }, verification: { type: object } } } } }
        "4XX": { $ref: "#/components/responses/Error" }

  /api/v1/monitors/{monitorId}:
    parameters: [{ name: monitorId, in: path, required: true, schema: { type: string } }]
    get: { tags: [Monitors], summary: Get a monitor, responses: { "200": { description: The monitor }, "4XX": { $ref: "#/components/responses/Error" } } }
    patch:
      tags: [Monitors]
      summary: Update schedule, scenarios, alerts or paused state
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interval_minutes: { type: integer, enum: [60, 360, 1440] }
                scenarios: { type: array, items: { $ref: "#/components/schemas/RunScenario" } }
                alert_email: { type: boolean }
                slack_webhook_url: { type: [string, "null"] }
                paused: { type: boolean }
      responses: { "200": { description: Updated }, "4XX": { $ref: "#/components/responses/Error" } }
    delete: { tags: [Monitors], summary: Delete a monitor, responses: { "200": { description: Deleted }, "4XX": { $ref: "#/components/responses/Error" } } }

  /api/v1/monitors/{monitorId}/verify:
    post:
      tags: [Monitors]
      summary: Check domain verification (DNS TXT or well-known file)
      parameters: [{ name: monitorId, in: path, required: true, schema: { type: string } }]
      responses: { "200": { description: "{ verified, method }" }, "4XX": { $ref: "#/components/responses/Error" } }

  /api/v1/monitors/{monitorId}/run:
    post:
      tags: [Monitors]
      summary: Run a monitor now (confirms the probe guard for production monitors)
      parameters: [{ name: monitorId, in: path, required: true, schema: { type: string } }]
      responses: { "200": { description: The run }, "4XX": { $ref: "#/components/responses/Error" } }

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: "`ci` keys can create runs and checks; `account` keys can also manage projects and keys."
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: object
                required: [code, message]
                properties:
                  code: { type: string, example: invalid_request }
                  message: { type: string }
  schemas:
    Gateway: { type: string, enum: [stripe, razorpay], default: stripe }
    RunScenario:
      type: string
      enum: [success, insufficient_funds, do_not_honor, expired_card, incorrect_cvv, 3ds_challenge, network_timeout, 3ds_abandoned, limbo, latency, duplicate]
    RunStatus: { type: string, enum: [running, passed, failed, error] }
    PlannedDelivery:
      type: object
      required: [id, scenario, at_ms, group, event_type, probe, body, headers]
      properties:
        id: { type: string, example: dlv_1 }
        scenario: { $ref: "#/components/schemas/RunScenario" }
        at_ms: { type: integer, description: Deliver this many ms after the run starts. }
        group: { type: [string, "null"], description: Deliveries sharing a group are sent at the same moment, concurrently. }
        event_type: { type: string }
        probe: { type: boolean }
        body: { type: string, description: Send these exact bytes; the signature covers them. }
        headers: { type: object, additionalProperties: { type: string } }
    Expectation:
      type: object
      properties:
        scenario: { $ref: "#/components/schemas/RunScenario" }
        expectation: { type: string }
    DeliveryResult:
      type: object
      required: [delivery_id, status_code]
      properties:
        delivery_id: { type: string }
        status_code: { type: [integer, "null"], minimum: 100, maximum: 599 }
        duration_ms: { type: integer }
        error: { type: string }
    AssertionResult:
      type: object
      required: [scenario, name, passed]
      properties:
        scenario: { $ref: "#/components/schemas/RunScenario" }
        name: { type: string, maxLength: 200 }
        passed: { type: boolean }
        message: { type: string, maxLength: 1000 }
    RunSummary:
      type: object
      properties:
        id: { type: string }
        project_id: { type: string }
        mode: { type: string, enum: [pull, push, probe] }
        status: { $ref: "#/components/schemas/RunStatus" }
        scenarios: { type: array, items: { $ref: "#/components/schemas/RunScenario" } }
    Run:
      allOf:
        - $ref: "#/components/schemas/RunSummary"
        - type: object
          properties:
            trigger: { type: string, enum: [api, ci, monitor, dashboard] }
            score: { type: [integer, "null"], minimum: 0, maximum: 100 }
            commit_sha: { type: [string, "null"] }
            branch: { type: [string, "null"] }
            created_at: { type: string, format: date-time }
            completed_at: { type: [string, "null"], format: date-time }
            results:
              type: [object, "null"]
              properties:
                checks:
                  type: array
                  items:
                    type: object
                    properties:
                      scenario: { $ref: "#/components/schemas/RunScenario" }
                      name: { type: string }
                      passed: { type: boolean }
                      detail: { type: string }
    Monitor:
      type: object
      properties:
        id: { type: string }
        project_id: { type: string }
        url: { type: string }
        environment: { type: string, enum: [staging, production] }
        interval_minutes: { type: integer }
        scenarios: { type: array, items: { $ref: "#/components/schemas/RunScenario" } }
        verified_at: { type: [string, "null"], format: date-time }
        probe_ack_at: { type: [string, "null"], format: date-time }
        alert_email: { type: boolean }
        has_slack: { type: boolean }
        paused: { type: boolean }
        last_run_id: { type: [string, "null"] }
        last_status: { type: [string, "null"] }
        next_run_at: { type: string, format: date-time }
    Project:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        gateway: { $ref: "#/components/schemas/Gateway" }
        has_signing_secret: { type: boolean }
        created_at: { type: string, format: date-time }
