openapi: 3.0.0
info:
  title: Gateway
  description: |
    # API

    Before you begin, follow the [Quick-start checklist](/docs/common/getting-started).

    Available environments:
    - **Production:** `https://gateway.vertex-cards.com`
    - **Demo:** `https://gateway.demo.vertex-cards.com`

    ## OpenAPI File Export
    For your convenience, you can download the OpenAPI file of our API: [download API Reference](/api-reference.yaml)
  version: 1.0.0
servers:
  - url: https://gateway.vertex-cards.com
    description: Production environment host.
  - url: https://gateway.demo.vertex-cards.com
    description: Demo environment host.
paths:
  /api/v1/cards/companies/{companyUuid}/accounts/providers:
    get:
      tags:
        - Accounts
      summary: "Retrieve Available Provider Accounts"
      description: |
        Returns a list of available provider accounts for the specified company. Use the returned `id` when [creating a new account](/docs/api-reference/post-cards-companies-accounts-create) to link it to the desired provider.
      operationId: get_cards_companies_accounts_providers
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "List of available provider accounts."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: "List of available provider accounts."
                    items:
                      $ref: "#/components/schemas/ProviderAccountInfo"
                type: object
  /api/v1/cards/companies/{companyUuid}/bins:
    post:
      tags:
        - Accounts
      summary: "Retrieve Available BINs"
      description: "Retrieves a list of BIN categories with detailed information about available BINs for card issuance within the specified company."
      operationId: get_app_external_v1_cardissue_cardbin_cardbin_listwithbins
      parameters:
        - name: accountIds
          in: query
          required: false
          description: "Array of account identifiers to filter BIN categories."
          example: ["9f283e59-21ec-4c74-ae32-156d49cd9cf2"]
          schema:
            type: array
            items:
              type: string
        - name: companyProviderIds
          in: query
          required: false
          description: "Array of provider identifiers to filter BIN categories."
          example: ["1f01110f-e8b1-6188-80e5-52f68afc03c5"]
          schema:
            type: array
            items:
              type: string
        - name: binCategories
          in: query
          required: false
          description: "Array of category type names to filter results."
          example: ["travel", "corporate_expenses"]
          schema:
            type: array
            items:
              type: string
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: categoryTypes[]
          in: query
          required: false
          description: "Alternative format for filtering by category type names."
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: categoryIds[]
          in: query
          required: false
          description: "Alternative format for filtering by category identifiers."
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: page
          in: query
          required: false
          description: "Page number for paginated results."
          schema:
            type: integer
            minimum: 0
            nullable: true
        - name: quantity
          in: query
          required: false
          description: "Number of records to retrieve per page."
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: true
            nullable: true
      responses:
        "200":
          description: "List of BIN categories with detailed BIN information."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: "Array of BIN category objects, each containing information about the category and its associated BINs."
                    items:
                      $ref: "#/components/schemas/V1CardIssueCardBinResponseCardBinCategoryWithBinDetailsResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object
  /api/v1/cards/companies/{companyUuid}/accounts:
    post:
      tags:
        - Accounts
      summary: "Create a New Account"
      description: |
        Creates a new account for the specified company, linked to a provider account. 
        The `id` field in the request body must be set to the identifier of the provider account, as returned by the [Retrieve Available Provider Accounts](/docs/api-reference/get-cards-companies-accounts-providers) endpoint. 
        The response contains the identifier of the newly created account.

        :::info
        This request is asynchronous. After you receive the `201` response, wait a short moment and then call [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details) to confirm that the account has been created and its `status` is `active`.
        :::
      operationId: post_cards_companies_accounts_create
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAccountRequest"
      responses:
        "201":
          description: "Account creation request accepted."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - id
                    properties:
                      id:
                        type: string
                        description: "Unique identifier of the created account."
                        example: "8f3d0c3d-9f3e-4ef6-8fae-c3169025dfcb"
                type: object
    get:
      tags:
        - Accounts
      summary: "Retrieve All Accounts for a Company"
      description: "Returns a list of all accounts associated with a specified company"
      operationId: get_app_external_v1_cardissue_account_account_getcompanyaccountsbyid
      parameters:
        - name: companyUuid
          in: path
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
        - name: page
          in: query
          required: false
          description: "Page number for paginated results."
          schema:
            type: integer
            default: 1
        - name: quantity
          in: query
          description: "Number of records to retrieve per page."
          required: false
          schema:
            type: integer
            default: 25
      responses:
        "200":
          description: Account data.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: "List of accounts associated with the specified company."
                    items:
                      $ref: "#/components/schemas/V1CardIssueAccountResponseCompanyAccountResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object
  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}:
    get:
      tags:
        - Accounts
      summary: "Retrieve Account Details"
      description: "Retrieves detailed information about a specific account belonging to a company, identified by their ids."
      operationId: get_app_external_v1_cardissue_account_account_details
      parameters:
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: Account data.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueAccountResponseAccountResponse"
                type: object
    patch:
      tags:
        - Accounts
      operationId: patch_app_external_v1_cardissue_account_account_update
      summary: "Update Account"
      description: |
        Updates the data of the specified account within a given company.

        :::info
        The request is asynchronous. Call the [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details) endpoint after a short delay to confirm that the update has completed successfully.
        :::
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueAccountRequestUpdateAccountRequest"
      responses:
        "204":
          description: "Account update request accepted."
  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/disable:
    post:
      tags:
        - Accounts
      operationId: post_app_external_v1_cardissue_account_account_deactivate
      summary: "Deactivate Account"
      description: |
        Deactivates the specified account belonging to a company, preventing any further usage of this account.

        Sets `status` field is `inactive` in [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details).

        :::info
        The request is asynchronous. Call the [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details) endpoint after a short delay to confirm that the deactivation has completed successfully.
        :::
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "204":
          description: "Account deactivation request accepted."

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/enable:
    post:
      tags:
        - Accounts
      operationId: post_app_external_v1_cardissue_account_account_activate
      summary: "Activate Account"
      description: |
        Reactivates the specified account belonging to a company, allowing the account to be used again.
        Sets `status` field is `active` in [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details).

        :::info
        The request is asynchronous. Call the [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details) endpoint after a short delay to confirm that the deactivation has completed successfully.
        :::
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "204":
          description: "Account activation request accepted."

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/restrictions:
    get:
      tags:
        - Accounts
      operationId: get_app_external_v1_cardissue_account_account_availablecardlimits
      summary: "Retrieve Card Creation Restrictions"
      description: "Retrieves information about the restrictions and limits related to creating new cards for a specified account within a given company."
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Available restrictions and limits for card creation."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: "List of restrictions, including limit details and BIN configurations for card creation."
                    items:
                      $ref: "#/components/schemas/V1CardIssueAccountResponseAccountRestrictionsResponse"
                type: object
  /api/v1/cards/accounts/{accountUuid}/accounts-available-for-transfer:
    get:
      tags:
        - Account Transfers
      summary: "Retrieve Accounts Available for Transfer"
      description: "Returns a paginated list of accounts that are available as destinations for a balance transfer from the specified account."
      operationId: get_app_external_v1_cardissue_account_account_listavailablefortransfer
      parameters:
        - name: page
          in: query
          required: false
          description: "Page number for paginated results."
          schema:
            type: integer
            default: 1
        - name: quantity
          in: query
          required: false
          description: "Number of records to retrieve per page."
          schema:
            type: integer
            default: 20
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the source account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "List of accounts available for transfer."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    "$ref": "#/components/schemas/V1CardIssueAccountResponseListAccountAvailableTransferResponse"
                    type: object
                type: object
  /api/v1/cards/accounts/{accountUuid}/balance/transfer:
    post:
      tags:
        - Account Transfers
      summary: "Transfer Account Balance"
      description: |
        Transfers a specified amount from the source account to a destination account.

        :::info
        This request is asynchronous.
        :::
      operationId: post_app_external_v1_cardissue_account_account_transferbalance
      parameters:
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the source account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/V1CardIssueAccountRequestTransferBalanceRequest"
      responses:
        "204":
          description: "Balance transfer request accepted."
  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards:
    get:
      tags:
        - Cards
      operationId: get_app_external_v1_cardissue_card_card_list
      summary: "Retrieve Cards for an Account"
      description: "Retrieves a list of cards associated with a specified account belonging to a given company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: statuses[]
          in: query
          required: false
          description: |
            Filter by one or more card statuses.

            Possible values:
            - **creating**: The card is in the process of being created.
            - **creating_failed**: The creation process for the card has failed.
            - **active**: The card is active and can be used for transactions.
            - **frozen**: The card is [temporarily frozen](/docs/api-reference/post-app-external-v-1-cardissue-card-card-freeze) and cannot be used. But can be [reactivated](/docs/api-reference/post-app-external-v-1-cardissue-card-card-activate).
            - **closed**: The card has been permanently closed and cannot be reactivated.
            - **expired**: The card has passed its expiry date and can no longer be used.
          schema:
            type: array
            items:
              type: string
              enum:
                - creating
                - creating_failed
                - active
                - frozen
                - closed
                - expired
            default: null
            nullable: true
        - name: page
          in: query
          required: false
          description: "Page number for paginated results. If not provided, all results are returned."
          schema:
            type: integer
            default: null
            minimum: 0
            nullable: true
        - name: quantity
          in: query
          required: false
          description: "Number of cards per page."
          schema:
            type: integer
            default: 25
            minimum: 0
            exclusiveMinimum: true
            nullable: true
        - name: createdAtFrom
          in: query
          required: false
          description: "Filter results to only include cards created at or after this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
            default: null
            nullable: true
        - name: createdAtTo
          in: query
          required: false
          description: "Filter results to only include cards created at or before this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
            default: null
            nullable: true
        - name: sortBy
          in: query
          required: false
          description: "Field by which to sort results."
          schema:
            type: string
            default: createdAt
            enum:
              - createdAt
              - name
              - status
            nullable: true
        - name: sortType
          in: query
          required: false
          description: "Sorting direction."
          schema:
            type: string
            default: desc
            enum:
              - desc
              - asc
            nullable: true
      responses:
        "200":
          description: "List of cards."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/V1CardIssueCardResponseGetCardResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object
    post:
      tags:
        - Cards
      operationId: post_app_external_v1_cardissue_card_card_create
      summary: "Issue a New Card"
      description: |
        Creates (issues) a new card under the specified account within a given company.

        :::info
        This is an asynchronous operation. After you initiate the card issuance, the card's status might initially be `creating`. You should call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `status` field to confirm when the card becomes `active` (or if the creation fails with `creating_failed`).
        :::
      parameters:
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account where the card will be issued."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardRequestCreateCardRequest"
      responses:
        "201":
          description: "Card creation request accepted."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardResponseCreateCardResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}:
    get:
      tags:
        - Cards
      operationId: get_app_external_v1_cardissue_card_card_getbyid
      summary: "Retrieve Card Details"
      description: "Returns detailed information about a specific card belonging to an account within a given company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          schema:
            type: string
            description: "Unique identifier of the company."
            example: "123e4567-e89b-12d3-a456-426614174000"
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          schema:
            type: string
            description: "Unique identifier of the account."
            example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          required: true
          schema:
            type: string
            description: "Unique identifier of the card."
            example: "de98a456-7891-12d3-a456-426614174abc"
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: Card data.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardResponseGetCardDetailsResponse"
                type: object
    patch:
      tags:
        - Cards
      operationId: patch_app_external_v1_cardissue_card_card_edit
      summary: "Update Card"
      description: |
        Updates the limit settings of an existing card under the specified account within a given company.

        :::info
        This request is asynchronous.  
        After sending the update, the data might not change right away.  
        Wait a short moment, then call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) to confirm that the new values have been applied successfully.
        :::
      parameters:
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account that the card belongs to."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          required: true
          description: "Unique identifier of the card to be updated."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardRequestEditCardRequest"
      responses:
        "200":
          description: "Request to update the card was accepted."

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/sensitive:
    get:
      tags:
        - Cards
      operationId: get_app_external_v1_cardissue_card_card_getcredentials
      summary: "Retrieve Card's Sensitive Information"
      description: "Returns sensitive details for a specific card belonging to an account in a given company."
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account containing the card."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          required: true
          description: "Unique identifier of the card whose sensitive details are requested."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Card sensitive data."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardResponseDetailsGetCardSensitiveResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/freeze:
    post:
      tags:
        - Cards
      operationId: post_app_external_v1_cardissue_card_card_freeze
      summary: "Freeze Card"
      description: |
        Freezes the specified card, preventing any further transactions and actions. 

        You can unfreeze (activate) the card again by calling the [Activate Frozen Card](/docs/api-reference/post-app-external-v-1-cardissue-card-card-activate) endpoint.  
        When a card is frozen, its `status` is set to `frozen`.  

        :::info
        This request is asynchronous: to confirm the card has been frozen, call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `status`.
        :::
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account containing the card to be frozen."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          required: true
          description: "Unique identifier of the card to be frozen."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "204":
          description: |
            Request to freeze the card was accepted.

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/activate:
    post:
      tags:
        - Cards
      operationId: post_app_external_v1_cardissue_card_card_activate
      summary: "Activate Frozen Card"
      description: |
        Reactivates (unfreezes) a card that is currently in the `frozen` state, allowing transactions to resume.  
        This endpoint is only valid if the card is currently `frozen`. 
        When successfully reactivated, the card's `status` becomes `active`.  
        :::info
        This request is asynchronous: to confirm the card has been activated, call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `status`.
        :::
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          required: true
          description: "Unique identifier of the account containing the card to be activated."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          description: "Unique identifier of the card to be activated."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "204":
          description: |
            Request to activate (unfreeze) the card was accepted.  
            This indicates the activation operation has started, but to confirm the status is now `active`, you must call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `status`.

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/close:
    post:
      tags:
        - Cards
      operationId: post_app_external_v1_cardissue_card_card_close
      summary: "Close Card"
      description: |
        Closes (blocks) the specified card. This action stops any operations with the card.
        :::warning
        This action is irreversible. Once a card is blocked, it cannot be restored.
        :::
        :::info
        This endpoint call is asynchronous: after making this request, you should verify that the card is blocked by calling the [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) endpoint and checking its `status = closed`.
        :::
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          description: "Unique identifier of the account containing the card to be closed."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          description: "Unique identifier of the card to be closed."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "204":
          description: |
            Request to close (block) the card was accepted.  
            This only indicates that the operation to block the card has started.  
            You must call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `status = closed` field to confirm that the card is blocked.

  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/balance/top-up:
    patch:
      tags:
        - Cards
      summary: Top up card balance
      description: |
        Tops up the specified card's balance using funds from the associated account balance.

        :::info
        This operation is asynchronous.  
        After receiving a `204` response, the top-up process has started, but may not be completed immediately.  
        To confirm the updated card balance, call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `availableBalance` field.
        :::
      operationId: patch_app_external_v1_cardissue_card_card_topup
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          description: "Unique identifier of the account containing the card."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          description: "Unique identifier of the card to be topped up."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardRequestTopUpCardRequest"
      responses:
        "200":
          description: |
            Request to top up the card balance was accepted.
            This only indicates that the top-up operation has started.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardResponseCardTopUpResponse"
                type: object
  /api/v1/cards/companies/{companyUuid}/accounts/{accountUuid}/cards/{cardUuid}/balance/withdraw:
    patch:
      tags:
        - Cards
      summary: Withdraw card balance
      description: |
        Withdraws funds from the specified card's balance to the associated account balance.

        :::info
        This operation is asynchronous.  
        After receiving a `204` response, the withdrawal process has started, but may not be completed immediately.  
        To confirm the updated card balance, call [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) and check the `availableBalance` field.
        :::
      operationId: patch_app_external_v1_cardissue_card_card_withdraw
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountUuid
          in: path
          description: "Unique identifier of the account containing the card."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardUuid
          in: path
          description: "Unique identifier of the card to withdraw from."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardRequestWithdrawCardRequest"
      responses:
        "200":
          description: |
            Request to withdraw funds from the card balance to the account balance was accepted.
            This only indicates that the withdrawal operation has started.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardResponseCardTopUpResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/card-owners:
    post:
      tags:
        - Card owners
      operationId: post_app_external_v1_cardissue_cardowner_cardowner_create
      summary: "Create Card Owner"
      description: |
        Creates a new card owner within the specified company. The same `cardOwnerId` can be reused to create multiple cards.

        :::info
        This request is asynchronous.  
        After you receive the `201` response, wait a short moment and then call [Retrieve Card Owner Data](/docs/api-reference/get-app-external-v-1-cardissue-cardowner-cardowner-getbyid) to confirm the owner has been created successfully.
        :::
      parameters:
        - name: companyUuid
          in: path
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardOwnerRequestCreateCardOwnerRequest"
      responses:
        "201":
          description: "Card owner creation request accepted."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardOwnerResponseCreateCardOwnerResponse"
                type: object

    get:
      tags:
        - Card owners
      operationId: get_app_external_v1_cardissue_cardowner_cardowner_list
      summary: "Retrieve List of Card Owners"
      description: "Returns a list of card owners for a specified company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: page
          in: query
          description: "Page number for paginated results. If not provided, defaults to retrieving all pages."
          example: 1
          required: false
          schema:
            type: integer
            default: null
            minimum: 0
            nullable: true
        - name: quantity
          in: query
          required: false
          description: "Number of owners per page."
          example: 25
          schema:
            type: integer
            default: 25
            minimum: 0
            exclusiveMinimum: true
            nullable: true
      responses:
        "200":
          description: "List of card owners."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/V1CardIssueCardResponseDetailsCardOwnerResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/card-owners/{cardOwnerId}:
    get:
      tags:
        - Card owners
      operationId: get_app_external_v1_cardissue_cardowner_cardowner_getbyid
      summary: "Retrieve Card Owner Data"
      description: "Returns details of a specific card owner within the specified company."
      parameters:
        - name: cardOwnerId
          in: path
          required: true
          description: "Identifier of the card owner."
          example: "owner-12345"
          schema:
            type: string
            pattern: .+
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Card owner data."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardOwnerResponseCardOwnerDetailsResponse"
                type: object

    patch:
      tags:
        - Card owners
      operationId: patch_app_external_v1_cardissue_cardowner_cardowner_edit
      summary: "Update Card Owner"
      description: |
        Updates the specified card owner's details.

        :::info
        This request is asynchronous.  
        After receiving the `204` response, wait briefly and then call [Retrieve Card Owner Data](/docs/api-reference/get-app-external-v-1-cardissue-cardowner-cardowner-getbyid) to verify that the changes have been applied.
        :::
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company. "
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardOwnerId
          in: path
          required: true
          description: "Identifier of the card owner."
          example: "owner-12345"
          schema:
            type: string
            pattern: "[^/]+"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardOwnerRequestEditCardOwnerRequest"
      responses:
        "204":
          description: "Card owner update request accepted."

  /api/v1/cards/companies/{companyProviderUuid}/card-owners/{cardOwnerId}/kyc/document:
    put:
      tags:
        - Card owners
      operationId: put_app_external_v1_cardissue_cardowner_cardownerkyc_uploaddocument
      summary: "Upload Card Owner KYC Document"
      description: |
        Uploads a scan or photo of the card owner's identity document. Upload all document sides via this endpoint, then call [Submit Card Owner KYC](/docs/api-reference/patch-app-external-v-1-cardissue-cardowner-cardownerkyc-submit) to submit the KYC application.

        Each call uploads a single file. If the document has a back side, call this endpoint twice — once for each side, each call with a different `X-IDEMPOTENCY-KEY`.
      parameters:
        - name: X-IDEMPOTENCY-KEY
          in: header
          required: true
          description: "Unique key (UUID) that prevents the same document from being uploaded twice. Repeating a request with the same key returns `409 Conflict`."
          example: "b3d1f8e2-7c4a-4f9b-9d3e-2a1c5e7f8b9d"
          schema:
            type: string
            format: uuid
        - name: companyProviderUuid
          in: path
          required: true
          description: "Identifier of the provider company. Can be obtained from the `companyProviderId` field returned by [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details)."
          example: "1f01110f-e8b1-6188-80e5-52f68afc03c5"
          schema:
            type: string
            format: uuid
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardOwnerId
          in: path
          required: true
          description: "Identifier of the card owner."
          example: "owner-12345"
          schema:
            type: string
            pattern: .+
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              required:
                - data
                - file
              properties:
                data:
                  $ref: "#/components/schemas/V1CardIssueCardOwnerRequestKycUploadCardOwnerKycDocumentDataRequest"
                file:
                  type: string
                  format: binary
                  description: "Document file. Allowed formats: `JPEG`, `JPG`, `PNG`, `PDF`. Maximum size: 30 MB."
              type: object
      responses:
        "204":
          description: "Document uploaded."
        "409":
          description: "A document has already been uploaded for the supplied `X-IDEMPOTENCY-KEY`."

  /api/v1/cards/companies/{companyProviderUuid}/card-owners/{cardOwnerId}/kyc:
    patch:
      tags:
        - Card owners
      operationId: patch_app_external_v1_cardissue_cardowner_cardownerkyc_submit
      summary: "Submit Card Owner KYC"
      description: |
        Submits Know Your Customer (KYC) data for a card owner. Some card products require the card owner to pass KYC before a card can be issued.

        To complete KYC:

        1. Upload the identity document via [Upload Card Owner KYC Document](/docs/api-reference/put-app-external-v-1-cardissue-cardowner-cardownerkyc-uploaddocument).
        2. Submit the KYC data using this endpoint.

        The endpoint returns a unique `id` of the submitted KYC. Use it to look up the current KYC status in the `kyc` array returned by [Retrieve Card Owner Data](/docs/api-reference/get-app-external-v-1-cardissue-cardowner-cardowner-getbyid).
      parameters:
        - name: companyProviderUuid
          in: path
          required: true
          description: "Identifier of the provider company. Can be obtained from the `companyProviderId` field returned by [Retrieve Account Details](/docs/api-reference/get-app-external-v-1-cardissue-account-account-details)."
          example: "1f01110f-e8b1-6188-80e5-52f68afc03c5"
          schema:
            type: string
            format: uuid
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: cardOwnerId
          in: path
          required: true
          description: "Identifier of the card owner."
          example: "owner-12345"
          schema:
            type: string
            pattern: .+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycPayloadRequest"
      responses:
        "200":
          description: "KYC submission accepted."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueCardOwnerResponseKycSubmitResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/top-ups:
    post:
      tags:
        - TopUps
      operationId: post_app_external_v1_cardissue_topup_topups_init
      summary: "Initialize a New Top-Up"
      description: "Creates a new top-up transaction for a specified company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1CardIssueTopUpRequestInitTopUpRequest"
      responses:
        "200":
          description: "Returns the top-up identifier and a payment address."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueTopUpResponseTopUpInitResponse"
                type: object
    get:
      tags:
        - TopUps
      operationId: get_app_external_v1_cardissue_topup_topups_list
      summary: "Retrieve List of Top-Ups"
      description: "Returns a list of top-ups associated with a specified company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: page
          in: query
          required: false
          description: "Page number for paginated results. If not provided, all items are returned."
          example: 1
          schema:
            type: integer
            default: null
            minimum: 0
            exclusiveMinimum: true
            nullable: true
        - name: quantity
          in: query
          required: false
          description: "Number of items per page."
          example: 25
          schema:
            type: integer
            default: 25
            minimum: 0
            exclusiveMinimum: true
            nullable: true
      responses:
        "200":
          description: "Top-ups list."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/V1CardIssueTopUpResponseTopUpListItemResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object
  /api/v1/cards/companies/{companyUuid}/top-ups/{topUpUuid}:
    get:
      tags:
        - TopUps
      operationId: get_app_external_v1_cardissue_topup_topups_details
      summary: "Retrieve Top-Up Details"
      description: "Returns detailed information about a specific top-up."
      parameters:
        - name: topUpUuid
          in: path
          description: "Unique identifier of the top-up."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Information about the specified top-up."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueTopUpResponseTopUpInfoResponse"
                type: object
  /api/v1/cards/companies/{companyUuid}/cards/transactions:
    get:
      tags:
        - Transactions
      operationId: get_app_external_v1_cardissue_transaction_cardtransaction_list
      summary: "Retrieve Card Transactions"
      description: "Returns a list of card transactions associated with a specified company."
      parameters:
        - name: page
          in: query
          required: false
          description: "Page number for paginated results."
          schema:
            type: integer
            default: 1
        - name: quantity
          in: query
          required: false
          description: "Number of transactions per page."
          schema:
            type: integer
            default: 25
        - name: ids[]
          in: query
          required: false
          description: "Filter by specific transaction UUIDs."
          schema:
            type: array
            items:
              type: string
        - name: cardIds[]
          in: query
          required: false
          description: "Filter by one or more card UUIDs."
          schema:
            type: array
            items:
              type: string
        - name: accountIds[]
          in: query
          required: false
          description: "Filter by one or more account UUIDs."
          schema:
            type: array
            items:
              type: string
        - name: types[]
          in: query
          required: false
          description: "Filter by one or more transaction types."
          schema:
            type: array
            items:
              type: string
              enum:
                - purchase
                - refund
                - fee
                - top_up
                - withdrawal
        - name: statuses[]
          in: query
          required: false
          description: "Filter by one or more transaction status."
          schema:
            type: array
            items:
              type: string
              enum:
                - authorized
                - canceled
                - declined
                - completed
        - name: createdAtFrom
          in: query
          required: false
          description: "Filter transactions created at or after this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
        - name: createdAtTo
          in: query
          required: false
          description: "Filter transactions created at or before this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
        - name: sortType
          in: query
          required: false
          description: "Sorting direction. Defaults to 'desc' if not specified."
          schema:
            type: string
            enum:
              - desc
              - asc
        - name: sortBy
          in: query
          required: false
          description: "Field by which to sort results."
          schema:
            type: string
            enum:
              - createdAt
              - status
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "List of transactions."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: "Array of transactions."
                    items:
                      $ref: "#/components/schemas/V1CardIssueTransactionResponseCardTransactionListItemResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/cards/transactions/{transactionUuid}:
    get:
      tags:
        - Transactions
      operationId: get_app_external_v1_cardissue_transaction_cardtransaction_getdetails
      summary: "Retrieve Card Transaction Details"
      description: "Returns detailed information about a specific card transaction within a given company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: transactionUuid
          in: path
          required: true
          description: "Unique identifier of the transaction."
          example: "d413a9d7-6c7b-4f89-b47e-c742060a12c7"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Transaction Details."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueTransactionResponseCardTransactionDetailsResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/accounts/transactions:
    get:
      tags:
        - Transactions
      operationId: get_app_external_v1_cardissue_transaction_transaction_list
      summary: "Retrieve Account Transactions"
      description: "Returns a list of transactions related to all accounts under a specified company."
      parameters:
        - name: page
          in: query
          required: false
          description: "Page number for paginated results."
          schema:
            type: integer
            default: 1
        - name: quantity
          in: query
          required: false
          description: "Number of transactions per page."
          schema:
            type: integer
            default: 25
        - name: ids[]
          in: query
          required: false
          description: "Filter by one or more transaction UUIDs."
          schema:
            type: array
            items:
              type: string
        - name: types[]
          in: query
          required: false
          description: "Filter by one or more transaction types."
          schema:
            type: array
            items:
              type: string
              enum:
                - payin
                - card_issuing
                - transfer_fee
                - withdrawal
        - name: createdAtFrom
          in: query
          required: false
          description: "Filter transactions created at or after this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
        - name: createdAtTo
          in: query
          required: false
          description: "Filter transactions created at or before this date/time. In ISO 8601 format `YYYY-MM-DDThh:mm:ss.sssZ` (e.g., `2025-05-02T12:00:00.000Z`)."
          schema:
            type: string
        - name: statuses[]
          in: query
          required: false
          description: "Filter by one or more transaction status."
          schema:
            type: array
            items:
              type: string
              enum:
                - declined
                - completed
                - canceled
                - authorized
        - name: sortType
          in: query
          required: false
          schema:
            type: string
            description: "Sorting direction. Defaults to 'desc' if not specified."
            enum:
              - desc
              - asc
        - name: sortBy
          in: query
          required: false
          description: "Field by which to sort results."
          schema:
            type: string
            enum:
              - createdAt
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: accountIds[]
          in: query
          description: "Filter by one or more account UUIDs."
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: "List of transactions."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionListItemResponse"
                  pagination:
                    $ref: "#/components/schemas/ResponsePaginationResponse"
                type: object

  /api/v1/cards/companies/{companyUuid}/accounts/transactions/{transactionUuid}:
    get:
      tags:
        - Transactions
      operationId: get_app_external_v1_cardissue_transaction_transaction_getdetails
      summary: "Retrieve Account Transaction Details"
      description: "Returns detailed information about a specific account transaction, within a given company."
      parameters:
        - name: companyUuid
          in: path
          required: true
          description: "Unique identifier of the company."
          example: "123e4567-e89b-12d3-a456-426614174000"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
        - name: transactionUuid
          in: path
          required: true
          description: "Unique identifier of the transaction."
          example: "d413a9d7-6c7b-4f89-b47e-c742060a12c7"
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: "Transaction details."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1CardIssueTransactionResponseAccountTransactionHistoryDetailsResponse"
                type: object
components:
  schemas:
    V1CardIssueAccountRequestUpdateAccountRequest:
      title: V1-CardIssue-Account-Request-UpdateAccountRequest
      required:
        - name
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 40
          pattern: '^[A-Za-z0-9](?:[A-Za-z0-9 \-\(\)]*[A-Za-z0-9\)]$)?'
          description: |
            Name of the account.  

            **Requirements**:  

            - Must only contain Latin letters, digits, spaces, dashes, and parentheses.  
            - Must be 2 to 40 characters in length.  
            - Must begin with a Latin letter or digit.  
            - Must end with a Latin letter, digit, or closing parenthesis.
          example: "Account 1"
        fees:
          nullable: true
          description: |
            Object specifying custom fee settings for the account. 

            - By default, editing fees is not available. If you do not have access, please contact support to request it.
            - Any account-level fee (percentage or fixed) cannot be set lower than the corresponding company-level fee.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountRequestFeeList"
        accountBinDirections:
          type: array
          description: |
            Array of BIN configurations that define which BINs are available for card issuance within each category.  
            These settings will only affect cards issued after the account update; existing cards remain unchanged.
          items:
            $ref: "#/components/schemas/V1CardIssueCardBinRequestCategoryBins"
          nullable: true
      type: object
    V1CardIssueCardRequestCreateCardRequest:
      title: V1-CardIssue-Card-Request-CreateCardRequest
      description: Card settings.
      required:
        - name
        - cardOwnerId
        - cardType
        - limits
      properties:
        name:
          type: string
          description: "Card name or label as defined by the user."
          example: "Company Expenses Card"
        cardProviderBinId:
          type: string
          nullable: true
          description: |
            Identifier of the BIN used to issue the card.

            You can obtain this value from the `data -> binList -> cardProviderBinId`
            field returned by the [Retrieve Card Creation Restrictions](/docs/api-reference/get-app-external-v-1-cardissue-account-account-availablecardlimits) endpoint.
          example: "ff246e21-3bda-4e47-83fb-05203939fe5b"
        binCategoryId:
          type: string
          nullable: true
          description: |
            Identifier of the BIN category from which a BIN will be selected for card issuance.  
            Use this parameter to specify the intended use case (e.g., travel, corporate expenses) for the card.  
            You can obtain available category identifiers from the `data -> binList -> categoryIds` field returned by the [Retrieve Card Creation Restrictions](/docs/api-reference/get-app-external-v-1-cardissue-account-account-availablecardlimits) endpoint.
          example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
        cardOwnerId:
          type: string
          description: |
            Identifier of the card owner.  
            You can obtain this `cardOwnerId` by creating a card owner via the 
            [Create Card Owner](/docs/api-reference/post-app-external-v-1-cardissue-cardowner-cardowner-create) endpoint.  
            The same `cardOwnerId` can be reused to create multiple cards.
          example: "be7312c7-8f46-4519-8d90-2ca196d43ba8"
        cardType:
          type: string
          description: |
            Type of the card to be issued.

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).
            - **physical**: Indicates a physical plastic card.
          enum:
            - virtual
            - physical
        limits:
          type: object
          description: |
            An bject to configure spending limits for the card. 
            Keys must be one of the available limit types. Values must be strings representing the desired limit amount (e.g., '500.00'). 
            Each specified limit value must fall within the minimum (`amountMin`) and maximum (`amountMax`) range allowed for that specific limit type, as defined in the account's restrictions (see [Retrieve Card Creation Restrictions](/docs/api-reference/get-app-external-v-1-cardissue-account-account-availablecardlimits)).
          properties:
            daily_limit:
              description: "The maximum amount allowed per day."
              type: string
              example: "100.00"
              nullable: true
            weekly_limit:
              description: "The maximum amount allowed per week."
              type: string
              example: "200.00"
              nullable: true
            monthly_limit:
              description: "The maximum amount allowed per month."
              type: string
              example: "300.00"
              nullable: true
            year_limit:
              description: "The maximum amount allowed per year."
              type: string
              example: "1000.00"
              nullable: true
            lifetime_limit:
              description: "The maximum total amount allowed over the entire card lifetime."
              type: string
              example: "10000.00"
              nullable: true
            transaction_limit:
              description: "The maximum amount allowed for a single transaction."
              type: string
              example: "50.00"
              nullable: true
        currency:
          nullable: true
          $ref: "#/components/schemas/CurrencyAlpha3Type"
      type: object
    V1CardIssueCardRequestEditCardRequest:
      title: V1-CardIssue-Card-Request-EditCardRequest
      description: "Request body containing new card settings to update."
      properties:
        name:
          type: string
          nullable: true
          description: "New name for the card. Leave null if unchanged."
          example: "Business Travel Card"
        limits:
          type: object
          nullable: true
          description: |
            An bject to configure spending limits for the card. 
            Keys must be one of the available limit types. Values must be strings representing the desired limit amount (e.g., '500.00'). 
            Each specified limit value must fall within the minimum (`amountMin`) and maximum (`amountMax`) range allowed for that specific limit type, as defined in the account's restrictions (see [Retrieve Card Creation Restrictions](/docs/api-reference/get-app-external-v-1-cardissue-account-account-availablecardlimits)).
          properties:
            daily_limit:
              description: "The maximum amount allowed per day."
              type: string
              example: "100.00"
              nullable: true
            weekly_limit:
              description: "The maximum amount allowed per week."
              type: string
              example: "200.00"
              nullable: true
            monthly_limit:
              description: "The maximum amount allowed per month."
              type: string
              example: "300.00"
              nullable: true
            year_limit:
              description: "The maximum amount allowed per year."
              type: string
              example: "1000.00"
              nullable: true
            lifetime_limit:
              description: "The maximum total amount allowed over the entire card lifetime."
              type: string
              example: "10000.00"
              nullable: true
            transaction_limit:
              description: "The maximum amount allowed for a single transaction."
              type: string
              example: "50.00"
              nullable: true
      type: object
    CurrencyAlpha3Type:
      title: " "
      description: ISO 4217 currency code
      type: string
      maxLength: 3
      minLength: 3
      example: USD
    V1CardIssueTransactionResponseAccountTransactionHistoryDetailsResponse:
      title: V1-CardIssue-Transaction-Response-AccountTransactionHistoryDetailsResponse
      required:
        - id
        - account
        - amount
        - currency
        - feeCurrency
        - settlementAmount
        - settlementCurrency
        - status
        - createdAt
        - transactionDetails
      properties:
        id:
          type: string
          description: "Unique identifier of the transaction."
        account:
          description: "Details of the account associated with this transaction."
          allOf:
            - $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionDetailsAccountDetailsResponse"
        amount:
          type: string
          description: Transaction amount. Dot as delimiter.
          example: "150.00"
        currency:
          description: "Currency code. ISO 4217 currency code (3-letter format)."
          $ref: "#/components/schemas/CurrencyAlpha3Type"
        feeAmount:
          type: string
          description: "Total fee amount for the transaction. The delimiter is a dot, with two digits after the delimiter."
          nullable: true
        feeCurrency:
          description: "Currency of the fee amount. ISO 4217 currency code (3-letter format)."
          $ref: "#/components/schemas/CurrencyAlpha3Type"
        settlementAmount:
          type: string
          description: "Transaction amount in the settlement currency. The delimiter is a dot, with two digits after the delimiter."
        settlementCurrency:
          description: "Settlement currency code. ISO 4217 currency code (3-letter format)."
          $ref: "#/components/schemas/CurrencyAlpha3Type"
        description:
          type: string
          description: "Сomment or note regarding the transaction."
          nullable: true
        status:
          description: |
            Current processing status of the transaction.

            * **authorized** – The transaction request has been approved and funds are placed on hold.
            * **pending** – The transaction is being processed.  
            * **canceled** – The transaction was manually voided.  
            * **declined** – The transaction request was refused. No money was reserved or moved, so your account balance is unchanged.  
            * **completed** – The transaction cleared all processing steps and has now fully posted to your account. The amount is final and permanently reflected in your available balance.
          enum:
            - authorized
            - pending
            - canceled
            - declined
            - completed
          example: "authorized"
        createdAt:
          type: string
          description: "Date and time when the transaction was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        updatedAt:
          type: string
          description: "Date and time of the latest transaction update. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Null if never updated."
          example: "2025-06-02T15:38:49+00:00"
          nullable: true
        parentId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of a related parent transaction. For example, a refund transaction will reference the original purchase transaction it reverses."
          example: "63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b"
        transactionDetails:
          description: "Specific details related to this account transaction."
          $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionDetailsAccountTransactionResponse"
      type: object
    V1CardIssueCardOwnerRequestCreateCardOwnerRequest:
      title: V1-CardIssue-CardOwner-Request-CreateCardOwnerRequest
      description: "Request body for creating a new card owner."
      required:
        - cardOwnerId
        - firstName
        - lastName
        - email
      properties:
        cardOwnerId:
          type: string
          pattern: "[a-zA-Z0-9-]+, [a-zA-Z0-9-]+"
          description: "Unique ID of the card owner."
          example: "owner-12345"
        firstName:
          type: string
          description: "First name of the card owner."
          example: "John"
        lastName:
          type: string
          description: "Last name of the card owner."
          example: "Doe"
        email:
          type: string
          description: "Email address for the card owner. Must be unique."
          example: "john.doe@example.com"
        phone:
          type: string
          default: null
          description: "Phone number of the card owner. Must be unique within the company."
          example: "+1-202-555-0147"
          nullable: true
      type: object
    V1CardIssueCardOwnerRequestEditCardOwnerRequest:
      title: V1-CardIssue-CardOwner-Request-EditCardOwnerRequest
      description: "Request body for editing an existing card owner."
      properties:
        firstName:
          type: string
          nullable: true
          description: "Updated first name of the card owner."
          example: "Jane"
        lastName:
          type: string
          nullable: true
          description: "Updated last name of the card owner."
          example: "Smith"
        email:
          type: string
          format: email
          nullable: true
          description: "Updated email address of the card owner."
          example: "jane.smith@example.com"
        phone:
          type: string
          nullable: true
          description: "Updated phone number of the card owner."
          example: "+1-202-555-0199"
      type: object

    V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycPayloadRequest:
      title: V1-CardIssue-CardOwner-Request-Kyc-SubmitCardOwnerKycPayloadRequest
      description: "Request body for submitting card owner KYC data."
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycDataRequest"
      type: object

    V1CardIssueCardOwnerResponseKycSubmitResponse:
      title: V1-CardIssue-CardOwner-Response-KycSubmitResponse
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier of the submitted KYC."
          example: "fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d"
      type: object

    V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycDataRequest:
      title: V1-CardIssue-CardOwner-Request-Kyc-SubmitCardOwnerKycDataRequest
      required:
        - firstName
        - lastName
        - birthDate
        - occupation
        - nationality
        - email
        - phone
        - phonePrefix
        - document
        - address
        - gender
      properties:
        firstName:
          type: string
          description: "First name of the card owner."
          example: "John"
        lastName:
          type: string
          description: "Last name of the card owner."
          example: "Doe"
        birthDate:
          type: string
          format: date
          description: "Date of birth. ISO 8601 date format `YYYY-MM-DD`."
          example: "1990-05-21"
        occupation:
          $ref: "#/components/schemas/CardIssueEnumCardOwnerKycCardOwnerKycOccupation"
        nationality:
          type: string
          description: "Nationality of the card owner. ISO 3166-1 alpha-2 country code."
          example: "US"
        email:
          type: string
          format: email
          description: "Email address of the card owner."
          example: "john.doe@example.com"
        phone:
          type: string
          description: "Phone number of the card owner."
          example: "2025550147"
        phonePrefix:
          type: string
          description: "Country calling code of the phone number, without the leading `+`."
          example: "1"
        document:
          $ref: "#/components/schemas/V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycDocumentRequest"
        address:
          $ref: "#/components/schemas/V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycAddressRequest"
        gender:
          $ref: "#/components/schemas/CardIssueEnumCardOwnerKycCardOwnerKycGender"
      type: object

    V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycDocumentRequest:
      title: V1-CardIssue-CardOwner-Request-Kyc-SubmitCardOwnerKycDocumentRequest
      description: "Identity document of the card owner."
      required:
        - type
        - number
        - expiryDate
      properties:
        type:
          $ref: "#/components/schemas/CardIssueEnumCardOwnerKycCardOwnerKycDocumentType"
        number:
          type: string
          description: "Document number."
          example: "X1234567"
        expiryDate:
          type: string
          format: date
          description: "Expiry date of the document. ISO 8601 date format `YYYY-MM-DD`."
          example: "2030-12-31"
      type: object

    V1CardIssueCardOwnerRequestKycSubmitCardOwnerKycAddressRequest:
      title: V1-CardIssue-CardOwner-Request-Kyc-SubmitCardOwnerKycAddressRequest
      description: "Residential address of the card owner."
      required:
        - country
        - state
        - city
        - district
        - address
        - postalCode
      properties:
        country:
          type: string
          description: "Country. ISO 3166-1 alpha-2 country code."
          example: "US"
        state:
          type: string
          description: "State or region."
          example: "California"
        city:
          type: string
          description: "City."
          example: "Los Angeles"
        district:
          type: string
          description: "District."
          example: "Downtown"
        address:
          type: string
          description: "Street address (street, building, apartment)."
          example: "350 S Grand Ave, Apt 12"
        postalCode:
          type: string
          description: "Postal or ZIP code."
          example: "90071"
      type: object

    V1CardIssueCardOwnerRequestKycUploadCardOwnerKycDocumentDataRequest:
      title: V1-CardIssue-CardOwner-Request-Kyc-UploadCardOwnerKycDocumentDataRequest
      description: "Metadata describing the uploaded document image."
      properties:
        documentSide:
          $ref: "#/components/schemas/CardIssueEnumCardOwnerKycCardOwnerKycDocumentSide"
          nullable: true
          description: "Side of the document captured in the file. The `FRONT` side is required; if the document has a `BACK` side, it must be uploaded as well."
      type: object

    CardIssueEnumCardOwnerKycCardOwnerKycOccupation:
      title: " "
      type: string
      description: "Occupation of the card owner."
      enum:
        - GOVERNMENT_OFFICERS
        - GOVERNMENT_WORKERS
        - SOE_AND_STATE_ORGAN_EXECUTIVES
        - SOE_AND_STATE_ORGAN_EMPLOYEES
        - PRIVATE_BUSINESS_OWNERS_AND_EXECUTIVES
        - PRIVATE_BUSINESS_EMPLOYEES
        - NONE_GOVERNMENT_ORGANIZATION_EXECUTIVES
        - NONE_GOVERNMENT_ORGANIZATION_EMPLOYEES
        - SOLE_TRADERS
        - RETIREES
        - STUDENTS
        - UNEMPLOYED
        - FREELANCER
      example: "PRIVATE_BUSINESS_EMPLOYEES"

    CardIssueEnumCardOwnerKycCardOwnerKycGender:
      title: " "
      type: string
      description: "Gender of the card owner."
      enum:
        - MALE
        - FEMALE
      example: "MALE"

    CardIssueEnumCardOwnerKycCardOwnerKycDocumentType:
      title: " "
      type: string
      description: "Type of the identity document."
      enum:
        - PASSPORT
        - ID_CARD
      example: "PASSPORT"

    CardIssueEnumCardOwnerKycCardOwnerKycDocumentSide:
      title: " "
      type: string
      description: "Side of the document image."
      enum:
        - FRONT
        - BACK
      example: "FRONT"

    V1CardIssueCardResponseCardTopUpResponse:
      title: V1-CardIssue-Card-Response-CardTopUpResponse
      required:
        - fromTransactionId
        - toTransactionId
      properties:
        fromTransactionId:
          type: string
          description: "Unique identifier of the transaction from which the funds were transferred."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
        toTransactionId:
          type: string
          description: "Unique identifier of the transaction to which the funds were transferred."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
      type: object

    V1CardIssueTopUpRequestInitTopUpRequest:
      title: V1-CardIssue-TopUp-Request-InitTopUpRequest
      required:
        - currency
      properties:
        currency:
          type: string
          description: |
            Cryptocurrency code for the top-up.
            Supported values are:  
            - **USDCTRC20** – USDC on the TRON network  
            - **USDTTRC20** – USDT on the TRON network
          example: "USDTTRC20"
          enum:
            - USDCTRC20
            - USDTTRC20
        accountId:
          type: string
          description: |
            Optional identifier of the account to credit.  
            If provided, the funds will be credited directly to this account.  
            If omitted, the funds will be added to the company's main balance (companyUuid), and you will need to allocate them manually via the dashboard.
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
          default: null
          nullable: true
      type: object
    V1CardIssueCardBinResponseCardBinCategoryWithBinDetailsResponse:
      title: V1-CardIssue-CardBin-Response-CardBinCategoryWithBinDetailsResponse
      description: "Information about a BIN category and its associated BINs."
      required:
        - id
        - type
        - name
        - description
        - bins
      properties:
        id:
          type: string
          description: "Unique identifier of the BIN category."
          example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
        type:
          type: string
          description: "Type or classification of the BIN category that defines its intended use case."
          example: "travel"
        name:
          type: string
          description: "Display name of the BIN category."
          example: "Travel Cards"
        description:
          type: string
          description: "Detailed description of the BIN category and its intended purpose."
          example: "BINs optimized for online purchases, booking."
        bins:
          type: array
          description: "Array of BIN configurations available within this category."
          items:
            $ref: "#/components/schemas/V1CardIssueCardBinResponseCardBinResponse"
      type: object
    V1CardIssueCardBinResponseCardBinResponse:
      title: V1-CardIssue-CardBin-Response-CardBinResponse
      description: "Detailed information about a specific BIN configuration."
      required:
        - cardProviderBinId
        - country
        - tokenizations
        - cardNetwork
        - tags
        - bin
        - isEnable
      properties:
        cardProviderBinId:
          type: string
          description: |
            Unique identifier of this BIN configuration.  
            Use this value when configuring account BIN restrictions or creating cards.
          example: "ff246e21-3bda-4e47-83fb-05203939fe5b"
        country:
          description: |
            Country in which the BIN is registered.  
            ISO 3166-1 alpha-2 country code.
          type: string
          maxLength: 2
          minLength: 2
          example: "CN"
        tokenizations:
          type: array
          description: |
            Digital wallet tokenization schemes supported for cards issued from this BIN.  
            Can be empty if no digital-wallet tokenization is available.
          items:
            type: string
            enum:
              - Apple pay
              - Google pay
        cardNetwork:
          description: "Payment network through which card transactions are processed."
          $ref: "#/components/schemas/CardIssueEnumCardCardNetwork"
        tags:
          type: array
          description: "Tags associated with the BIN configuration for categorization, identification, and feature indication purposes (e.g., 3DS requirements, digital wallet support, use case optimization)."
          items:
            type: string
        bin:
          type: string
          description: |
            First 6 – 8 digits of the payment card number (BIN) that identifies the issuer and product.
          example: "411111"
        isEnable:
          type: boolean
          description: |
            Indicates whether this BIN is currently available for card issuance.  
            If `true`, the BIN can be used to issue new cards. If `false`, the BIN is disabled.
          example: true
      type: object
    V1CardIssueAccountResponseCompanyAccountResponse:
      title: V1-CardIssue-Account-Response-CompanyAccountResponse
      required:
        - id
        - allowedCardTypes
        - cards
        - currency
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: "Unique identifier of the account."
          example: "8f3d0c3d-9f3e-4ef6-8fae-c3169025dfcb"
        name:
          type: string
          description: "Name of the account."
          example: "My travel card"
          nullable: true
        balance:
          type: string
          description: "Current balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          example: "1000.00"
          nullable: true
        undistributedBalance:
          type: string
          description: "Current undistributed balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          nullable: true
          example: "100.00"
        holdedBalance:
          type: string
          description: "Current holded balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          nullable: true
          example: "100.00"
        allowedCardTypes:
          type: array
          description: |
            Allowed card types for the account.  

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).  
            - **physical**: Indicates a physical plastic card.
          items:
            type: string
            enum:
              - virtual
              - physical
        cards:
          type: integer
          description: "The number of cards created for this account."
          example: 5
        currency:
          description: "The currency for this account. ISO 4217 currency code (3-letter format)."
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        status:
          $ref: "#/components/schemas/V1CardIssueAccountEnumAccountStatus"
        createdAt:
          type: string
          description: "Date and time when the account was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        updatedAt:
          type: string
          description: "Date and time of the latest account update. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        deletedAt:
          type: string
          description: "Date and time when the account was deleted. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Or null if active."
          nullable: true
          example: "2025-06-02T15:38:49+00:00"
      type: object
    ResponsePaginationResponse:
      title: Http-Response-PaginationResponse
      required:
        - quantity
        - totalQuantity
        - currentPage
        - pages
      properties:
        quantity:
          type: integer
          description: "Number of records returned in the current page."
          example: 25
        totalQuantity:
          type: integer
          description: "Total number of records available."
          example: 100
        currentPage:
          type: integer
          description: "Current page number."
          example: 2
        pages:
          type: integer
          description: "Total number of pages available based on 'quantity' and 'totalQuantity'."
          example: 4
      type: object
    V1CardIssueAccountResponseAccountResponse:
      title: V1-CardIssue-Account-Response-AccountResponse
      required:
        - id
        - name
        - isUsedCardBalance
        - allowedCardTypes
        - cards
        - currency
        - status
        - createdAt
        - updatedAt
        - fees
        - isTransferAllowed
        - companyProviderId
        - binList
      properties:
        id:
          type: string
          description: "Unique identifier of the account."
          example: "8f3d0c3d-9f3e-4ef6-8fae-c3169025dfcb"
        name:
          type: string
          description: "Name of the account."
          example: "Default"
        balance:
          type: string
          nullable: true
          description: "Current balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          example: "1000.00"
        holdedBalance:
          type: string
          nullable: true
          description: "Current holded balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        availableBalance:
          type: string
          nullable: true
          description: "Current available balance of the account in a string format. The delimiter is a dot, with two digits after the delimiter."
          example: "900.00"
        isUsedCardBalance:
          type: boolean
          description: |
            Indicates whether the account supports using a dedicated card balance.
            If `true`, cards issued under this account will have their own balance, separate from the main account balance.
            If `false`, all card transactions are settled directly from the account balance.
          example: true
        allowedCardTypes:
          type: array
          description: |
            Allowed card types for the account.

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).  
            - **physical**: Indicates a physical plastic card.
          items:
            type: string
            enum:
              - virtual
              - physical
        cards:
          type: integer
          description: "The number of cards created for this account."
          example: 5
        currency:
          description: "ISO 4217 currency code (3-letter format)."
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        status:
          $ref: "#/components/schemas/V1CardIssueAccountEnumAccountStatus"
        companyProviderId:
          type: string
          format: uuid
          description: "Identifier of the provider that this account is linked to."
          example: "1f01110f-e8b1-6188-80e5-52f68afc03c5"
        createdAt:
          type: string
          description: "Date and time when the account was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        updatedAt:
          type: string
          description: "Date and time of the latest account update. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        fees:
          $ref: "#/components/schemas/V1CardIssueAccountResponseFeeListResponse"
          description: |
            Object specifying custom fee settings for the account.
        isTransferAllowed:
          type: boolean
          description: |
            Indicates whether balance transfers are allowed for this account.
            If `true`, funds can be transferred from this account to other accounts via [Transfer Account Balance](/docs/api-reference/post-app-external-v-1-cardissue-account-account-transferbalance).
            If `false`, balance transfers from this account are not permitted.
          example: true
        deletedAt:
          type: string
          nullable: true
          description: "Date and time when the account was deleted. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Or null if active."
          example: "2025-06-02T15:38:49+00:00"
        binList:
          type: array
          description: "List of available BIN configurations for card issuance. Can be empty."
          items:
            $ref: "#/components/schemas/V1CardIssueAccountResponseCardBinResponse"
        accountOwnerId:
          type: string
          format: uuid
          nullable: true
          description: "Unique identifier of the account owner."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
      type: object
    V1CardIssueAccountResponseFeeListResponse:
      title: V1-CardIssue-Account-Response-FeeListResponse
      properties:
        cardTransactions:
          nullable: true
          description: |
            Fee settings for card transactions.  
            Can be specified as a percentage of the transaction amount or as a fixed amount per transaction.
          oneOf:
            - $ref: "#/components/schemas/V1CardIssueAccountResponseFeeAccountAmountFee"
            - $ref: "#/components/schemas/V1CardIssueAccountResponseFeePercentFee"
        cardIssuing:
          nullable: true
          description: |
            Fee applied for issuing a new card.  
            Can be specified as a fixed amount.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountResponseFeeAccountAmountFee"
        topUpsAllocation:
          nullable: true
          description: |
            Fee applied when allocating top-up funds to the account.  
            Can be specified as a percentage of the top-up amount.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountResponseFeePercentFee"
      type: object
    V1CardIssueAccountResponseFeeAccountAmountFee:
      title: Fixed Fee
      required:
        - type
        - amount
        - currency
        - inherited
      properties:
        type:
          type: string
          enum:
            - amount
          description: |
            Indicates that the fee is specified as a fixed amount.
          example: amount
        amount:
          type: string
          description: |
            Fixed fee amount applied.  
            Expressed as a string. Dot as delimiter.
          example: "2.50"
        currency:
          type: string
          maxLength: 3
          minLength: 3
          description: |
            Currency code for the fee amount.
            ISO 4217 currency code (3-letter format).
          example: USD
        inherited:
          type: boolean
          description: |
            If true, the fee for this account is not customized and is equal to the company-level fee.
          example: true
      type: object
    V1CardIssueAccountResponseFeePercentFee:
      title: Percent Fee
      required:
        - type
        - percent
        - inherited
      properties:
        type:
          type: string
          enum:
            - percent
          description: |
            Indicates that the fee is specified as a percentage.
          example: percent
        percent:
          type: string
          description: |
            Percentage value of the fee applied.  
            Expressed as a string representing the percent (e.g., "15" for 15%). Dot as delimiter.
          example: "15"
        inherited:
          type: boolean
          description: |
            If true, the fee for this account is not customized and is equal to the company-level fee.
          example: true
      type: object
    V1CardIssueAccountResponseCardBinResponse:
      title: " "
      description: Information about a BIN (Bank Identification Number) configuration that can be used by the account when issuing cards.
      required:
        - cardTokenizations
        - cardProviderBinId
        - tags
        - categoryIds
      properties:
        bin:
          type: string
          description: |
            First 6 – 8 digits of the payment card number (BIN) that identifies the issuer and product.
          example: "411111"
          nullable: true
        cardNetwork:
          nullable: true
          description: |
            Payment network through which card transactions are processed.
          $ref: "#/components/schemas/CardIssueEnumCardCardNetwork"
        issuerCountry:
          type: string
          nullable: true
          description: |
            Country in which the BIN is registered.  
            ISO 3166-1 alpha-2 code.
          example: "US"
        cardTokenizations:
          type: array
          description: |
            Tokenisation schemes supported for cards issued from this BIN.  
            Can be empty if no digital-wallet tokenisation is available.
          items:
            type: string
            enum:
              - Apple pay
              - Google pay
        cardProviderBinId:
          type: string
          description: |
            Unique identifier of this BIN configuration.  
            Pass this value when calling **[Issue a New Card](/docs/api-reference/post-app-external-v-1-cardissue-card-card-create)**.
          example: "ff246e21-3bda-4e47-83fb-05203939fe5b"
        tags:
          type: array
          description: |
            Tags associated with the BIN configuration.
          items:
            type: string
            example: "travel"
        categoryIds:
          type: array
          description: |
            Identifiers of BIN categories that define the intended use case or purpose of the BIN.  
            For example, categories may include travel, corporate expenses, or other specific use cases.
          items:
            type: string
            example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      type: object
    V1CardIssueAccountResponseAccountRestrictionsResponse:
      title: V1-CardIssue-Account-Response-AccountRestrictionsResponse
      required:
        - limits
        - binList
        - cardBalance
      properties:
        limits:
          type: array
          description: "Array of objects representing available limit configurations for card creation."
          items:
            $ref: "#/components/schemas/V1CardIssueAccountResponseLimitPeriodTypeResponse"
        binList:
          type: array
          description: "Array of objects representing available BIN configurations."
          items:
            $ref: "#/components/schemas/V1CardIssueAccountResponseCardBinResponse"
        cardBalance:
          type: boolean
          description: |
            Indicates whether this provider supports using a dedicated card balance.
            If `true`, cards issued under this account will have their own balance, separate from the main account balance.  
            If `false`, all card transactions are settled directly from the account balance.
          example: true

      type: object
    V1CardIssueCardResponseGetCardResponse:
      title: V1-CardIssue-Card-Response-GetCardResponse
      required:
        - cardId
        - name
        - currency
      properties:
        cardId:
          type: string
          description: "Unique identifier of the card."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
        name:
          type: string
          description: "Name of the card."
          example: "My Travel Card"
        currency:
          type: string
          description: "Currency of the card in ISO 4217 currency code (3-letter format)."
          maxLength: 3
          minLength: 3
          example: USD
        availableBalance:
          type: string
          description: "Available balance of the card in a string format. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        holder:
          type: string
          nullable: true
          description: "Name of the cardholder."
          example: "John Doe"
        cardType:
          type: string
          description: |
            Type of the card.

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).  
            - **physical**: Indicates a physical plastic card.
          enum:
            - virtual
            - physical
          nullable: true
        maskedNumber:
          type: string
          nullable: true
          description: "Masked card number (e.g., 1234******5678)."
          example: "4111******1111"
        paymentSystem:
          type: string
          example: "Visa"
          nullable: true
          description: "Payment system of the card."
          allOf:
            - $ref: "#/components/schemas/CardIssueEnumCardCardNetwork"
        expiredAt:
          type: string
          example: "10.2024"
          description: "Expiration date of the card in MM.YYYY format."
          nullable: true
        cardStatus:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/V1CardIssueCardEnumCardStatus"
      type: object
    V1CardIssueCardEnumCardStatus:
      title: " "
      type: string
      description: |
        Possible statuses for a card:

        * **creating** – The card-issuance request has been accepted and is still being processed; the card is not yet usable.
        * **creating_failed** – The attempt to issue the card has failed; no valid card was created.
        * **active** – The card has been successfully issued and is fully usable for transactions.
        * **frozen** – The card has been temporarily frozen as the result of calling the **[Freeze Card](/docs/api-reference/post-app-external-v-1-cardissue-card-card-freeze)** endpoint; all transactions are declined until the card is [re-activated](/docs/api-reference/post-app-external-v-1-cardissue-card-card-activate).
        * **expired** – The card's expiration date has passed and it can no longer be used.
        * **blocked** – The card has been permanently closed/blocked as the result of calling the **[Close Card](/docs/api-reference/post-app-external-v-1-cardissue-card-card-close)** endpoint; this action is irreversible and the card cannot be reactivated.
      enum:
        - creating
        - creating_failed
        - active
        - frozen
        - expired
        - blocked
    V1CardIssueCardResponseCreateCardResponse:
      title: V1-CardIssue-Card-Response-CreateCardResponse
      description: "Response body containing the identifier of the newly issued card."
      required:
        - id
      properties:
        id:
          type: string
          description: "Unique identifier of the issued card."
          example: "fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d"
      type: object
    V1CardIssueCardResponseGetCardDetailsResponse:
      title: V1-CardIssue-Card-Response-GetCardDetailsResponse
      required:
        - account
        - card
      properties:
        account:
          $ref: "#/components/schemas/V1CardIssueCardResponseDetailsCardAccountDetailsResponse"
        card:
          $ref: "#/components/schemas/V1CardIssueCardResponseDetailsCardDetailsResponse"
      type: object
    V1CardIssueCardResponseDetailsGetCardSensitiveResponse:
      title: V1-CardIssue-Card-Response-Details-GetCardSensitiveResponse
      required:
        - cardNumber
        - cvv
        - expiryMonth
        - expiryYear
      properties:
        cardNumber:
          type: string
          description: "Full, unmasked card number."
          example: "4111111111111111"
        cvv:
          type: string
          description: "CVV code of the card."
          example: "123"
        expiryMonth:
          type: string
          description: "Expiration month of the card (MM)."
          example: "10"
        expiryYear:
          type: string
          description: "Expiration year of the card (YYYY)."
          example: "2024"
        cardHolder:
          type: string
          description: "Name of the card holder."
          example: "JOHN DOE"
          nullable: true
      type: object
    V1CardIssueCardResponseDetailsCardOwnerResponse:
      title: V1-CardIssue-Card-Response-Details-CardOwnerResponse
      required:
        - firstName
        - lastName
        - email
      properties:
        cardOwnerId:
          type: string
          description: "Identifier for the card owner."
          example: "merch123"
          nullable: true
        firstName:
          type: string
          description: "First name of the card owner."
          example: "John"
        lastName:
          type: string
          description: "Last name of the card owner."
          example: "Doe"
        email:
          type: string
          description: "Email address of the card owner."
          example: "john.doe@example.com"
        phone:
          type: string
          nullable: true
          description: "Phone number of the card owner."
          example: "+1-202-555-0147"
        address:
          description: "Address of the card owner."
          nullable: true
          allOf:
            - "$ref": "#/components/schemas/V1CardIssueCardResponseDetailsCardOwnerAddressResponse"
      type: object
    V1CardIssueCardOwnerResponseCardOwnerDetailsResponse:
      title: V1-CardIssue-CardOwner-Response-CardOwnerDetailsResponse
      required:
        - firstName
        - lastName
        - email
        - kyc
      properties:
        cardOwnerId:
          type: string
          description: "Identifier for the card owner."
          example: "merch123"
          nullable: true
        firstName:
          type: string
          description: "First name of the card owner."
          example: "John"
        lastName:
          type: string
          description: "Last name of the card owner."
          example: "Doe"
        email:
          type: string
          description: "Email address of the card owner."
          example: "john.doe@example.com"
        phone:
          type: string
          nullable: true
          description: "Phone number of the card owner."
          example: "+1-202-555-0147"
        kyc:
          type: array
          default: []
          description: "History of KYC submissions for this card owner. Empty if none have been submitted."
          items:
            $ref: "#/components/schemas/V1CardIssueCardOwnerResponseCardOwnerKycResponse"
        address:
          description: "Address of the card owner."
          nullable: true
          allOf:
            - "$ref": "#/components/schemas/V1CardIssueCardResponseDetailsCardOwnerAddressResponse"
      type: object
    V1CardIssueCardOwnerResponseCardOwnerKycResponse:
      title: V1-CardIssue-CardOwner-Response-CardOwnerKycResponse
      description: "KYC submission record for a card owner."
      required:
        - kycId
        - status
      properties:
        kycId:
          type: string
          format: uuid
          description: "Unique identifier of the KYC submission. Returned by [Submit Card Owner KYC](/docs/api-reference/patch-app-external-v-1-cardissue-cardowner-cardownerkyc-submit)."
          example: "fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d"
        status:
          $ref: "#/components/schemas/CardIssueEnumCardOwnerKycCardOwnerKycStatus"
      type: object
    CardIssueEnumCardOwnerKycCardOwnerKycStatus:
      title: " "
      type: string
      description: |
        Processing status of a KYC submission:

        * **created** – The KYC submission has been received and is queued for processing.
        * **approved** – The KYC submission has been reviewed and accepted.
        * **denied** – The KYC submission has been reviewed and rejected.
      enum:
        - created
        - approved
        - denied
      example: "approved"
    V1CardIssueCardResponseDetailsCardOwnerAddressResponse:
      title: V1-CardIssue-Card-Response-Details-CardOwnerAddressResponse
      description: "Address details of the card owner."
      required:
        - postalCode
        - city
        - addressLine1
      properties:
        postalCode:
          type: string
          description: "Postal or ZIP code."
          example: "10001"
        city:
          type: string
          description: "City name."
          example: "New York"
        addressLine1:
          type: string
          description: "Primary street address."
          example: "123 Main Street"
        addressLine2:
          type: string
          description: "Secondary address line (apartment, suite, unit, etc.)."
          example: "Apt 4B"
          nullable: true
      type: object
    V1CardIssueCardOwnerResponseCreateCardOwnerResponse:
      title: V1-CardIssue-CardOwner-Response-CreateCardOwnerResponse
      description: "Response body for the newly created card owner."
      required:
        - firstName
        - lastName
        - email
      properties:
        cardOwnerId:
          type: string
          nullable: true
          description: "Unique ID of the card owner."
          example: "owner-12345"
        firstName:
          type: string
          description: "First name of the card owner."
          example: "John"
        lastName:
          type: string
          description: "Last name of the card owner."
          example: "Doe"
        email:
          type: string
          format: email
          description: "Email address of the card owner."
          example: "john.doe@example.com"
        phone:
          type: string
          default: null
          nullable: true
          description: "Phone number of the card owner."
          example: "+1-202-555-0147"
        address:
          description: "Address of the card owner."
          nullable: true
          allOf:
            - "$ref": "#/components/schemas/V1CardIssueCardResponseDetailsCardOwnerAddressResponse"
      type: object
    V1CardIssueTopUpResponseTopUpListItemResponse:
      title: V1-CardIssue-TopUp-Response-TopUpListItemResponse
      required:
        - id
        - status
        - currency
        - amount
        - settlementCurrency
        - settlementAmount
        - createdAt
      properties:
        id:
          type: string
          description: "Unique identifier of the top-up."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
        status:
          $ref: "#/components/schemas/V1CardIssueTopUpStatus"
        currency:
          type: string
          description: "Currency of the top-up transaction."
          example: "USDTTRC20"
          enum:
            - USDCTRC20
            - USDTTRC20
        amount:
          type: string
          description: "Total amount of the transaction in the top-up currency. The delimiter is a dot."
          example: "100.00"
        settlementCurrency:
          type: string
          maxLength: 3
          minLength: 3
          description: "Сurrency in which the funds will actually be credited to your account. ISO 4217 currency code (3-letter format)."
          example: "USD"
        settlementAmount:
          type: string
          description: "Exact amount that will be credited, expressed in the settlement currency. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        createdAt:
          type: string
          description: "Date and time when the top-up was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
      type: object
    V1CardIssueTopUpStatus:
      title: " "
      type: string
      description: |
        Status for a top-up in its lifecycle.

        - **created** – The top-up request has been opened and is awaiting payment from the payer.
        - **in_progress** – Payment is expected; funds have not yet reached our platform.
        - **readyForAllocation** – Funds have arrived and need to be split among the target account(s).
        - **allocating** – Funds are being allocated to the target account(s).
        - **readyForTransfer** – Allocation is complete; the transfer job has been queued and will begin shortly.
        - **transfering** – Money is currently being moved to the account.
        - **completed** – The full amount was successfully credited to all destination accounts.
        - **refunded** – The entire top-up amount was returned to the payer.
        - **failed** – Payment was not made or a critical error occurred during processing.
      enum:
        - created
        - in_progress
        - readyForAllocation
        - allocating
        - readyForTransfer
        - transfering
        - completed
        - refunded
        - failed
      example: "in_progress"
    V1CardIssueTopUpResponseTopUpInitResponse:
      title: V1-CardIssue-TopUp-Response-TopUpInitResponse
      required:
        - id
        - paymentAddress
      properties:
        id:
          type: string
          description: "Unique identifier of the top-up."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
        paymentAddress:
          type: string
          description: "Payment wallet address where the deposit must be sent."
          example: "0xAbCdEf1234567890abcdef1234567890AbCdEf12"
      type: object
    V1CardIssueTopUpResponseTopUpInfoResponse:
      title: V1-CardIssue-TopUp-Response-TopUpInfoResponse
      required:
        - id
        - status
        - currency
        - amount
        - settlementCurrency
        - settlementAmount
        - createdAt
      properties:
        id:
          type: string
          description: "Unique identifier of the top-up."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
        paymentAddress:
          type: string
          nullable: true
          description: |
            Wallet address for depositing funds.
          example: "0xAbCdEf1234567890abcdef1234567890AbCdEf12"
        status:
          $ref: "#/components/schemas/V1CardIssueTopUpStatus"
        currency:
          type: string
          description: "Cryptocurrency used for the top-up."
          example: "USDTTRC20"
          enum:
            - USDCTRC20
            - USDTTRC20
        amount:
          type: string
          description: "Total amount of the transaction in the top-up currency."
          example: "105.10"
        feeCurrency:
          type: string
          nullable: true
          description: "Currency of the fee."
          example: "USDT"
          enum:
            - USDTTRC20
            - USDCTRC20
        feeAmount:
          type: string
          description: "Total fee amount across all transactions related to the top-up."
          example: "2.50"
          nullable: true
        settlementCurrency:
          type: string
          maxLength: 3
          minLength: 3
          description: "Сurrency in which the funds will actually be credited to your account. ISO 4217 currency code (3-letter format)."
          example: "USD"
        settlementAmount:
          type: string
          description: "Exact amount that will be credited, expressed in the settlement currency. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        txHash:
          type: string
          nullable: true
          description: "Blockchain transaction hash of the deposit."
          example: "f42b89e65d80bdc1801cbb1906e620f2bb2d4c2275936627a1b2f8a9bd6f5e3c"
        createdAt:
          type: string
          description: "Date and time when the top-up was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
      type: object
    V1CardIssueTransactionResponseCardTransactionListItemResponse:
      title: V1-CardIssue-Transaction-Response-CardTransactionListItemResponse
      description: Information about a single card transaction.
      required:
        - id
        - cardId
        - accountId
        - amount
        - currency
        - feeCurrency
        - settlementAmount
        - settlementCurrency
        - status
        - type
        - createdAt
        - declineReason
      properties:
        id:
          type: string
          description: Unique identifier of the transaction.
          example: 63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b
        cardId:
          type: string
          description: Unique identifier of the card that initiated the transaction.
          example: abc123e4-5678-90ab-cdef-1234567890ab
        accountId:
          type: string
          description: Unique identifier of the account that owns the card.
          example: 9f283e59-21ec-4c74-ae32-156d49cd9cf2
        amount:
          type: string
          description: "Transaction amount in the merchant's currency (`currency`). The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        currency:
          type: string
          description: "Source currency code. ISO 4217 currency code (3-letter format)."
          example: "USD"
        feeAmount:
          type: string
          description: "Fee amount charged for the transaction in the account currency (`feeCurrency`). The delimiter is a dot, with two digits after the delimiter."
          example: "2.50"
          nullable: true
        feeCurrency:
          type: string
          description: "Currency of the fee amount. ISO 4217 currency code (3-letter format)."
          example: "USD"
        settlementAmount:
          type: string
          description: "Transaction amount converted to the account currency (`settlementCurrency`), excluding fees. The delimiter is a dot, with two digits after the delimiter."
          example: "150.00"
        settlementCurrency:
          allOf:
            - $ref: "#/components/schemas/CurrencyAlpha3Type"
            - type: string
              description: "Settlement currency code. ISO 4217 currency code (3-letter format)."
        status:
          $ref: "#/components/schemas/V1CardIssueTransactionEnumTransactionStatus"
        type:
          $ref: "#/components/schemas/V1CardIssueTransactionEnumCardTransactionType"
        createdAt:
          type: string
          description: "Date and time when the transaction was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        merchantName:
          type: string
          nullable: true
          description: "Name of the merchant or entity involved in this transaction."
          example: "John Doe Shop"
        merchantCountry:
          type: string
          nullable: true
          description: "Country of the merchant or entity involved in this transaction."
          example: "US"
        rrn:
          type: string
          nullable: true
          description: "Retrieval Reference Number assigned by the processor."
          example: "123456789012"
        authorizationCode:
          type: string
          nullable: true
          description: "Code indicating approval of the transaction."
          example: "AUTH1234"
        authorizedBy:
          nullable: true
          description: "Indicates the entity that authorized the transaction."
          allOf:
            - $ref: "#/components/schemas/CardIssueEnumBalanceAuthorizedByType"
        declineReason:
          type: string
          description: "Reason for transaction decline."
          example: "Insufficient funds"
        mcc:
          type: string
          nullable: true
          description: "Merchant Category Code."
          example: "5999"
        transactionAt:
          type: string
          description: "Date and time when the transaction actually occurred. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
          nullable: true
        parentId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of a related parent transaction. For example, a refund transaction will reference the original purchase transaction it reverses."
          example: "63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b"
        transferJobId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of the job associated with this transaction."
          example: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
      type: object
    V1CardIssueTransactionEnumCardTransactionType:
      title: " "
      type: string
      description: |
        Category that describes the nature of a card transaction:

         * **purchase** – Outgoing payment for goods or services made by the cardholder.
         * **refund** – Inbound credit that reverses all or part of a previous purchase.
         * **fee** – Charge applied.
         * **top_up** – Funds added to the card balance.
         * **withdrawal** – Funds withdrawn from the card balance.
      enum:
        - purchase
        - refund
        - fee
        - top_up
        - withdrawal
    V1CardIssueTransactionResponseTransactionListItemResponse:
      title: V1-CardIssue-Transaction-Response-TransactionListItemResponse
      description: Summary information about a single account-level transaction.
      required:
        - id
        - accountId
        - settlementAmount
        - settlementCurrency
        - status
        - type
        - createdAt
      properties:
        id:
          type: string
          description: "Identifier of the transaction."
          example: "d413a9d7-6c7b-4f89-b47e-c742060a12c7"
        accountId:
          type: string
          description: "Unique identifier of the account associated with the transaction."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
        settlementAmount:
          type: string
          description: "Transaction amount in the settlement currency. The delimiter is a dot, with two digits after the delimiter."
          example: "150.00"
        settlementCurrency:
          description: "Settlement currency code. ISO 4217 currency code (3-letter format)."
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        status:
          description: |
            Current processing status of the transaction.

            * **authorized** – The transaction was authorized.  
            * **pending** – The transaction is being processed.  
            * **canceled** – The transaction was manually voided.  
            * **declined** – The transaction request was refused. No money was reserved or moved, so your account balance is unchanged.  
            * **completed** – The transaction cleared all processing steps and has now fully posted to your account. The amount is final and permanently reflected in your available balance.
          example: "authorized"
          enum:
            - pending
            - authorized
            - canceled
            - declined
            - completed
        type:
          $ref: "#/components/schemas/V1CardIssueTransactionEnumAccountTransactionType"
        createdAt:
          description: "Date and time when the transaction was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
          type: string
        parentId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of a related parent transaction. For example, a refund transaction will reference the original purchase transaction it reverses."
          example: "63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b"
      type: object
    V1CardIssueTransactionResponseCardTransactionDetailsResponse:
      title: V1-CardIssue-Transaction-Response-CardTransactionDetailsResponse
      required:
        - id
        - account
        - amount
        - currency
        - feeCurrency
        - settlementAmount
        - settlementCurrency
        - status
        - createdAt
        - updatedAt
        - transactionDetails
      properties:
        id:
          type: string
          description: "Identifier of the transaction."
          example: "d413a9d7-6c7b-4f89-b47e-c742060a12c7"
        account:
          $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionDetailsAccountDetailsResponse"
        amount:
          type: string
          format: money
          description: "Transaction amount in the merchant's currency (`currency`). The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        currency:
          description: "Source currency code. ISO 4217 currency code (3-letter format)."
          type: string
          maxLength: 3
          minLength: 3
          example: "USD"
        feeAmount:
          type: string
          description: "Fee amount charged for the transaction in the account currency (`feeCurrency`). The delimiter is a dot, with two digits after the delimiter."
          example: "2.50"
          nullable: true
        feeCurrency:
          type: string
          maxLength: 3
          minLength: 3
          nullable: true
          description: "Currency of the fee amount. ISO 4217 currency code (3-letter format)."
          example: "USD"
        settlementAmount:
          type: string
          description: "Transaction amount converted to the account currency (`settlementCurrency`), excluding fees. The delimiter is a dot, with two digits after the delimiter."
          example: "98.00"
        settlementCurrency:
          type: string
          maxLength: 3
          minLength: 3
          example: "USD"
          description: "Settlement currency code. ISO 4217 currency code (3-letter format)."
        description:
          type: string
          nullable: true
          description: "Comment regarding the transaction."
          example: "Payment for invoice #1234"
        status:
          $ref: "#/components/schemas/CardIssueEnumBalanceNewTransactionStatus"
        createdAt:
          description: "Date and time when the transaction was created. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          type: string
          example: "2025-06-02T15:38:49+00:00"
        updatedAt:
          type: string
          description: "Date and time of the latest transaction update. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        transactionDetails:
          $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionDetailsCardTransactionResponse"
        parentId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of a related parent transaction. For example, a refund transaction will reference the original purchase transaction it reverses."
          example: "63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b"
        transferJobId:
          type: string
          format: uuid
          nullable: true
          description: "Identifier of the job associated with this transaction."
          example: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
      type: object
    CardIssueEnumCardCardNetwork:
      title: " "
      type: string
      description: |
        Payment-card networks.
      enum:
        - visa
        - mastercard
        - jcb
        - amex
        - dci
        - unionpay
        - upi
        - mir
        - discover
        - redcompra
        - elo
        - hipercard
    V1CardIssueAccountResponseLimitPeriodTypeResponse:
      title: V1-CardIssue-Account-Response-LimitPeriodTypeResponse
      required:
        - type
      properties:
        type:
          type: string
          description: |
            The category of the limit, referencing how it applies. Possible values are:
            - **daily_limit**: The amount allowed per day.
            - **weekly_limit**: The amount allowed per week.
            - **monthly_limit**: The amount allowed per month.
            - **year_limit**: The amount allowed per year.
            - **lifetime_limit**: The total amount allowed over the entire card lifetime.
            - **transaction_limit**: The amount allowed for a single transaction.
          enum:
            - daily_limit
            - weekly_limit
            - monthly_limit
            - year_limit
            - lifetime_limit
            - transaction_limit
        amountMin:
          type: string
          nullable: true
          description: "Minimum amount allowed for the specified limit type. The delimiter is a dot, with two digits after the delimiter."
        amountMax:
          type: string
          description: "Maximum amount allowed for the specified limit type. The delimiter is a dot, with two digits after the delimiter."
          nullable: true
      type: object
    V1CardIssueCardResponseDetailsCardAccountDetailsResponse:
      title: V1-CardIssue-Card-Response-Details-CardAccountDetailsResponse
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: "Unique identifier of the account."
          example: "f123e456-7ab9-12d3-a456-426614174111"
        name:
          type: string
          description: "Name of the account."
          example: "Default Account"
      type: object
    V1CardIssueTransactionEnumAccountTransactionType:
      title: " "
      description: |
        Category describing the nature of an account-level transaction:

        * **payin** – Incoming credit to the account (e.g., top-up).  
        * **withdrawal** – Outgoing debit from the account.
        * **card_issuing** – Cost or fee related to issuing a new card.
      type: string
      enum:
        - payin
        - withdrawal
        - card_issuing
    V1CardIssueCardResponseDetailsCardDetailsResponse:
      title: V1-CardIssue-Card-Response-Details-CardDetailsResponse
      required:
        - cardId
        - name
        - currency
        - cardTokenizations
        - limits
        - cardOwner
        - status
        - availableActions
        - createdAt
        - updatedAt
      properties:
        cardId:
          type: string
          description: "Unique identifier of the card."
          example: "abc123e4-5678-90ab-cdef-1234567890ab"
        name:
          type: string
          description: "Name of the card."
          example: "Travel Card"
        availableBalance:
          type: string
          nullable: true
          description: "Available balance on the card. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
        spendedBalance:
          type: string
          nullable: true
          description: "Spent balance on the card. The delimiter is a dot, with two digits after the delimiter."
          example: "50.00"
        currency:
          description: "ISO 4217 currency code (3-letter format)."
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        holder:
          type: string
          nullable: true
          description: "Cardholder's name."
          example: "JOHN DOE"
        cardTokenizations:
          description: "Available card tokenization options. Can be empty."
          type: array
          items:
            type: string
            enum:
              - apple_pay
              - google_pay
        maskedNumber:
          type: string
          nullable: true
          description: "Masked card number."
          example: "4111******1111"
        paymentSystem:
          type: string
          nullable: true
          description: "Payment system of the card."
          allOf:
            - $ref: "#/components/schemas/CardIssueEnumCardCardNetwork"
        cardType:
          type: string
          description: |
            Type of the card.

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).  
            - **physical**: Indicates a physical plastic card.
          enum:
            - virtual
            - physical
          nullable: true
        expiredAt:
          type: string
          description: "Card expiration date in MM.YYYY format."
          example: "10.2024"
          nullable: true
        limits:
          type: array
          description: "Array of limit objects for this card."
          items:
            $ref: "#/components/schemas/V1CardIssueCardResponseDetailsCardLimitResponse"
        cardOwner:
          $ref: "#/components/schemas/V1CardIssueCardResponseDetailsCardOwnerResponse"
        status:
          $ref: "#/components/schemas/V1CardIssueCardEnumCardStatus"
        availableActions:
          type: array
          description: "List of available actions that can be performed on this card."
          items:
            type: string
            enum:
              - activate
              - freeze
              - close
        createdAt:
          type: string
          description: "Date and time when the card was issued. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        updatedAt:
          type: string
          description: "Date and time of the latest update to the card. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
        deletedAt:
          type: string
          description: "Date and time when the card was deleted. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
          default: null
          nullable: true
      type: object
    V1CardIssueTransactionResponseTransactionDetailsCardTransactionResponse:
      title: V1-CardIssue-Transaction-Response-TransactionDetails-CardTransactionResponse
      required:
        - card
        - type
      properties:
        card:
          $ref: "#/components/schemas/V1CardIssueTransactionResponseTransactionDetailsCardDetailsResponse"
        merchantName:
          type: string
          nullable: true
          description: "Name of the merchant or entity involved in this transaction."
          example: "John Doe Shop"
        merchantCountry:
          type: string
          nullable: true
          description: "Country of the merchant or entity involved in this transaction."
          example: "US"
        type:
          $ref: "#/components/schemas/V1CardIssueTransactionEnumCardTransactionType"
        rrn:
          type: string
          nullable: true
          description: "Retrieval Reference Number assigned by the processor."
          example: "123456789012"
        authorizationCode:
          type: string
          nullable: true
          description: "Code indicating approval of the transaction."
          example: "AUTH1234"
        authorizedBy:
          nullable: true
          description: "Indicates the entity that authorized the transaction."
          allOf:
            - $ref: "#/components/schemas/CardIssueEnumBalanceAuthorizedByType"
        declineReason:
          type: string
          description: "Reason for transaction decline."
          example: "Insufficient funds"
        mcc:
          type: string
          nullable: true
          description: "Merchant Category Code."
          example: "5999"
        transactionAt:
          type: string
          description: "Date and time when the transaction actually occurred. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
          nullable: true
      type: object
    V1CardIssueAccountEnumAccountStatus:
      title: " "
      type: string
      description: |
        Lifecycle statuses for a account:

        * **creating** – An account-creation request has been sent to the provider and is awaiting confirmation.  
        * **creating_failed** – The provider rejected or timed-out the creation request. You can retry creating the account.  
        * **active** – The account is fully operational; normal usage is allowed.  
        * **active_changing** – A change to an active account is in progress; the account remains usable, but its data is not yet in sync.  
        * **active_changing_failed** – The most recent attempt to change the active account failed; the account itself is still active and usable, but the requested update was not applied. You can try again. 
        * **inactive** – The account has been deactivated; no new operations are permitted until reactivation. To re-activate the account, call the **[Activate Account](/docs/api-reference/post-app-external-v-1-cardissue-account-account-activate)** endpoint.
        * **activating** – Reactivation of a previously inactive account is being processed.
        * **activating_failed** – The attempt to reactivate the account was rejected or errored; the account remains inactive and unusable. You can try again.
      enum:
        - creating
        - creating_failed
        - active
        - active_changing
        - active_changing_failed
        - inactive
        - activating
        - activating_failed
    V1CardIssueTransactionResponseTransactionDetailsAccountTransactionResponse:
      title: V1-CardIssue-Transaction-Response-TransactionDetails-AccountTransactionResponse
      required:
        - sourceAccountId
        - type
      properties:
        sourceAccountId:
          type: string
          description: "Identifier of the source account for this transaction."
          example: "a9c213e4-5678-90ab-cdef-1234567890ab"
        type:
          $ref: "#/components/schemas/V1CardIssueTransactionEnumAccountTransactionType"
        transactionAt:
          description: "Date and time when the transaction actually occurred. Returned in ISO 8601 format: `YYYY-MM-DDTHH:mm:ss±HH:MM`."
          example: "2025-06-02T15:38:49+00:00"
          type: string
          nullable: true
      type: object
    CardIssueEnumBalanceNewTransactionStatus:
      title: " "
      type: string
      description: |
        Processing status of a card transaction:

        * **authorized** – The transaction request has been approved and funds are placed on hold, but the amount has not yet been captured or settled; the final amount can still change.
        * **pending** – The transaction is being processed.
        * **canceled** – An existing authorisation was subsequently voided; the hold is released and the transaction will not proceed to settlement.
        * **declined** – The transaction request was rejected by the issuer, scheme, or internal rules; no funds were reserved or transferred.
        * **completed** – The transaction has fully cleared and settled; the final amount has been posted to the account balance and is no longer provisional.
      enum:
        - authorized
        - pending
        - canceled
        - declined
        - completed
      example: "authorized"
    V1CardIssueTransactionEnumTransactionStatus:
      title: V1-CardIssue-Transaction-Enum-TransactionStatus
      type: string
      description: |
        Processing status of a card transaction:

        * **authorized** – The transaction request has been approved and funds are placed on hold, but the amount has not yet been captured or settled; the final amount can still change.
        * **canceled** – An existing authorisation was subsequently voided; the hold is released and the transaction will not proceed to settlement.
        * **declined** – The transaction request was rejected by the issuer, scheme, or internal rules; no funds were reserved or transferred.
        * **completed** – The transaction has fully cleared and settled; the final amount has been posted to the account balance and is no longer provisional.
      enum:
        - authorized
        - canceled
        - declined
        - completed
      example: "authorized"
    V1CardIssueTransactionResponseTransactionDetailsAccountDetailsResponse:
      title: " "
      required:
        - accountId
        - accountName
      properties:
        accountId:
          type: string
          description: "Unique identifier of the account."
          example: "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
        accountName:
          type: string
          description: "Name of the account."
          example: "Marketing Expenses"
      type: object
    V1CardIssueTransactionResponseTransactionDetailsCardDetailsResponse:
      title: " "
      description: Set of card attributes of a transaction record.
      required:
        - id
        - maskedNumber
        - name
      properties:
        id:
          type: string
          description: Unique identifier of the card.
          example: abc123e4-5678-90ab-cdef-1234567890ab
        maskedNumber:
          type: string
          description: Masked primary account number (PAN) with only the first 6 and last 4 digits visible.
          example: "4111******1111"
        name:
          type: string
          description: Card label set by the user.
          example: "Travel Card"
      type: object
    CardIssueEnumBalanceAuthorizedByType:
      title: " "
      type: string
      enum:
        - system
        - merchant
        - provider
    V1CardIssueCardResponseDetailsCardLimitResponse:
      title: V1-CardIssue-Card-Response-Details-CardLimitResponse
      required:
        - id
        - type
        - value
        - spend
      properties:
        id:
          type: string
          description: "Unique identifier for this specific card limit."
          example: "d67fc9a2-8c24-4d81-a6c9-8e6b0dca3460"
        type:
          type: string
          description: |
            The category of the limit, referencing how it applies. Possible values are:
            - **daily_limit**: The maximum amount allowed per day.
            - **weekly_limit**: The maximum amount allowed per week.
            - **monthly_limit**: The maximum amount allowed per month.
            - **year_limit**: The maximum amount allowed per year.
            - **lifetime_limit**: The maximum total amount allowed over the entire card lifetime.
            - **transaction_limit**: The maximum amount allowed for a single transaction.
          enum:
            - daily_limit
            - weekly_limit
            - monthly_limit
            - year_limit
            - lifetime_limit
            - transaction_limit
          example: "daily_limit"
        value:
          type: string
          description: "Value of the set limit. The delimiter is a dot, with two digits after the delimiter."
          example: "500.00"
        spend:
          type: string
          description: "Amount already spent from this limit. The delimiter is a dot, with two digits after the delimiter."
          example: "100.00"
      type: object
    ProviderAccountInfo:
      title: ProviderAccountInfo
      required:
        - id
        - currency
        - supportedCardBalances
        - type
      properties:
        id:
          type: string
          description: "Unique identifier of the provider account."
          example: "1f01110f-e8b1-6188-80e5-52f68afc03c5"
        currency:
          type: string
          description: "Currency of the provider account. ISO 4217 currency code (3-letter format)."
          example: "USD"
        supportedCardBalances:
          type: string
          description: |
            List of supported card balance types for this provider account.

            - **personal_card_balance**: Each card has its own dedicated balance, separate from the main account balance.
            - **shared_account_balance**: All cards share the main account balance; no individual card balances are maintained.
          enum:
            - personal_card_balance
            - shared_account_balance
          example: "personal_card_balance"
        type:
          type: string
          description: |
            List of card types that can be issued under this provider account.

            - **virtual**: Indicates a card that exists only in digital form (no physical plastic card is issued).
            - **physical**: Indicates a physical plastic card.
          enum:
            - virtual
            - physical
          example: "virtual"
      type: object
    CreateAccountRequest:
      title: CreateAccountRequest
      required:
        - id
        - name
        - enableCardBalance
      properties:
        id:
          type: string
          description: "Identifier of the provider account to link. Must be obtained from the [Retrieve Available Provider Accounts](/docs/api-reference/get-cards-companies-accounts-providers) endpoint."
          example: "1f01110f-e8b1-6188-80e5-52f68afc03c5"
        name:
          type: string
          description: "Name for the new account."
          example: "Travel account"
        fees:
          default: null
          nullable: true
          description: |
            Object specifying custom fee settings for the account. 

            - If omitted, company-level fee settings will be applied.
            - By default, editing fees is not available. If you do not have access, please contact support to request it.
            - Any account-level fee (percentage or fixed) cannot be set lower than the corresponding company-level fee.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountRequestFeeList"
        enableCardBalance:
          type: string
          description: |
            Specifies the card balance type for the account. Possible values:

            - **personal_card_balance**: Each card has its own dedicated balance, separate from the main account balance.
            - **shared_account_balance**: All cards share the main account balance; no individual card balances are maintained.

            You can obtain the available values for this field from the response of the [Retrieve Available Provider Accounts](/docs/api-reference/get-cards-companies-accounts-providers) endpoint.
          enum:
            - personal_card_balance
            - shared_account_balance
          example: "personal_card_balance"
        accountBinDirections:
          type: array
          description: |
            Array of BIN configurations that define which BINs are available for card issuance within each category.  
            These settings are applied at the time of account creation and only affect newly issued cards.
          items:
            $ref: "#/components/schemas/V1CardIssueCardBinRequestCategoryBins"
          nullable: true
      type: object
    V1CardIssueCardBinRequestCategoryBins:
      title: V1-CardIssue-CardBin-Request-CategoryBins
      description: Configuration that maps a BIN category to specific BINs available for card issuance.
      required:
        - binCategoryId
      properties:
        binCategoryId:
          type: string
          description: |
            Unique identifier of the BIN category.  
            Defines the intended use case or purpose (e.g., travel, corporate expenses) for the BINs in this configuration.  
            You can obtain available category identifiers from the `data -> id` field returned by the [Retrieve Available BINs](/docs/api-reference/post-app-external-v-1-cardissue-cardbin-cardbin-listwithbins) endpoint.
          example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
        cardBinIds:
          type: array
          description: |
            List of specific BIN identifiers that will be available for card issuance within this category.  
            If omitted or set to null, all BINs from the provider that belong to this category will be available. 
            You can obtain available BIN identifiers from the `data -> bins -> cardProviderBinId` field returned by the [Retrieve Available BINs](/docs/api-reference/post-app-external-v-1-cardissue-cardbin-cardbin-listwithbins) endpoint.
          items:
            type: string
            example: "ff246e21-3bda-4e47-83fb-05203939fe5b"
          nullable: true
      type: object
    V1CardIssueAccountRequestFeeList:
      title: V1-CardIssue-Account-Request-FeeList
      properties:
        cardTransactions:
          type: object
          nullable: true
          description: |
            Fee settings for card transactions.  
            The fee is charged on the amount of each transaction performed with the account.  
            Can be specified as a percentage of the transaction amount or as a fixed amount per transaction.
          oneOf:
            - $ref: "#/components/schemas/V1CardIssueAccountRequestPercentFeeRequest"
            - $ref: "#/components/schemas/V1CardIssueAccountRequestAmountFeeRequest"
        cardIssuing:
          default: null
          nullable: true
          description: |
            Fee applied for issuing a new card.
            Can be specified as a fixed amount.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountRequestAmountFeeRequest"
        topUpsAllocation:
          default: null
          nullable: true
          description: |
            Fee applied when allocating top-up funds to the account.
            Can be specified as a percentage. The fee is charged on the amount of each top-up allocated to the account.
          allOf:
            - $ref: "#/components/schemas/V1CardIssueAccountRequestPercentFeeRequest"
      type: object
    V1CardIssueAccountRequestPercentFeeRequest:
      title: Percent Fee
      required:
        - value
        - type
      properties:
        value:
          type: string
          minimum: 0
          description: |
            Percentage value of the fee to be applied.
            Expressed as a string representing the percent (e.g., '15' for 15%). Dot as delimiter.
          example: "15"
        type:
          type: string
          description: |
            Indicates that the fee is specified as a percentage.
          enum:
            - percent
      type: object
    V1CardIssueAccountRequestAmountFeeRequest:
      title: Fixed Fee
      required:
        - value
        - type
      properties:
        value:
          type: string
          minimum: 0
          description: |
            Fixed fee amount to be applied.  
            Expressed as a string in the account's currency. Dot as delimiter.
          example: "2.50"
        type:
          type: string
          description: |
            Indicates that the fee is specified as a fixed amount.
          enum:
            - amount
      type: object
    V1CardIssueCardRequestTopUpCardRequest:
      title: V1-CardIssue-Card-Request-TopUpCardRequest
      description: |
        Specify the amount to be transferred from the account to the card.  
        The amount must be greater than zero and within the available account balance.
      required:
        - amount
      properties:
        amount:
          type: string
          minimum: 0
          exclusiveMinimum: true
          example: "100.00"
          description: |
            Amount to top up the card balance. Expressed as a string with a dot as the decimal separator.
      type: object
    V1CardIssueCardRequestWithdrawCardRequest:
      title: V1-CardIssue-Card-Request-WithdrawCardRequest
      description: |
        Request body for withdrawing funds from a card's balance to the associated account balance.

        Specify the amount to be transferred from the card to the account.
      required:
        - amount
      properties:
        amount:
          type: string
          example: "50.00"
          description: |
            Amount to withdraw from the card balance. Expressed as a string with a dot as the decimal separator.
      type: object
    V1CardIssueAccountResponseListAccountAvailableTransferResponse:
      title: V1-CardIssue-Account-Response-ListAccountAvailableTransferResponse
      description: "Paginated list of accounts available as destinations for a balance transfer."
      required:
        - accounts
        - pagination
      properties:
        accounts:
          type: array
          description: "List of accounts available for transfer."
          items:
            "$ref": "#/components/schemas/V1CardIssueAccountResponseAccountDictionary"
        pagination:
          "$ref": "#/components/schemas/ResponsePaginationResponse"
      type: object
    V1CardIssueAccountResponseAccountDictionary:
      title: V1-CardIssue-Account-Response-AccountDictionary
      description: "Account information"
      required:
        - id
        - name
        - currency
      properties:
        id:
          type: string
          description: "Unique identifier of the account."
          example: 1ef2294f-b286-64de-b605-0242ac12000e
        name:
          type: string
          description: "Display name of the account."
          example: Default
        currency:
          "$ref": "#/components/schemas/CurrencyAlpha3Type"
      type: object
    V1CardIssueAccountRequestTransferBalanceRequest:
      title: V1-CardIssue-Account-Request-TransferBalanceRequest
      description: "Request body for transferring balance between accounts."
      required:
        - amount
        - destinationAccountUuid
      properties:
        amount:
          type: string
          minimum: 0
          exclusiveMinimum: true
          description: "Amount to transfer. Expressed as a string with a dot as the decimal separator."
          example: "50.00"
        description:
          type: string
          nullable: true
          description: "Purpose or reason for the transfer."
          example: "Monthly budget allocation"
        destinationAccountUuid:
          type: string
          description: "Unique identifier of the destination account. Use [Retrieve Accounts Available for Transfer](/docs/api-reference/get-app-external-v-1-cardissue-account-account-listavailablefortransfer) to get the list of available destination accounts."
          example: "1ef2294f-b286-64de-b605-0242ac12000e"
      type: object
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Access-Token
      in: header
security:
  - ApiKey: []
x-webhooks:
  cardTransactionEvent:
    post:
      summary: "Card Transaction Event"
      description: |
        Notifies your system whenever any transaction event occurs on a card, including:
        - Transaction creation
        - Transaction confirmation
        - Transaction clearing
        - Transaction status change

        The payload structure is identical to the response of the [Retrieve Card Transaction Details](/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails) endpoint.

        We send POST requests with card data to your configured endpoint. 
        A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

        [See how to configure callback.](/docs/common/getting-started/webhooks)
      operationId: cardTransactionEventCallback
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/V1CardIssueTransactionResponseCardTransactionDetailsResponse"
  accountTransactionEvent:
    post:
      summary: "Account Transaction Event"
      description: |
        Notifies your system whenever any of the following events occur for an account transaction:
        - Transaction creation
        - Transaction confirmation
        - Transaction clearing
        - Transaction status change

        The payload structure is identical to the response of the [Retrieve Account Transactions](/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails) endpoint.

        We send POST requests with transaction data to your configured endpoint. 
        A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

        [See how to configure callback.](/docs/common/getting-started/webhooks)
      operationId: accountTransactionEventCallback
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/V1CardIssueTransactionResponseAccountTransactionHistoryDetailsResponse"
  accountTopUpEvent:
    post:
      summary: "Account Top-Up Event"
      description: |
        Notifies your system whenever any of the following events occur for an account top-up:
        - Top-up received
        - Top-up confirmation
        - Top-up status change

        The payload structure is identical to the response of the [Retrieve Top-Up Details](/docs/api-reference/get-app-external-v-1-cardissue-topup-topups-details) endpoint.

        We send POST requests with top-up data to your configured endpoint. 
        A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

        [See how to configure callback.](/docs/common/getting-started/webhooks)
      operationId: accountTopUpEventCallback
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/V1CardIssueTopUpResponseTopUpInfoResponse"
  cardStateEvent:
    post:
      summary: "Card State Event"
      description: |
        Notifies your system whenever a card is created or its `status` changes.

        The payload structure is identical to the response of the [Retrieve Card Details](/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid) endpoint.

        We send POST requests with card data to your configured endpoint.
        A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

        [See how to configure callback.](/docs/common/getting-started/webhooks)
      operationId: cardStateEventCallback
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/V1CardIssueCardResponseGetCardDetailsResponse"
