openapi: 3.2.0
info:
  description: 'Endpoints for doing various actions connected to the Card entity.

    All date-time fields adhere to the ISO 8601 standard unless specified otherwise.

    For example: 2024-05-31T06:55:17Z'
  version: '1'
  title: Get card API
  contact:
    name: Enfuce Financial Services
    url: https://enfuce.com
    email: info@enfuce.com
servers:
- url: https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer
  description: UAT Sandbox
- url: https://api.{{tenant}}.eu.live.prod.mycore.enfuce.com/issuer
  description: Production
security:
- bearerAuth: []
tags:
- name: Get card
  description: Endpoints for fetching a card
paths:
  /v1/cards:
    get:
      tags:
      - Get card
      summary: Get Card Applications for Main Card
      description: 'Send a request to this endpoint to return all card applications for a specific main card.

        If the main card does not exist, an empty array is returned.'
      operationId: getCards
      parameters:
      - name: mainCardId
        in: query
        description: Unique identifier of the main card for which you want to retrieve the list of card applications.
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/x-audit-user'
      responses:
        '200':
          description: Successful retrieval of card applications.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/cards/{id}:
    get:
      tags:
      - Get card
      summary: Get Card
      operationId: getCard
      parameters:
      - name: id
        in: path
        description: Unique identifier of the card you want to retrieve.
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/x-audit-user'
      responses:
        '200':
          description: The card details are successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/cards/{id}/controlToken:
    post:
      tags:
      - Get card
      summary: Initiate Card Data Retrieval
      description: 'Send a request to this endpoint when the cardholder wants to retrieve card data, such as PAN, expiry and CVV2/CVC2.

        If no sequence number is specified, the latest card version is used by default. Only card versions not in CLOSED status are allowed.'
      operationId: getCardDataControlToken
      parameters:
      - name: id
        in: path
        description: Unique identifier of the card.
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/x-audit-user'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlTokenRequestBody'
      responses:
        '200':
          description: Control token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardDataControlTokenResponseBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CardConfigurationType:
      type: string
      description: The type of card defined by this card configuration.
      enum:
      - DEBIT
      - CREDIT
      - COMBO
      example: CREDIT
    Id:
      type: string
      format: uuid
      description: Unique identifier of a resource.
      example: 20218aae-b15e-406c-9e9f-23735cd86a48
    AdditionalValues:
      type: object
      description: 'You can include up to **30 additional key-value pairs** in the embossing file sent to the card manufacturer.


        - **Keys** must follow the pattern: `^[a-zA-Z0-9-]{1,36}$` (only letters, numbers, and hyphens, with a maximum length of 36 characters).

        - **Values** must follow the pattern: `^[a-zA-Z0-9|\-_ +.@éàèùçâêîôûëïü''/=]{1,1000}$`.


        Enfuce **does not perform any additional validation** on these key-value pairs beyond ensuring they match the specified patterns.


        These fields are intended for **storing data without further processing**. If you need to store a **complex structure**, you can **base64 encode** the value. The encoded value will be passed as entered, without modifications.


        ⚠ **Important:** Any usage of these fields should be agreed upon with the manufacturer.

        '
      maxProperties: 30
      additionalProperties:
        type: string
      example:
        keyWithPlainTextValue: value1
        keyWithBase64Value: dmFsdWUyYmFzZTY0ZW5jb2RlZA==
    CardVersionStatus:
      type: string
      description: '- ACTIVE - The card is completely operational. You can perform all actions with the card.

        - ACTIVE_LIMITED - The card version is usable for digital transactions only. Provisioning, token payments and e-commerce transactions are allowed, while physical entry modes (chip, contactless, magstripe and ATM) are declined.

        - INITIAL - The specific card version is awaiting activation. During this state, the card can have limited usage, such as being added to a digital wallet or cardholder can view the PIN (if it is a plastic card). However, in the INITIAL state, the card cannot be used for payments.

        - CLOSED - The previous versions of the card are no longer valid as a new version is activated or the card is closed.

        '
      enum:
      - ACTIVE
      - ACTIVE_LIMITED
      - INITIAL
      - CLOSED
      example: ACTIVE
    ErrorResponse:
      type: object
      properties:
        type:
          description: The problem type.
          type: string
        title:
          description: The reason phrase of HttpStatus.
          type: string
        status:
          description: HTTP problem status.
          type: number
        detail:
          description: The problem detail.
          type: string
        instance:
          description: The request path.
          type: string
        id:
          description: Unique error identifier.
          type: string
          format: uuid
        timestamp:
          description: Date-time when error occurred.
          type: string
          format: date-time
    CardConfigurationCode:
      type: string
      description: A unique code to identify the card configuration. Max character limit is 36.
      example: MC_DEBIT_1
      minLength: 1
      maxLength: 36
      pattern: ^[A-Za-z0-9_-]+$
    CardStatus:
      type: string
      description: '- ACTIVE - Card is active and is enabled for normal usage.

        - BLOCKED - Card is temporarily blocked.

        - BLOCKED_SUSPECTED_FRAUD - Card is temporarily blocked due to suspected fraud.

        - CLOSED_DUE_TO_FRAUD - Card has been closed due to fraud.

        - CLOSED_LOST - Card has been closed due to being lost.

        - CLOSED_STOLEN - Card has been closed due to being stolen.

        - CLOSED - Card has been manually closed.

        - CLOSED_EXPIRED - Card has no active or initial card versions and cannot be used.

        '
      enum:
      - ACTIVE
      - BLOCKED
      - BLOCKED_SUSPECTED_FRAUD
      - CLOSED_DUE_TO_FRAUD
      - CLOSED_LOST
      - CLOSED_STOLEN
      - CLOSED
      - CLOSED_EXPIRED
      example: ACTIVE
    Printed:
      type: boolean
      description: 'Indicates whether the specific card would be printed or not. Only applicable to multi-application cards.

        Otherwise, the request will return 400 Bad Request.

        '
      example: true
    ExternalLayoutCode:
      type: string
      description: Unique code forwarded to the embossing house; the code identifies the plastic layout to be used for printing the new card. Ensure beforehand, the selected embossing house is aligned with the code used for each layout.
      minLength: 1
      maxLength: 32
      pattern: ^[a-zA-Z0-9-_]+$
      example: 1
    ChipEnabled:
      type: boolean
      description: 'Whether the card should be visible in card terminal or not. Only applicable to multi-application cards.

        Otherwise, the request will return 400 Bad Request.

        '
      example: true
    ControlTokenRequestBody:
      type: object
      properties:
        sequenceNumber:
          allOf:
          - $ref: '#/components/schemas/SequenceNumber'
          description: 'The sequence number of the card version to use. If not specified, the latest card version is used by default.

            Only card versions not in CLOSED status are allowed.

            '
      title: ControlTokenRequestBody
    EmbossingName:
      type: string
      description: The name to be embossed on the card. Max character limit is 26.
      minLength: 1
      maxLength: 26
      pattern: ^[A-Za-z0-9 /.,&+'\- ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ ĀāĂ㥹ĆćĈĉĊċČčĎďĐđĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪīĬĭĮįİıIJijĴĵĶķĸĹ ĺĻļĽľĿŀŁłŃńŅņŇňʼnŊŋŌōŎŏŐőŒœŔŕŖŗŘřŚśŜŝŞşŠšŢţŤťŦŧŨũŪūŬŭŮůŰű ŲųŴŵŶŷŸŹźŻżŽžſǪǫȘșȚțȪȫȮȯȲȳḐḑṢṣẞỌọ]+$
      example: John Doe
    UpdateCount:
      type: integer
      description: The version number of the entity.
      example: 1
    CardVersion:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CardVersionStatus'
        expirationTime:
          $ref: '#/components/schemas/ExpirationTime'
        renewalDate:
          $ref: '#/components/schemas/RenewalDate'
        sequenceNumber:
          $ref: '#/components/schemas/SequenceNumber'
        keySetId:
          $ref: '#/components/schemas/KeySetId'
        createdAt:
          $ref: '#/components/schemas/Created'
        updatedAt:
          $ref: '#/components/schemas/Updated'
    Plastic:
      type: object
      properties:
        embossingName:
          $ref: '#/components/schemas/EmbossingName'
        preferredCardAddress:
          $ref: '#/components/schemas/Address'
        preferredCardDeliveryType:
          $ref: '#/components/schemas/CardDeliveryType'
        preferredPinAddress:
          $ref: '#/components/schemas/Address'
        preferredPinDeliveryType:
          $ref: '#/components/schemas/PinDeliveryType'
        manufacturerId:
          $ref: '#/components/schemas/Id'
        externalLayoutCode:
          $ref: '#/components/schemas/ExternalLayoutCode'
        createdAt:
          $ref: '#/components/schemas/Created'
        updatedAt:
          $ref: '#/components/schemas/Updated'
    Address:
      type: object
      properties:
        address1:
          description: First line of address.
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^(?!\s)(?!.*\s$).+(?<!\s)$
          example: Kings street 12
        address2:
          type: string
          pattern: ^(?!\s)(?!.*\s$).*(?<!\s)$
          description: Second line of address. Any string without trailing or leading whitespaces, or an empty string.
          maxLength: 255
          example: Apartment 5B
        address3:
          type: string
          pattern: ^(?!\s)(?!.*\s$).*(?<!\s)$
          description: Third line of address. Any string without trailing or leading whitespaces, or an empty string.
          maxLength: 255
          example: Building C
        address4:
          type: string
          pattern: ^(?!\s)(?!.*\s$).*(?<!\s)$
          description: Fourth line of the address. Any string without trailing or leading whitespaces, or an empty string.
          maxLength: 255
          example: Entrance North
        city:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^(?!\s)(?!.*\s$).+(?<!\s)$
          example: Mariehamn
        country:
          type: string
          description: A valid ISO-3166-1 alpha-3 country code.
          pattern: '[A-Z]{3}'
          example: FIN
        region:
          type: string
          maxLength: 32
          example: Åland Islands
        zipCode:
          type: string
          minLength: 1
          maxLength: 32
          pattern: ^(?!\s)(?!.*\s$).+(?<!\s)$
          example: 22100
      required:
      - address1
      - city
      - country
      - zipCode
    AccountId:
      type: string
      description: Unique identifier of an account.
      minLength: 1
      maxLength: 36
      example: 20218aae-b15e-406c-9e9f-23735cd86a48
      pattern: ^[a-zA-Z0-9-]+$
    CardDeliveryType:
      type: string
      description: Select the type of delivery you prefer for the new card being created. - MAIL - The card would be sent via mail services. - COURIER - The card would be sent via courier services. - CUSTOM_1–CUSTOM_5 - Custom delivery types that can be used for shipping methods agreed between the customer and the bureau.
      enum:
      - MAIL
      - COURIER
      - CUSTOM_1
      - CUSTOM_2
      - CUSTOM_3
      - CUSTOM_4
      - CUSTOM_5
      example: MAIL
    ExpirationTime:
      type: string
      format: date-time
      description: 'The expiration date-time of the card, always at 23:59:59 UTC on the last day of a month.


        If a different expiry than the program default is specified during card creation, it is

        converted to UTC (if a different offset is given) and rounded up to 23:59:59 of the last day of

        its own month.


        To be sure of the exact expiration month, always specify this value with a Z (UTC) offset. For

        example, to expire the card in August 2030, set "2030-08-31T23:59:59Z".

        '
      example: '2030-08-31T23:59:59Z'
    RenewalDate:
      type: string
      format: date
      description: The date when the auto renewal occurs.
    DigitalLayoutCode:
      type: string
      description: The digital layout code for the card. Max character limit is 36.
      minLength: 1
      maxLength: 36
      pattern: ^[a-zA-Z0-9-]+$
      example: 9
    CardResponse:
      type: object
      title: Create Single Card
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/Id'
          description: Unique identifier of a card.
        createdAt:
          $ref: '#/components/schemas/Created'
        updatedAt:
          $ref: '#/components/schemas/Updated'
        programId:
          allOf:
          - $ref: '#/components/schemas/Id'
          description: The program ID associated with the card.
        cardholderId:
          allOf:
          - $ref: '#/components/schemas/Id'
          description: Unique identifier of the cardholder associated with the card.
        accountId:
          allOf:
          - $ref: '#/components/schemas/AccountId'
          description: Unique identifier of the account associated with the card.
        plastic:
          $ref: '#/components/schemas/Plastic'
        cardVersions:
          type: array
          description: Card versions ordered by sequence number ascending.
          items:
            $ref: '#/components/schemas/CardVersion'
        role:
          $ref: '#/components/schemas/CardRole'
        mainCardId:
          allOf:
          - $ref: '#/components/schemas/Id'
          description: Unique identifier of the main card. Populated if this card is part of a card application
        previousCardId:
          allOf:
          - $ref: '#/components/schemas/Id'
          description: Unique identifier of the card this card replaced. Populated if this card is a replacement of another card.
        cardConfigurationCode:
          $ref: '#/components/schemas/CardConfigurationCode'
        cardConfigurationType:
          $ref: '#/components/schemas/CardConfigurationType'
        cardScheme:
          $ref: '#/components/schemas/CardScheme'
        maskedPan:
          $ref: '#/components/schemas/MaskedPrimaryAccountNumber'
        pinStatus:
          $ref: '#/components/schemas/PinStatus'
        cardStatus:
          $ref: '#/components/schemas/CardStatus'
        automaticRenewal:
          $ref: '#/components/schemas/AutomaticRenewal'
        digitalLayoutCode:
          $ref: '#/components/schemas/DigitalLayoutCode'
        multiApplicationProperties:
          $ref: '#/components/schemas/MultiApplicationProperties'
        updateCount:
          $ref: '#/components/schemas/UpdateCount'
        additionalValues:
          $ref: '#/components/schemas/AdditionalValues'
        feeConfigId:
          allOf:
          - $ref: '#/components/schemas/FeeConfigId'
    ContactPriorityLevel:
      type: integer
      description: 'The contact priority level for given card. Only applicable to multi-application cards.

        Otherwise, the request will return 400 Bad Request.

        '
      format: int32
      minimum: 0
    ApplicationIndex:
      type: integer
      description: The index of the application
      example: 1
    CardDataControlTokenResponseBody:
      type: object
      properties:
        token:
          type: string
          description: The control token.
          example: eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..pTLFy-lzse0ZmtOX.vjG0cY1uxH8v80amEjOgPs0zUv9lDXrskW0nM0MBArCBqzZ9Ph2k3Lt85L1uEq2RK0YG6mCTJdGOyOuuO3CmPE-_w941ya5y4RskdHefCkQDdRG3sesQ070d1nMgLRWFLorJKjn7umSyOrRMjMjQg684O5VWxlApPwgIt4sOXbTZKcrRh5qv-8cBDp4IYQ-HznucHiloVtjZf2he.UrmJDmSYeBSveB-uojVDnA
        cardDataUrl:
          type: string
          description: The URL to call on mobile devices for accessing the card's data.
          example: https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/card-data/view
        cardDataFrameUrl:
          type: string
          description: The URL to open in iframe to access the card's data.
          example: https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/card-data/view/frame
      required:
      - token
      title: CardDataControlTokenResponseBody
    MultiApplicationProperties:
      type: object
      properties:
        applicationName:
          $ref: '#/components/schemas/ApplicationName'
        applicationIndex:
          $ref: '#/components/schemas/ApplicationIndex'
        contactPriorityLevel:
          $ref: '#/components/schemas/ContactPriorityLevel'
        contactlessPriorityLevel:
          $ref: '#/components/schemas/ContactlessPriorityLevel'
        printed:
          $ref: '#/components/schemas/Printed'
        chipEnabled:
          $ref: '#/components/schemas/ChipEnabled'
    ApplicationName:
      type: string
      description: 'Name of the application. Max character limit is 16. Only applicable to multi-application cards.

        Otherwise, the request will return 400 Bad Request.

        '
      minLength: 1
      maxLength: 16
      pattern: ^[a-zA-Z ]+$
      example: Credit Application
    CardRole:
      type: string
      description: The role of the card. Multi application cards will have one main card and multiple card applications. Single cards will be treated as main cards.
      enum:
      - MAIN_CARD
      - CARD_APPLICATION
      example: MAIN_CARD
    AutomaticRenewal:
      type: boolean
      description: A flag indicating whether automatic renewal is enabled or not.
    SequenceNumber:
      type: integer
      minimum: 1
      description: The sequence number of the card version, this value is also known as PSN (pan sequence number)
      example: 1
    PinStatus:
      type: string
      description: '- GENERATED - A pin has been randomly generated for the card.

        - WAITING - A pin is waiting to be set on the card.

        - SET - A pin has been manually set on the card.

        - INHERITED - For card applications only. The pin status is inherited from the main card.

        '
      enum:
      - GENERATED
      - WAITING
      - SET
      - INHERITED
      example: GENERATED
    ContactlessPriorityLevel:
      type: integer
      description: 'The contactless priority level of the given card. Only applicable to multi-application cards.

        Otherwise, the request will return 400 Bad Request.

        '
      format: int32
      minimum: 0
    FeeConfigId:
      type: string
      description: 'Unique identifier of a fee configuration. When provided, this value overrides the program default. This feature must be enabled for the tenant; otherwise, this field can be left null and will not be used.

        '
      minLength: 1
      maxLength: 36
      example: SILVER
      pattern: ^[a-zA-Z0-9_-]+$
    KeySetId:
      type: string
      format: uuid
      description: The id of the key set used by this card version
      example: 01b20ad2-3c2a-48d2-ac2e-5bf6d8b246cd
    CardScheme:
      type: string
      enum:
      - MASTERCARD
      - VISA
      example: MASTERCARD
    PinDeliveryType:
      type: string
      description: Select the type of delivery you prefer for sending the card PIN. - MAIL - The card PIN would be sent via mail services. - COURIER - The card PIN would be sent via courier services. - EPIN - The card PIN would be sent digitally.
      enum:
      - MAIL
      - COURIER
      - EPIN
      example: MAIL
    Created:
      type: string
      format: date-time
      description: The date and time when the card was created.
    MaskedPrimaryAccountNumber:
      type: string
      description: A masked version of the primary account number
      example: '123456______4285'
    Updated:
      type: string
      format: date-time
      description: The date and time when the object/entity was updated last time.
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: about:blank
            title: Bad Request
            status: 400
            detail: 'JSON parse error: Unexpected character...'
            instance: /v1/cards
            id: 5cc541cb-f456-4331-b537-d2380fca0400
            timestamp: '2026-02-24T12:34:56Z'
    InternalServerError:
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: about:blank
            title: Internal Server Error
            status: 500
            detail: Unexpected error occurred.
            instance: /v1/cards
            id: 5cc541cb-f456-4331-b537-d2380fca0500
            timestamp: '2026-02-24T12:34:56Z'
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: about:blank
            title: Forbidden
            status: 403
            detail: Access Denied
            instance: /v1/cards
            id: 5cc541cb-f456-4331-b537-d2380fca0403
            timestamp: '2026-02-24T12:34:56Z'
    Unauthorized:
      description: Unauthorized
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: about:blank
            title: Not Found
            status: 404
            detail: 'Entity not found - Program with id: 2ec117b7-454e-4cc5-8b89-dea5485aab2b'
            instance: /v1/cards
            id: 5cc541cb-f456-4331-b537-d2380fca0404
            timestamp: '2026-02-24T12:34:56Z'
  parameters:
    x-audit-user:
      in: header
      name: x-audit-user
      required: false
      description: Optional audit user header
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT