openapi: 3.1.0
info:
  title: Card Control
  description: Enables customers to securely lock and unlock credit cards
  version: '1.0'
x-method: searched
x-source: https://developer.barclays.com/api/apis/versions/fb39ed1a-d10a-47f7-92bb-7ecbb6bbe39e.bdn/design?specification=oas31
x-harvested: '2026-09-04'
x-harvested-note: Verbatim OpenAPI 3.1 design export from the Barclays API Exchange registry (developer.barclays.com), fetched
  anonymously. The untouched export is in openapi/_original/barclays-card-control-openapi.json. The UK Open Banking documents
  carry OBIE (openbanking.org.uk) in info.contact/termsOfService because they are the OBIE standard contract as Barclays implements
  and publishes it — the API, the registry record and the host are Barclays'.
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:
  schemas:
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    CardControlStatusDetailList:
      type: array
      description: List of lock/unlock status for each card in the account
      items:
        $ref: '#/components/schemas/CardControlStatusDetailType'
      maxItems: 100
      minItems: 0
    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
    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
    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
  responses:
    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'
    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'
    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'
    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'
    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
    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'
    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'
    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'
    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
    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
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: Bearer Token
      required: true
      deprecated: false
      allowEmptyValue: false
      schema:
        type: string
        maxLength: 2048
        minLength: 32
        pattern: ^[A-Za-z0-9\-_\.\ ]{32,2048}$
      example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IlE4SkRobnd0ODU4eDNlbTRwVVkzd0R2Q3RsRSIsInBpLmF0bSI6IjUybWUifQ.eyJjbGllbnRfaWQiOiJVU0NCSU5UQ0xJRU5UIiwiaXNzIjoiVElBQS1VUyIsImF1ZCI6IlVTQ0IiLCJzdWIiOiJzeXNUSUFBVVNBUFBMWVQiLCJhZGdyb3VwcyI6WyJDTj1mR0xCQ3VzdFByb2R1Y3RITlAsT1U9R3JvdXBzLE9VPUdMQixEQz1JTlRSQU5FVCxEQz1CQVJDQVBJTlQsREM9Y29tIiwiQ049ZkdMQkNycHRQY3NHYXBRQSxPVT1Hcm91cHMsT1U9R0xCLERDPUlOVFJBTkVULERDPUJBUkNBUElOVCxEQz1jb20iLCJDTj1mR0xCQWNjdE1nbXROUCxPVT1Hcm91cHMsT1U9R0xCLERDPUlOVFJBTkVULERDPUJBUkNBUElOVCxEQz1jb20iLCJDTj1mR0xCVElBQVVTQ0JJbnRyUyxPVT1Hcm91cHMsT1U9R0xCLERDPUlOVFJBTkVULERDPUJBUkNBUElOVCxEQz1jb20iXSwiZXhwIjoxNjgzMjYyNzk3fQ.JDw6udt7pegvyz2tD_W0gUR_FXr7XnZIMnb0GeXLGFC7Zcg5yq6vI2bTMaee9pNhtCEJlIbLa5aKvP6xdt1xBfusE74g85Tohb5c-4MF7QNsC3vBCNOlTpnXMPkHR2_aNfXzf_Duvf81ZotsD_KwUF7w8f63BHgpI4itiFSduGEFGzAKlV2OJwcgIIlhDfhstbDtREL931QlFI8v_sj7JjXWOqivrFSOhiuen-rM5SRvFrnm50P9mZvyhs4-228cZ-xv36c5NAsbO9whQCHE5N0rDOhMgCKl65rnCdUr8rktOCe3fMQTWxV-qQqnr4hscgFtcJt9gU07pwP8zvf4xQ
    Correlation-ID:
      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.\n"
      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
    X-Party-Id:
      name: X-Party-Id
      in: header
      description: 'Party ID of customer associated to an account Id

        '
      required: true
      deprecated: false
      allowEmptyValue: false
      schema:
        type: string
        maxLength: 17
        minLength: 1
        pattern: ^[0-9]{1,17}$
      example: '100145000'
    ExternalAccountIdPath:
      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
    OauthClient-ID:
      name: oauth_clientid
      in: header
      description: 'To be set by Akana ND. It will be removed when published on Akana,

        '
      required: true
      deprecated: false
      allowEmptyValue: false
      schema:
        type: string
        maxLength: 256
        minLength: 1
        pattern: ^[a-zA-Z0-9.\-]{1,256}$
      example: bdn-68EwxNCdDi65Y2FV6wxupfsoD3ilveYxDqok0LD5
    X-Auth-Type:
      name: X-Auth-Type
      in: header
      description: 'X-AuthType injected by AKANA ND.

        Denotes how the token was issued - client-creds/auth-grant

        '
      required: true
      deprecated: false
      allowEmptyValue: false
      schema:
        type: string
        description: Denotes how the token was issued - client-creds/auth-grant
        enum:
        - auth-grant
        - client-creds
      example: auth-grant
    X-IDVSessionID:
      name: X-IDVSessionID
      in: header
      description: 'X-IDVSessionID injected by AKANA ND

        '
      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: 6c9b83bc-5c94-45c8-a594-5ea890409b62
    Content-Type:
      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
  examples:
    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-503:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
    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-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-400-bad-request:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: BAD_REQUEST
          title: The request is invalid or not properly formed.
    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-500:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error.
    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.
  requestBodies:
    LockCardRequest:
      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
    UnlockCardRequest:
      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
  headers:
    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
    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
  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