openapi: 3.0.0
info:
  title: Azapay API
  description: |
    Azapay API provides endpoints for managing crypto wallets, transactions, and user verification.
    The API follows REST principles and uses JSON for request/response bodies.
  version: 1.0.0
  contact:
    name: Azapay Support
    email: support@azapay.com

servers:
  - url: https://api.azapay.com/v1
    description: Production server
  - url: https://staging-api.azapay.com/v1
    description: Staging server

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        kyc_status:
          type: string
          enum: [unverified, pending, verified]
        tier:
          type: string
          enum: [basic, verified, premium]
        verification_level:
          type: string
          enum: [unverified, basic, verified]
        daily_transaction_total:
          type: number
          format: float
        monthly_transaction_total:
          type: number
          format: float
        preferred_currency:
          type: string
          enum: [USD, EUR, GBP, NGN]
        created_at:
          type: string
          format: date-time

    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        transaction_ref:
          type: string
        type:
          type: string
          enum: [transfer, deposit, withdraw, wallet_creation]
        amount:
          type: number
          format: float
        currency:
          type: string
        crypto_currency:
          type: string
        status:
          type: string
          enum: [pending, completed, failed, refunded]
        created_at:
          type: string
          format: date-time

    Wallet:
      type: object
      properties:
        id:
          type: string
          format: uuid
        wallet_address:
          type: string
        balance:
          type: number
          format: float
        currency:
          type: string
        status:
          type: string
          enum: [active, inactive, suspended]
        created_at:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: integer

paths:
  /auth/register:
    post:
      summary: Register a new user
      tags: [Authentication]
      x-rate-limit:
        window: 3600
        max: 3
        description: Maximum 3 registrations per hour per IP address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - phone
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                phone:
                  type: string
      responses:
        "201":
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/login:
    post:
      summary: Login user
      tags: [Authentication]
      x-rate-limit:
        window: 300
        max: 5
        description: Maximum 5 login attempts per 5 minutes per IP address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  user:
                    $ref: "#/components/schemas/User"
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /wallet/balance:
    get:
      summary: Get wallet balance
      tags: [Wallet]
      security:
        - BearerAuth: []
      x-rate-limit:
        window: 60
        max: 30
        description: Maximum 30 balance checks per minute per user
      responses:
        "200":
          description: Wallet balance retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet_address:
                    type: string
                  balance:
                    type: object
                    properties:
                      value:
                        type: number
                        format: float
                      currency:
                        type: string
                      crypto_currency:
                        type: string
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /wallet/transfer:
    post:
      summary: Transfer funds
      tags: [Wallet]
      security:
        - BearerAuth: []
      x-rate-limit:
        window: 3600
        max: 10
        description: Maximum 10 transfers per hour per user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - amount
                - currency
              properties:
                email:
                  type: string
                  format: email
                amount:
                  type: number
                  format: float
                currency:
                  type: string
                  enum: [USD, EUR, GBP, NGN]
      responses:
        "200":
          description: Transfer successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  transaction:
                    $ref: "#/components/schemas/Transaction"
                  amount:
                    type: object
                    properties:
                      value:
                        type: number
                        format: float
                      currency:
                        type: string
                      crypto_currency:
                        type: string
        "400":
          description: Invalid input or insufficient funds
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /kyc/submit:
    post:
      summary: Submit KYC documents
      tags: [KYC]
      security:
        - BearerAuth: []
      x-rate-limit:
        window: 86400
        max: 3
        description: Maximum 3 KYC submissions per day per user
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - document_type
                - document_number
                - document_country
                - date_of_birth
                - document_image
                - user_image
              properties:
                document_type:
                  type: string
                  enum: [passport, national_id, drivers_license]
                document_number:
                  type: string
                document_country:
                  type: string
                date_of_birth:
                  type: string
                  format: date
                document_image:
                  type: string
                  format: binary
                document_image_back:
                  type: string
                  format: binary
                user_image:
                  type: string
                  format: binary
      responses:
        "200":
          description: KYC submission successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  tier:
                    type: string
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /kyc/submit-address:
    post:
      summary: Submit address verification
      tags: [KYC]
      security:
        - BearerAuth: []
      x-rate-limit:
        window: 86400
        max: 3
        description: Maximum 3 address verifications per day per user
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - country
                - state
                - city
                - street
                - zip
                - proof_of_address
              properties:
                country:
                  type: string
                state:
                  type: string
                city:
                  type: string
                street:
                  type: string
                zip:
                  type: string
                proof_of_address:
                  type: string
                  format: binary
      responses:
        "200":
          description: Address verification successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  tier:
                    type: string
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /kyc/submit-background-check:
    post:
      summary: Submit background check
      tags: [KYC]
      security:
        - BearerAuth: []
      x-rate-limit:
        window: 86400
        max: 2
        description: Maximum 2 background checks per day per user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - employment_status
                - occupation
                - primary_purpose
                - source_of_funds
              properties:
                employment_status:
                  type: string
                  enum: [employed, self_employed, unemployed, student]
                occupation:
                  type: string
                primary_purpose:
                  type: string
                source_of_funds:
                  type: string
                expected_monthly_inflow:
                  type: number
                  format: float
      responses:
        "200":
          description: Background check submission successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  tier:
                    type: string
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /webhooks/transactions:
    post:
      summary: Handle transaction webhooks
      tags: [Webhooks]
      x-rate-limit:
        window: 60
        max: 100
        description: Maximum 100 webhook calls per minute per IP address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - data
              properties:
                type:
                  type: string
                  enum: [transfer.completed, transfer.failed, transfer.pending]
                data:
                  type: object
                  properties:
                    reference:
                      type: string
                    amount:
                      type: number
                      format: float
                    currency:
                      type: string
                    status:
                      type: string
                    timestamp:
                      type: string
                      format: date-time
      responses:
        "200":
          description: Webhook processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        "401":
          description: Invalid webhook signature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
