paths:
  /customers/{customerId}/cards/register:
    post:
      summary: Register customer for card issuance
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dateOfBirth, address]
              properties:
                bvn:
                  type: string
                  description: "Optional override. The customer's BVN on file is used if omitted."
                  example: "22222222222"
                dateOfBirth:
                  type: string
                  format: date
                  example: "1990-05-15"
                address:
                  type: string
                  description: "Residential address (Required)."
                  example: "123 Main Street, Lagos"
                selfieUrl:
                  type: string
                  description: "Optional selfie image URL for KYC."
                  example: "https://example.com/selfie.jpg"
                idDocument:
                  type: string
                  description: "Optional ID Document URL for KYC."
                  example: "https://example.com/id.jpg"
      responses:
        '200':
          description: Customer registered for cards successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Customer mapped to Payscribe successfully, ready for card issuance."

  /customers/{customerId}/cards:
    post:
      summary: Create a new virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: "Amount to fund the new virtual card (Required)"
                  example: 10
                brand:
                  type: string
                  enum: [verve, mastercard, visa]
                  example: "mastercard"
                currency:
                  type: string
                  enum: [NGN, USD]
                  example: "USD"
                dob:
                  type: string
                  description: "Date of Birth (YYYY-MM-DD). Required if customer is not yet registered on PayScribe."
                  example: "1990-01-01"
                address:
                  type: string
                  description: "Residential Address. Required if customer is not yet registered on PayScribe."
                  example: "123 Main Street, Lagos"
                selfieUrl:
                  type: string
                  description: "Optional selfie image URL for KYC."
                  example: "https://example.com/selfie.jpg"
                idDocument:
                  type: string
                  description: "Optional ID Document URL for KYC."
                  example: "https://example.com/id.jpg"
      responses:
        '201':
          description: Virtual card created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Card created successfully"
                  data:
                    type: object
                    properties:
                      cardId:
                        type: string
                        format: uuid
                      cardNumber:
                        type: string
                        example: "5399 **** **** 1234"
                      cvv:
                        type: string
                        example: "***"
                      expiryDate:
                        type: string
                        example: "12/28"

    get:
      summary: Get all cards for a customer
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of customer cards
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        brand:
                          type: string
                          example: "mastercard"
                        status:
                          type: string
                          example: "active"
                        balance:
                          type: number
                          example: 150.50

  /customers/{customerId}/cards/{cardId}/topup:
    post:
      summary: Top up a virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: cardId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 50
      responses:
        '200':
          description: Card top-up successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Card topped up successfully"

  /customers/{customerId}/cards/{cardId}/withdraw:
    post:
      summary: Withdraw from a virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: cardId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 20
      responses:
        '200':
          description: Withdrawal successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Funds withdrawn from card to virtual account successfully"

  /customers/{customerId}/cards/{cardId}/freeze:
    post:
      summary: Freeze a virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: cardId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Card frozen successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Card frozen"

  /customers/{customerId}/cards/{cardId}/unfreeze:
    post:
      summary: Unfreeze a virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: cardId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Card unfrozen successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Card unfrozen"

  /customers/{customerId}/cards/{cardId}/terminate:
    post:
      summary: Terminate a virtual card
      tags: [Cards]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: cardId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Card terminated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Card permanently terminated"
