openapi: 3.2.0
info:
  title: Payments Payment Product External API External Account API
  description: Enables customers to easily create, update, or cancel payments
  version: '2.0'
tags:
- name: paymentProductExternalAPI-ExternalAccount
  description: OAS3 External Account APIs
paths:
  /cards/accounts/{extAccountId}/payments/external-accounts/{bankAccountId}:
    summary: External Bank Account management for a given external bank account ID from Partner
    description: Offers external bank management options for a given external bank account ID
    get:
      tags:
      - paymentProductExternalAPI-ExternalAccount
      summary: Get an external bank account for partner provided external bank account ID
      description: Get an external bank account configured for a user
      operationId: getExternalAccountV2
      parameters:
      - name: extAccountId
        in: path
        description: External Account ID received from the partner
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^c[\d]{1,12}$|^m[\d]{1,20}$
        example: e17e3338-344b-403c-8a87-f7d8006d6e33
      - name: bankAccountId
        in: path
        description: Internal sequence number generated for external account
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 12
          minLength: 1
          pattern: ^[0-9]{1,12}$
        example: 0013467801
      - 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: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/ExternalAccountResLast4'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      deprecated: false
  /cards/accounts/{extAccountId}/payments/external-accounts:
    summary: External Bank Account management
    description: Offers external bank account management
    get:
      tags:
      - paymentProductExternalAPI-ExternalAccount
      summary: Get all external bank accounts for partner provided accountId
      description: Get all external bank accounts configured for a user.
      operationId: getAllExternalAccountsV2
      parameters:
      - name: extAccountId
        in: path
        description: External Account ID received from the partner
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^c[\d]{1,12}$|^m[\d]{1,20}$
        example: e17e3338-344b-403c-8a87-f7d8006d6e33
      - 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: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/AllExternalAccountsResLast4'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      deprecated: false
components:
  responses:
    AllExternalAccountsResLast4:
      description: Gets all external bank accounts
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetAllExternalAccountsResponseDataLast4'
          examples:
            AllExternalAccountsRes:
              $ref: '#/components/examples/AllExternalAccountsResLast4'
    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:
            InternalServerError:
              $ref: '#/components/examples/example-error-500'
    ExternalAccountResLast4:
      description: Get an external bank account
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetExternalAccountResponseDataLast4'
          examples:
            ExternalAccountRes:
              $ref: '#/components/examples/ExternalAccountResLast4'
    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:
            ServiceUnavailable:
              $ref: '#/components/examples/example-error-503'
    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:
            NotFound:
              $ref: '#/components/examples/example-error-404'
    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:
            Unauthorized:
              $ref: '#/components/examples/example-error-401'
  examples:
    ExternalAccountResLast4:
      value:
        data:
          bankDetails:
            bankRoutingNumber: '037736634'
            isValidBank: false
            bankNewRoutingNumber: '908982053'
            bankName: TD RETAIL CARD SERVICES
          bankAccountNickname: 'BX)#C8) '
          bankAccountId: '414'
          bankAccountNumberLast4: '4513'
          bankAccountType: SAVINGS
    AllExternalAccountsResLast4:
      value:
        data:
        - bankDetails:
            bankRoutingNumber: '397827963'
            isValidBank: false
            bankNewRoutingNumber: '863153389'
            bankName: TD RETAIL CARD SERVICES
          bankAccountNickname: 79n#9vn5#)
          bankAccountId: 08
          bankAccountNumberLast4: '4110'
          bankAccountType: SAVINGS
    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-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
    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.
  schemas:
    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
    BankAccountNumberLast4:
      type: string
      deprecated: false
      description: Last 4 digits of Bank account number to be added as a payment source
      example: '1234'
      maxLength: 4
      minLength: 4
      pattern: ^([a-zA-Z0-9]{4,4})$
    BankName:
      type: string
      deprecated: false
      description: Bank name of the bank account added as payment source
      example: bankName
      maxLength: 255
      minLength: 1
      pattern: ^([A-Za-z0-9 &,.'#+$=()_/-]{1,255})$
    BankAccountType:
      type: string
      deprecated: false
      description: Account type of the bank account used as payment source
      enum:
      - CHECKING
      - SAVINGS
      example: CHECKING
      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
    ExternalBankDetails:
      type: object
      additionalProperties: false
      deprecated: false
      properties:
        bankName:
          $ref: '#/components/schemas/BankName'
        isValidBank:
          type: boolean
          deprecated: false
          description: Signifies the validity of the bank routing number
          example: false
          nullable: false
        bankNewRoutingNumber:
          $ref: '#/components/schemas/BankRoutingNumber'
        bankRoutingNumber:
          $ref: '#/components/schemas/BankRoutingNumber'
    GetAllExternalAccountsResponseDataLast4:
      type: object
      additionalProperties: false
      deprecated: false
      description: All external bank accounts response data
      properties:
        data:
          $ref: '#/components/schemas/ExternalAccountListLast4'
      required:
      - data
      nullable: false
    GetExternalAccountResponseDataLast4:
      type: object
      additionalProperties: false
      deprecated: false
      description: external bank account response data
      properties:
        data:
          $ref: '#/components/schemas/ExternalAccountLast4'
      required:
      - data
      nullable: false
    BankRoutingNumber:
      type: string
      deprecated: false
      description: Bank routing number of the bank account added as payment source
      example: '123455645'
      maxLength: 9
      minLength: 9
      pattern: ^([0-9]{9})$
    ExternalAccountListLast4:
      type: array
      additionalProperties: false
      deprecated: false
      description: Get all external account list
      items:
        $ref: '#/components/schemas/ExternalBankAccountDetailsLast4'
      maxItems: 2000
      minItems: 0
      nullable: false
    ExternalAccountLast4:
      type: object
      additionalProperties: false
      deprecated: false
      description: Get all external account response
      properties:
        bankDetails:
          $ref: '#/components/schemas/ExternalBankDetails'
        bankAccountNickname:
          $ref: '#/components/schemas/BankAccountNickname'
        bankAccountId:
          $ref: '#/components/schemas/BankAccountId'
        bankAccountNumberLast4:
          $ref: '#/components/schemas/BankAccountNumberLast4'
        bankAccountType:
          $ref: '#/components/schemas/BankAccountType'
      nullable: false
    BankAccountId:
      type: string
      deprecated: false
      description: ID of bank account added as payment source
      example: '123456789'
      maxLength: 12
      minLength: 1
      pattern: ^([0-9]{1,12})$
      nullable: false
    BankAccountNickname:
      type: string
      deprecated: false
      description: Nickname for bank account added as payment source
      example: ASHES
      maxLength: 24
      minLength: 1
      pattern: ^([a-zA-Z0-9 .,&()#'-]{1,24})$
      nullable: false
    ExternalBankAccountDetailsLast4:
      type: object
      additionalProperties: false
      deprecated: false
      description: Bank account details
      properties:
        bankDetails:
          $ref: '#/components/schemas/ExternalBankDetails'
        bankAccountNickname:
          $ref: '#/components/schemas/BankAccountNickname'
        bankAccountId:
          $ref: '#/components/schemas/BankAccountId'
        bankAccountNumberLast4:
          $ref: '#/components/schemas/BankAccountNumberLast4'
        bankAccountType:
          $ref: '#/components/schemas/BankAccountType'
      nullable: false
  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
  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