Barclays Card Controls API

openapi: 3.2.0
info:
  title: Card Controls API
  description: Enables customers to securely lock and unlock credit cards
  version: '1.0'
tags:
- name: Card Controls API
  description: API for locking and unlocking cards and retrieving card lock/unlock status based on account ID with fraud verification.
paths:
  /cards/accounts/{accountId}/unlock-card:
    summary: Unlock a card for an account
    description: Unlocks a card based on external customer ID and card last 4 digits with fraud verification
    post:
      tags:
      - Card Controls API
      summary: Unlock a card for an account
      description: 'Unlocks a card based on the provided account ID, external customer ID, and card last 4 digits.

        Performs fraud assessment before unlocking the card and returns unlock status.


        **Business Flow:**

        1. Validates account and customer details via entitlement service

        2. Performs fraud assessment through decision gateway

        3. Unlocks the card via card control service

        4. Polls for unlock confirmation status

        5. Returns unlock status with card identifier and customer role


        **Error Scenarios:**

        - 400: Invalid request format or account/customer not found

        - 403: Fraud assessment declined the operation

        - 404: Resource not found

        - 428: Additional fraud verification required (challenge)'
      operationId: unlockCard
      parameters:
      - name: Content-Type
        in: header
        description: Content-Type
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 35
          minLength: 16
          pattern: ^[a-z0-9A-Z\/ ]{16,35}$
        example: application/json
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: accountId
        in: path
        description: A unique identifier (UUID format) for the customer account
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: c8de699e-ff6d-11eb-9a03-0242ac130003
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      requestBody:
        description: Card unlock request containing the card identifier for fraud assessment and unlock operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlockCardRequestData'
            examples:
              single-card:
                summary: Single card unlock
                value:
                  data:
                    cardIdentifier:
                      externalCustomerId: 550e8400-e29b-41d4-a716-446655440000
                      cardLast4: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/UnlockCardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/ForbiddenFraudDeclined'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '428':
          $ref: '#/components/responses/FraudChallenge'
      deprecated: false
  /cards/accounts/{accountId}/lock-card:
    summary: Lock a card for an account
    description: Locks a card based on external customer ID and card last 4 digits with fraud verification
    post:
      tags:
      - Card Controls API
      summary: Lock a card for an account
      description: 'Locks a card based on the provided account ID, external customer ID, and card last 4 digits.

        Performs fraud assessment before locking the card and returns lock status.


        **Business Flow:**

        1. Validates account and customer details via entitlement service

        2. Performs fraud assessment through decision gateway

        3. Locks the card via card control service

        4. Polls for lock confirmation status

        5. Returns lock status with card identifier and customer role


        **Error Scenarios:**

        - 400: Invalid request format or account/customer not found

        - 403: Fraud assessment declined the operation

        - 404: Resource not found

        - 428: Additional fraud verification required (challenge)'
      operationId: lockCard
      parameters:
      - name: Content-Type
        in: header
        description: Content-Type
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 35
          minLength: 16
          pattern: ^[a-z0-9A-Z\/ ]{16,35}$
        example: application/json
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: accountId
        in: path
        description: A unique identifier (UUID format) for the customer account
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: c8de699e-ff6d-11eb-9a03-0242ac130003
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      requestBody:
        description: Card lock request containing the card identifier for fraud assessment and lock operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockCardRequestData'
            examples:
              single-card:
                summary: Single card lock
                value:
                  data:
                    cardIdentifier:
                      externalCustomerId: 550e8400-e29b-41d4-a716-446655440000
                      cardLast4: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LockCardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/ForbiddenFraudDeclined'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '428':
          $ref: '#/components/responses/FraudChallenge'
      deprecated: false
  /cards/accounts/{accountId}/card-lock-status:
    summary: Get card lock/unlock status for all cards in an account
    description: Retrieves the current lock/unlock status for all cards associated with the specified account
    get:
      tags:
      - Card Controls API
      summary: Retrieve lock/unlock status for all cards in the account
      description: 'Returns the lock/unlock status for all cards associated with the specified account,

        including whether each card is currently locked and the customer''s role on the account.


        **Response includes:**

        - Card identifiers (external customer ID and last 4 digits)

        - Customer role on the account (PRIMARY, AUTHORIZED_USER)

        - Lock status for each card (true/false)


        **Use Cases:**

        - Display card lock/unlock status in customer portal

        - Verify card lock state before performing operations

        - Support agent inquiry for card control status'
      operationId: getCardControlStatus
      parameters:
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: accountId
        in: path
        description: A unique identifier (UUID format) for the customer account
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: c8de699e-ff6d-11eb-9a03-0242ac130003
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/CardControlStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      deprecated: false
components:
  examples:
    example-error-403_FRAUD_DECLINED:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: FRAUD_DECLINED
          title: The user is not permitted to access the requested operation and it cannot be completed
          detail: The user is not permitted to access the requested operation and it cannot be completed
    example-error-400-bad-request:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: BAD_REQUEST
          title: The request is invalid or not properly formed.
    example-error-428_FRAUD_CHALLENGE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: FRAUD_CHALLENGE
          title: Fraud challenge required
          detail: Fraud challenge required
        meta:
          verificationContextId: A22DFEC1-C5E7-4DD7-99FD-716528EB1FE3
    example-error-403:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: ACCESS_FORBIDDEN
          title: The user is not permitted to access the requested operation and it cannot be completed.
    example-error-500:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error.
    example-error-404:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found.
    example-error-401:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: AUTHENTICATION_ERROR
          title: The user could not be authenticated for this request.
    example-error-503:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
  schemas:
    CardControlStatusDetailType:
      type: object
      additionalProperties: false
      description: Lock/unlock status details for a single card
      properties:
        cardIdentifier:
          $ref: '#/components/schemas/CardIdentifier'
        customerRole:
          type: string
          description: Customer's role on the account (e.g., PRIMARY, AUTHORIZED_USER)
          example: PRIMARY
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z_]{1,50}$
        isLock:
          type: boolean
          default: false
          description: Indicates if the card is currently locked (true) or unlocked (false)
          example: true
      required:
      - cardIdentifier
      - customerRole
      - isLock
    CardControlStatusDetailList:
      type: array
      description: List of lock/unlock status for each card in the account
      items:
        $ref: '#/components/schemas/CardControlStatusDetailType'
      maxItems: 100
      minItems: 0
    UnlockCardRequestDataItem:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Card unlock request payload containing the card to unlock.


        **Purpose:**

        - Identify the card to unlock using external customer ID and card last 4 digits

        - Used as input for fraud assessment and card unlock operation

        '
      properties:
        cardIdentifier:
          $ref: '#/components/schemas/CardIdentifier'
      required:
      - cardIdentifier
      nullable: false
    ErrorResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'An API error response.

        '
      properties:
        meta:
          type: object
          additionalProperties: true
          description: Contains Non-standard meta information
        errors:
          type: array
          description: 'Contains one or more error messages and is mutually exclusive with the data item.

            This will not be returned in success scenarios.

            '
          items:
            $ref: '#/components/schemas/ErrorType'
          maxItems: 50
          minItems: 0
      nullable: false
    LockUnlockCardDetailType:
      type: object
      additionalProperties: false
      description: Card lock/unlock result details for a single card
      properties:
        cardIdentifier:
          $ref: '#/components/schemas/CardIdentifier'
        customerRole:
          type: string
          description: Customer's role on the account (e.g., PRIMARY, AUTHORIZED_USER)
          example: PRIMARY
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z_]{1,50}$
        isLock:
          type: boolean
          description: Indicates if the card is currently locked (true) or unlocked (false)
          example: true
    CardIdentifier:
      type: object
      additionalProperties: false
      description: Unique card identifier using external customer ID and last 4 digits
      properties:
        externalCustomerId:
          type: string
          format: uuid
          description: External customer identifier in UUID format
          example: 550e8400-e29b-41d4-a716-446655440000
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        cardLast4:
          type: string
          description: Last 4 digits of the card number
          example: '1234'
          maxLength: 4
          minLength: 4
          pattern: ^[0-9]{4}$
      required:
      - cardLast4
      - externalCustomerId
    UnlockCardResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response data containing the result of a card unlock operation.


        **Response Structure:**

        - Returns unlock status for the requested card

        - Includes card identifier to match request to response

        - Shows customer role on the account (PRIMARY, AUTHORIZED_USER)

        - Indicates unlock result via isLock flag (false when unlocked)


        **Use Cases:**

        - Confirm card was successfully unlocked

        - Display unlock confirmation to customer

        - Update UI to reflect new card unlock state

        '
      properties:
        data:
          $ref: '#/components/schemas/UnlockCardControlResponseDataItem'
      nullable: false
    LockCardResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response data containing the result of a card lock operation.


        **Response Structure:**

        - Returns lock status for the requested card

        - Includes card identifier to match request to response

        - Shows customer role on the account (PRIMARY, AUTHORIZED_USER)

        - Indicates lock result via isLock flag (true when locked)


        **Use Cases:**

        - Confirm card was successfully locked

        - Display lock confirmation to customer

        - Update UI to reflect new card lock state

        '
      properties:
        data:
          $ref: '#/components/schemas/LockCardControlResponseDataItem'
      nullable: false
    CardControlStatusResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response data containing lock/unlock status for all cards in the account.


        **Response Structure:**

        - Returns status for all cards associated with the account

        - Includes both locked and unlocked cards

        - Shows card identifiers (external customer ID and last 4 digits)

        - Indicates customer role for each card


        **Use Cases:**

        - Display all cards and their lock/unlock status in customer portal

        - Verify card lock state before performing operations

        - Support agent inquiry for account card status

        '
      properties:
        data:
          $ref: '#/components/schemas/CardControlStatusResponseDataItem'
      nullable: false
    UnlockCardControlResponseDataItem:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response containing unlock result for a single card.


        **Response Structure:**

        - Contains card identifier, customer role, and lock status

        - isLock will be false after a successful unlock operation

        '
      properties:
        lockUnlockCardDetailType:
          $ref: '#/components/schemas/LockUnlockCardDetailType'
      nullable: false
    ErrorType:
      type: object
      additionalProperties: true
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 9709-4675-2456-7801
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9\-]{1,50}$
        code:
          type: string
          description: Machine readable, unique code of the message related to particular case within operation execution.
          example: ACCOUNT_NUMBER_NOT_FOUND
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        title:
          type: string
          description: Short description of the error. Not for displaying purposes.
          example: The authorization credentials required for this request are invalid.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
        detail:
          type: string
          description: Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
        meta:
          type: object
          additionalProperties: true
          description: Object containing non-standard meta-information about the error.
      required:
      - code
      - id
      - title
    LockCardRequestData:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Request data for locking a card with fraud assessment.


        **Purpose:**

        - Lock a card by providing card identifier (external customer ID and card last 4 digits)

        - Fraud verification is performed before the lock operation


        **Validation:**

        - Card identifier must be valid and associated with the account

        - Account must exist and have active customers

        - Fraud assessment must approve the operation before proceeding

        '
      properties:
        data:
          $ref: '#/components/schemas/LockCardRequestDataItem'
      required:
      - data
      nullable: false
    UnlockCardRequestData:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Request data for unlocking a card with fraud assessment.


        **Purpose:**

        - Unlock a card by providing card identifier (external customer ID and card last 4 digits)

        - Fraud verification is performed before the unlock operation


        **Validation:**

        - Card identifier must be valid and associated with the account

        - Account must exist and have active customers

        - Fraud assessment must approve the operation before proceeding

        '
      properties:
        data:
          $ref: '#/components/schemas/UnlockCardRequestDataItem'
      required:
      - data
      nullable: false
    LockCardControlResponseDataItem:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response containing lock result for a single card.


        **Response Structure:**

        - Contains card identifier, customer role, and lock status

        - isLock will be true after a successful lock operation

        '
      properties:
        lockUnlockCardDetailType:
          $ref: '#/components/schemas/LockUnlockCardDetailType'
      nullable: false
    LockCardRequestDataItem:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Card lock request payload containing the card to lock.


        **Purpose:**

        - Identify the card to lock using external customer ID and card last 4 digits

        - Used as input for fraud assessment and card lock operation

        '
      properties:
        cardIdentifier:
          $ref: '#/components/schemas/CardIdentifier'
      required:
      - cardIdentifier
      nullable: false
    CardControlStatusResponseDataItem:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'Response containing lock/unlock status for all cards in the account.


        **Response Structure:**

        - Returns a list of all cards and their current lock/unlock status

        - Each entry includes card identifier, customer role, and lock state

        '
      properties:
        cardControlStatusList:
          $ref: '#/components/schemas/CardControlStatusDetailList'
      nullable: false
  headers:
    Correlation-ID-ResHeader:
      description: 'Unique end-to-end trace ID. The initiating system (such as a Channel or

        Batch Job), must generate this unique ID, then this must be passed

        through the API call stack. This is required to maintain compliance with the current Barclays REST Standard.

        '
      required: true
      schema:
        type: string
        deprecated: false
        maxLength: 36
        minLength: 36
        pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        nullable: false
      example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
    Cache-Control:
      description: GIS mandatory response header. This is added by the Cognac sidecar.
      schema:
        type: string
        default: no-cache, no-store, must-revalidate
        deprecated: false
        example: no-cache, no-store, must-revalidate
        maxLength: 35
        minLength: 35
        pattern: ^no-cache, no-store, must-revalidate$
        nullable: false
  responses:
    Unauthorized:
      description: 'The user could not be authenticated for this request.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-401:
              $ref: '#/components/examples/example-error-401'
    UnlockCardResponse:
      description: Successful card unlock response
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID-ResHeader'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnlockCardResponseData'
          examples:
            successful-unlock:
              summary: Successful card unlock
              value:
                data:
                  lockUnlockCardDetailType:
                    cardIdentifier:
                      externalCustomerId: 550e8400-e29b-41d4-a716-446655440000
                      cardLast4: '1234'
                    customerRole: PRIMARY
                    isLock: false
    LockCardResponse:
      description: Successful card lock response
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID-ResHeader'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LockCardResponseData'
          examples:
            successful-lock:
              summary: Successful card lock
              value:
                data:
                  lockUnlockCardDetailType:
                    cardIdentifier:
                      externalCustomerId: 550e8400-e29b-41d4-a716-446655440000
                      cardLast4: '1234'
                    customerRole: PRIMARY
                    isLock: true
    FraudChallenge:
      description: 'Fraud challenge required

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            FraudChallenge:
              $ref: '#/components/examples/example-error-428_FRAUD_CHALLENGE'
    ServiceUnavailable:
      description: "temporary maintenance of service, try again later. The implication \nis that this is a temporary condition which will be alleviated \nafter some delay. If known, the length of the delay will be \nindicated in a Retry-After header. If no Retry-After is given, \nthe client SHOULD handle the response as it would for a 500 response. \nNote: The existence of the 503 status code does not imply that a \nserver will use it when becoming overloaded. Servers may simply \nrefuse the connection.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-503:
              $ref: '#/components/examples/example-error-503'
    ForbiddenFraudDeclined:
      description: 'The user is not permitted to access the requested operation and it cannot be completed.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            Forbidden:
              $ref: '#/components/examples/example-error-403'
            FraudDeclined:
              $ref: '#/components/examples/example-error-403_FRAUD_DECLINED'
    CardControlStatusResponse:
      description: Successful lock/unlock status response
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID-ResHeader'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CardControlStatusResponseData'
          examples:
            successful-status:
              summary: Successful status retrieval
              value:
                data:
                  cardControlStatusList:
                  - cardIdentifier:
                      externalCustomerId: 550e8400-e29b-41d4-a716-446655440000
                      cardLast4: '1234'
                    customerRole: PRIMARY
                    isLock: true
                  - cardIdentifier:
                      externalCustomerId: 7d444840-9dc0-11d1-b245-5ffdce74fad2
                      cardLast4: '5678'
                    customerRole: AUTHORIZED_USER
                    isLock: false
    NotFound:
      description: "Server has not found a resource with that URI. This may be \ntemporary and permanent condition. This status code is \ncommonly used when the server does not wish to reveal \nexactly why the request has been refused, or when no other \nresponse is applicable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-404:
              $ref: '#/components/examples/example-error-404'
    Forbidden:
      description: 'The user is not permitted to access the requested operation and it cannot be completed.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-403:
              $ref: '#/components/examples/example-error-403'
    InternalServerError:
      description: "Server encountered an error processing request. This should not \nhappen normally, but it is a generic error message, given when \nno more specific message is suitable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-500:
              $ref: '#/components/examples/example-error-500'
    BadRequest:
      description: "The request could not be understood by the server due to malformed \nsyntax. The client SHOULD NOT repeat the request without \nmodifications.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-400-bad-request:
              $ref: '#/components/examples/example-error-400-bad-request'
  securitySchemes:
    ExternalTiaaUsCCAuth:
      type: oauth2
      description: OAuth2.0 Client Credentials Grant authentication using TIAA-US for external APIs
      flows:
        clientCredentials:
          tokenUrl: https://token.tiaa-dev.us.barclays.intranet:8443/as/token.oauth2
          scopes:
            read: read only
            write: write only