openapi: 3.2.0
info:
  title: Benefits Redemption Rewards Redemption Capabilities API
  description: Enables users to view and redeem their rewards
  version: '3.0'
tags:
- name: Rewards-Redemption-Capabilities
paths:
  /cards/accounts/external/{externalAccountID}/redemption/capabilities:
    summary: Retrieves the available external redemption capabilities for an account.
    description: Retrieves the available external redemption capabilities for an account.
    get:
      tags:
      - Rewards-Redemption-Capabilities
      summary: Get external redemption capabilities
      description: Retrieves the external redemption capabilities for an account.
      operationId: getRedemptionCapabilities
      parameters:
      - name: Correlation-ID
        in: header
        description: 'Unique identifier for each incoming request. The API caller must pass this in the header, which will be cascaded through the API call stack.

          This is required to maintain compliance with the current Barclays REST standards.'
        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: externalAccountID
        in: path
        description: A unique id (similar to UUID) created for each customer account.
        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}$
        example: 0dbcb7ee-6c59-483b-966a-44d11557665b
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/RedemptionCapabilitiesResponse'
        '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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      deprecated: false
components:
  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
    RedemptionRule:
      type: object
      additionalProperties: false
      deprecated: false
      description: Defined rule for the redemption type.
      properties:
        ruleId:
          type: string
          description: Unique identifier for the rule.
          example: '100005000000'
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,50}$
        ruleName:
          type: string
          description: Name of the rule.
          example: Samsung Cashback Rule
          maxLength: 50
          minLength: 1
          pattern: ^.{1,50}$
        conversionRate:
          type: number
          description: Conversion rate for the redemption.
          example: 1
        minRedeem:
          type: number
          description: Minimum amount that can be redeemed.
          example: 1500
        maxRedeem:
          type: number
          description: Maximum amount that can be redeemed.
          example: 5000
      required:
      - conversionRate
      - maxRedeem
      - minRedeem
      - ruleId
      - ruleName
      nullable: false
    ErrorType:
      type: object
      additionalProperties: false
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 1c4717c4-d4a5-e3f3-4a71-b868908763ff
          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}$
        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}$
      required:
      - code
      - id
      - title
    RedemptionCapabilitiesResponse:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains redemption eligibility information based on available redemption options for a specific external account.
      properties:
        partnerProductBrandId:
          type: string
          description: Unique identifier for the partner product brand.
          example: 4f9d630a-249b-474f-9efa-6a03b4dd407c
          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}$
        partnerProductBrandName:
          type: string
          description: Name of the partner product brand.
          example: SMG001
          maxLength: 6
          minLength: 6
          pattern: ^[a-zA-Z0-9]{6}$
        rewardType:
          type: string
          description: Rewards currency type
          example: POINTS
          maxLength: 10
          minLength: 1
          pattern: ^[a-zA-Z]{1,10}$
        rewardCurrencyDisplayName:
          type: string
          description: Display name of the reward type.
          example: Rewards
          maxLength: 50
          minLength: 1
          pattern: ^.{1,50}$
        isCashBased:
          type: boolean
          description: Indicates if the reward type is cash-based.
          example: true
        cashCapabilities:
          type: array
          description: List of cash-based redemption capabilities.
          items:
            $ref: '#/components/schemas/CashCapability'
          maxItems: 10
          minItems: 1
        nonCashCapabilities:
          type: array
          description: List of non-cash redemption capabilities.
          items:
            type: object
            additionalProperties: true
          maxItems: 10
          minItems: 1
          nullable: true
      required:
      - cashCapabilities
      - isCashBased
      - partnerProductBrandId
      - partnerProductBrandName
      - rewardCurrencyDisplayName
      - rewardType
      nullable: false
    RedemptionCapabilitiesResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: Redemption Capabilities Response Data
      properties:
        data:
          $ref: '#/components/schemas/RedemptionCapabilitiesResponse'
      required:
      - data
      nullable: false
    FulfillmentMethod:
      type: object
      additionalProperties: false
      deprecated: false
      description: Fulfillment method for the redemption type.
      properties:
        fulfillmentMethod:
          type: string
          description: Method of fulfillment.
          example: STMNT_CR
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z_]{1,50}$
        capAmount:
          type: number
          description: Maximum amount that can be redeemed per cap period.
          example: 50
        capPeriod:
          type: string
          description: Period for the cap amount.
          example: DAY
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z_]{1,50}$
      required:
      - fulfillmentMethod
      nullable: false
    CashCapability:
      type: object
      additionalProperties: false
      deprecated: false
      description: Details about the cash-based redemption capability.
      properties:
        redemptionType:
          type: string
          description: Type of redemption.
          example: CASH_BACK
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z_]{1,50}$
        redemptionTypeId:
          type: string
          description: Unique identifier for the redemption type.
          example: 6070de43-c712-4902-9077-0a69b691eaea
          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}$
        redemptionTypeName:
          type: string
          description: Name for the redemption type.
          example: Samsung Cashback
          maxLength: 100
          minLength: 1
          pattern: ^.{1,100}$
        fulfillmentMethods:
          type: array
          description: Available fulfillment methods for the redemption type.
          items:
            $ref: '#/components/schemas/FulfillmentMethod'
          maxItems: 5
          minItems: 1
        rules:
          type: array
          description: Defined rules for the redemption type.
          items:
            $ref: '#/components/schemas/RedemptionRule'
          maxItems: 20
          minItems: 1
      required:
      - fulfillmentMethods
      - redemptionType
      - redemptionTypeId
      - redemptionTypeName
      - rules
      nullable: false
  examples:
    example-error-429:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: TOO_MANY_REQUESTS
          title: Too many requests
          detail: The client sent too many requests and server is not able to serve them all at the moment
    example-error-403:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: ACCESS_FORBIDDEN
          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
    ResponseWithOnlyCashRedemptionCapabilities:
      value:
        data:
          partnerProductBrandId: 4f9d630a-249b-474f-9efa-6a03b4dd407c
          partnerProductBrandName: SMG001
          rewardType: Cash
          rewardCurrencyDisplayName: Rewards
          isCashBased: true
          cashCapabilities:
          - redemptionType: CASH_BACK
            redemptionTypeId: 6070de43-c712-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung Cashback
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            - fulfillmentMethod: RW_ACH
              capAmount: 500
              capPeriod: DAY
            rules:
            - ruleId: '100005000000'
              ruleName: Samsung Cashback Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
          - redemptionType: PAY_WITH_POINTS
            redemptionTypeId: 6070de43-c713-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung Wallet Pay
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            rules:
            - ruleId: '100006000000'
              ruleName: Samsung Wallet Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
          - redemptionType: PAY_YOURSELF_BACK
            redemptionTypeId: 6070de43-c711-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung PYB
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            rules:
            - ruleId: '100007000000'
              ruleName: Samsung PYB Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
    ResponseWithAllRedemptionCapabilities:
      value:
        data:
          partnerProductBrandId: 4f9d630a-249b-474f-9efa-6a03b4dd407c
          partnerProductBrandName: SMG001
          rewardType: Cash
          rewardCurrencyDisplayName: Rewards
          isCashBased: true
          cashCapabilities:
          - redemptionType: CASH_BACK
            redemptionTypeId: 6070de43-c712-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung Cashback
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            - fulfillmentMethod: RW_ACH
              capAmount: 500
              capPeriod: DAY
            rules:
            - ruleId: '100005000000'
              ruleName: Samsung Cashback Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
          - redemptionType: PAY_WITH_POINTS
            redemptionTypeId: 6070de43-c713-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung Wallet Pay
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            rules:
            - ruleId: '100006000000'
              ruleName: Samsung Wallet Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
          - redemptionType: PAY_YOURSELF_BACK
            redemptionTypeId: 6070de43-c711-4902-9077-0a69b691eaea
            redemptionTypeName: Samsung PYB
            fulfillmentMethods:
            - fulfillmentMethod: STMNT_CR
              capAmount: 50
              capPeriod: DAY
            rules:
            - ruleId: '100007000000'
              ruleName: Samsung PYB Rule
              conversionRate: 1
              minRedeem: 1500
              maxRedeem: 5000
          nonCashCapabilities:
          - {}
    example-error-500:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error
          detail: Downstream service call failure while retrieving rewards balance
    example-error-401:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: UNAUTHORIZED
          title: The authorization credentials required for this request are invalid
          detail: The authorization credentials required for this request are invalid
    example-error-503:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
          detail: Scheduled service outage starting from Wednesday, 04 Jul 2050 0100 GMT until Wednesday, 04 Jul 2050 0500 GMT
    example-error-404:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found
          detail: Couldn't locate the account
    example-error-400-bad-request:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BAD_REQUEST
          title: The request is invalid or not properly formed
          detail: Invalid request, field name does not match with the API spec
  responses:
    BadRequest:
      description: 'The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            BadRequest:
              $ref: '#/components/examples/example-error-400-bad-request'
    InternalServerError:
      description: 'Server encountered an error during processing the request. It''s s a generic error message, given when a more specific message is not available.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            InternalServerError:
              $ref: '#/components/examples/example-error-500'
    ServiceUnavailable:
      description: 'Temporary maintenance of service, try again later. This is a temporary condition which will be alleviated after some delay.

        '
      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 was unable to locate a resource to complete the operation. This may be temporary or permanent.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            NotFound:
              $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:
            Forbidden:
              $ref: '#/components/examples/example-error-403'
    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'
    TooManyRequests:
      description: 'Server received a large number of requests from a single party in a given amount of time. Client is advised to retry after the agreed cool down period.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            TooManyRequests:
              $ref: '#/components/examples/example-error-429'
    RedemptionCapabilitiesResponse:
      description: Redemption capabilities Response Data
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RedemptionCapabilitiesResponseData'
          examples:
            ResponseWithAllRedemptionCapabilities:
              $ref: '#/components/examples/ResponseWithAllRedemptionCapabilities'
            ResponseWithOnlyCashRedemptionCapabilities:
              $ref: '#/components/examples/ResponseWithOnlyCashRedemptionCapabilities'
  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