openapi: 3.0.1
info:
  title: Cards REST APIs
  description: Cards Internal REST APIs
  version: '1'
servers:
  - url: 'https://api.plumery.com'
    description: Live Server
paths:
  '/internal/v1/parties/{partyId}/cards':
    get:
      description: |
        Internal API to retrieve a single card of a party using either its card ID or its card token.
        Exactly one of `cardId` or `cardToken` must be provided. The response includes both identifiers.
      operationId: Get card by ID or token
      parameters:
        - $ref: '#/components/parameters/partyId'
        - $ref: '#/components/parameters/cardId'
        - $ref: '#/components/parameters/cardToken'
        - $ref: '#/components/parameters/includeStatusHistory'
      responses:
        '200':
          $ref: "#/components/responses/InternalCardResponse"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-internal: true
components:
  responses:
    InternalCardResponse:
      description: The matching card, including both card ID and card token.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InternalCard"
    BadRequest:
      description: Invalid request (neither or both of cardId/cardToken provided).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponse'
    NotFound:
      description: No card found for the given identifier.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundErrorResponse'
          example:
            code: "urn:plmr:cards:api:CARD_NOT_FOUND"
            message: "Card was not found."
            requestId: "61201356-81f5-9d7e-8b85-262482a0c724"
    ServerError:
      description: Internal server error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerErrorResponse'
  parameters:
    partyId:
      in: path
      name: partyId
      required: true
      description: |
        The ID of the party that owns the cards. See PartyId model.
      schema:
        $ref: "#/components/schemas/PartyId"
    cardId:
      in: query
      name: cardId
      required: false
      description: The card ID. Provide either this or cardToken.
      schema:
        $ref: "#/components/schemas/CardId"
    cardToken:
      in: query
      name: cardToken
      required: false
      description: The card token. Provide either this or cardId.
      schema:
        $ref: "#/components/schemas/CardToken"
    includeStatusHistory:
      in: query
      name: includeStatusHistory
      required: false
      description: |
        Set to `true` to include history of card transitions in the response.
      example: true
      schema:
        type: boolean
        default: false
  schemas:
    BadRequestResponse:
      description: Bad request response
      type: object
      properties:
        code:
          $ref: '#/components/schemas/BadRequestErrorCode'
        message:
          type: string
        requestId:
          type: string
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    InternalServerErrorResponse:
      description: Internal server error response
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InternalServerErrorCode'
        message:
          type: string
        requestId:
          type: string
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    NotFoundErrorResponse:
      type: object
      description: Not found error response
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorCode'
        message:
          type: string
        requestId:
          type: string
    BadRequestErrorCode:
      type: string
      enum:
        - 'urn:plmr:cards:api:INVALID_CARD_LOOKUP_REQUEST'
        - 'urn:plmr:cards:api:BAD_REQUEST'
        - 'urn:plmr:cards:api:INVALID_PARAM'
        - 'urn:plmr:cards:api:WEB_APPLICATION'
      example: 'urn:plmr:cards:api:INVALID_CARD_LOOKUP_REQUEST'
    NotFoundErrorCode:
      type: string
      enum:
        - 'urn:plmr:cards:api:RESOURCE_UNKNOWN'
        - 'urn:plmr:cards:api:CARD_NOT_FOUND'
      example: 'urn:plmr:cards:api:CARD_NOT_FOUND'
    InternalServerErrorCode:
      type: string
      enum:
        - 'urn:plmr:cards:api:INTERNAL_SERVER_ERROR'
      example: 'urn:plmr:cards:api:INTERNAL_SERVER_ERROR'
    FieldErrorCode:
      type: string
      enum:
        - 'urn:plmr:cards:api:NOT_BLANK'
        - 'urn:plmr:cards:api:NOT_NULL'
    FieldError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/FieldErrorCode'
        message:
          type: string
        field:
          type: string
    PartyId:
      type: string
      description: Unique identifier for the party.
      example: 6878951b-256b-4baa-9e81-ad4c577adc4e
    InternalCard:
      title: InternalCard
      description: |
        Internal representation of a card. Same non-sensitive data as BasicCard, plus the card token,
        so internal services can reference a card by either its card ID or its card token.
      allOf:
        - $ref: '#/components/schemas/BasicCard'
        - type: object
          properties:
            token:
              type: string
              description: The card token used as a card reference by internal services.
    BasicCard:
      type: object
      title: BasicCard
      description: Safe representation of a card, excluding any sensitive data.
      properties:
        cardId:
          $ref: "#/components/schemas/CardId"
        cardholder:
          $ref: "#/components/schemas/Cardholder"
        type:
          $ref: "#/components/schemas/CardType"
        primaryAccountId:
          $ref: "#/components/schemas/AccountId"
        maskedPan:
          $ref: "#/components/schemas/CardMaskedPan"
        expirationDate:
          type: string
          description: Expiry date of the card
          format: MM/YY
          example: 07/24
        cardStatus:
          $ref: "#/components/schemas/CardStatus"
        cardStatusDateTime:
          $ref: "#/components/schemas/DateTime"
        cardStatusHistory:
          $ref: "#/components/schemas/CardStatusHistory"
        fulfillmentStatus:
          $ref: "#/components/schemas/FulfillmentStatus"
        fulfillmentStatusDateTime:
          $ref: "#/components/schemas/DateTime"
        fulfillmentStatusHistory:
          $ref: "#/components/schemas/FulfillmentStatusHistory"
        alias:
          $ref: "#/components/schemas/CardAlias"
        atmWithdrawalsAllowed:
          $ref: "#/components/schemas/AtmWithdrawalsAllowed"
        onlinePaymentsAllowed:
          $ref: "#/components/schemas/OnlinePaymentsAllowed"
        contactlessAllowed:
          $ref: "#/components/schemas/ContactlessAllowed"
        additionalAttributes:
          $ref: '#/components/schemas/AdditionalAttributes'
        limitsList:
          type: array
          items:
            $ref: "#/components/schemas/UpsertLimitRequest"
        productId:
          $ref: "#/components/schemas/ProductId"
        customisation:
          $ref: "#/components/schemas/Customisation"
        walletTokens:
          type: array
          items:
            $ref: "#/components/schemas/WalletToken"
      required:
        - cardId
        - cardholder
        - cardType
        - primaryAccountId
        - maskedPan
        - expirationDate
        - cardStatus
        - cardStatusDateTime
        - fulfillmentStatus
        - fulfillmentStatusDateTime
    CardStatusHistory:
      type: array
      items:
        type: object
        properties:
          cardStatus:
            $ref: '#/components/schemas/CardStatus'
          cardStatusDateTime:
            $ref: '#/components/schemas/DateTime'
    FulfillmentStatusHistory:
      type: array
      items:
        type: object
        properties:
          fulfillmentStatus:
            $ref: '#/components/schemas/FulfillmentStatus'
          fulfillmentStatusDateTime:
            $ref: '#/components/schemas/DateTime'
    WalletToken:
      type: object
      description: Represents a digital wallet token provisioned to a device
      properties:
        walletToken:
          type: string
          description: Wallet token id
          example: d932902f-6832-4083-8c4e-77328b0e05d1
        walletType:
          type: string
          description: Type of digital wallet (e.g., GOOGLE_PAY, APPLE_PAY)
          example: GOOGLE_PAY
        state:
          type: string
          description: Current state of the wallet token
          example: ACTIVE
        stateDateTime:
          $ref: '#/components/schemas/DateTime'
      required:
        - walletType
        - state
        - stateDateTime
    UpsertLimitRequest:
      type: object
      properties:
        amount:
          $ref: "#/components/schemas/LimitAmount"
        window:
          $ref: "#/components/schemas/LimitWindow"
        type:
          $ref: "#/components/schemas/LimitType"
      required:
        - amount
        - window
        - type
    AdditionalAttributes:
      type: object
      additionalProperties: true
      description: |
        Free-form map of non-standard attributes.
    CardId:
      type: string
      description: Unique identifier for the card.
      example: d932902f-6832-4083-8c4e-77328b0e05d1
    CardToken:
      type: string
      description: The card token used as a card reference by internal services.
      example: 89d94bb5-03a6-43cf-8c29-9ddaecb07f12
    Cardholder:
      type: string
      description: Name of the person who owns the card.
      example: John Doe
    AccountId:
      type: string
      description: Unique identifier for the account the card is associated to.
      example: 332cb801-1510-46c8-b4c5-a16b2ebc3757
    CardMaskedPan:
      type: string
      description: Display-friendly, obfuscated version of the Primary Account Number (PAN).
      example: 111111****5162
    CardType:
      type: string
      description: |
        The Card Type.

        The current set of possible values includes:
        - VIRTUAL
        - PHYSICAL

        Please note that new possible values can be added in the future.
      example: VIRTUAL
    CardStatus:
      type: string
      description: Card current status
      enum:
        - ACTIVE
        - INACTIVE
        - FROZEN
        - TERMINATED
        - EXPIRED
      example: ACTIVE
    FulfillmentStatus:
      type: string
      description: Card fulfillment status
      enum:
        - ISSUED
        - ORDERED
        - SHIPPED
        - DELIVERED
      example: ISSUED
    CardAlias:
      type: string
      description:
        The card alias.
      example: Online Shopping
    AtmWithdrawalsAllowed:
      type: boolean
      description: |
        Indicates whether ATM cash withdrawals are permitted for the card. By default at card creation this is true.
      example: true
    OnlinePaymentsAllowed:
      type: boolean
      description: |
        Indicates whether online (e-commerce) payments are permitted for the card. By default at card creation this is true.
      example: true
    ContactlessAllowed:
      type: boolean
      description: |
        Indicates whether contactless payments are permitted for the card. By default at card creation this is true.
      example: true
    ProductId:
      type: string
      description: |
        The product id value associated with the card. If none is provided, then the default product id for virtual cards will be used.
      example: "abc123"
    Customisation:
      type: object
      description: The customisation to be applied on the card.
      properties:
        colour:
          $ref: "#/components/schemas/Colour"
        text:
          $ref: "#/components/schemas/Text"
        designId:
          type: string
          description: Unique identifier of the design to be applied on the card.
    Colour:
      type: string
      description: |
        The colour of the card as supported by the fulfilment provider.
      example: "BLACK"
    Text:
      type: string
      description: |
        Custom text to be displayed on the card. Maximum of 21 characters allowed.
      example: "John Doe"
    LimitAmount:
      description: |
        The amount given with fractional digits, where fractions must be compliant to the currency definition.
        Up to 14 significant figures. The decimal separator is a dot.

        **Example:**
        Valid representations for EUR with up to two decimals are:

          * 1056
          * 5877.78
      type: string
      pattern: '[0-9]{1,14}(\.[0-9]{1,3})?'
      example: '5877.78'
    LimitWindow:
      description: |
        The time window for which the limit applies.
      type: string
      enum:
        - 'DAILY'
        - 'WEEKLY'
        - 'MONTHLY'
      example: 'DAILY'
    LimitType:
      description: |
        The type of transaction to which the limit applies.
           - `ATM_WITHDRAWAL`: The limit applies to cash withdrawals made at ATMs.
           - `PURCHASE`: The limit applies to purchase transactions.
      type: string
      enum:
        - 'ATM_WITHDRAWAL'
        - 'PURCHASE'
      example: 'PURCHASE'
    DateTime:
      format: date-time
      type: string
      example: '2024-07-22T11:02:11Z'