Barclays Rewards Redemption API

openapi: 3.2.0
info:
  title: Benefits Redemption Rewards Redemption API
  description: Enables users to view and redeem their rewards
  version: '3.0'
tags:
- name: Rewards-Redemption
paths:
  /cards/accounts/external/{externalAccountID}/rewards/redemption:
    summary: Fulfill statement credit/ACH for the given account and corresponding program attributes.
    description: Deducts rewards from the given account and posts a statement credit/ACH. Returns a redemption id for tracking.
    post:
      tags:
      - Rewards-Redemption
      summary: Fulfill statement credit/ACH for the given account and corresponding program…
      description: Deducts rewards from the given account and posts a statement credit/ACH. Returns a redemption id for tracking.
      operationId: postRewardsRedemption
      parameters:
      - name: Content-Type
        in: header
        description: Content-Type
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 16
          minLength: 16
          pattern: ^[a-z/]{16}$
        example: application/json
      - 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: 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: X-Channel-Id
        in: header
        description: The channel ID of external entity initiating the call.
        required: false
        deprecated: false
        schema:
          type: string
          maxLength: 40
          minLength: 1
          pattern: ^[A-Za-z0-9\-_]{1,40}$
        example: WALLET
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      requestBody:
        description: Contains information required for the redemption operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionRequestDataV3'
            examples:
              RedemptionRequestPayWithPoints:
                $ref: '#/components/examples/RedemptionRequestPayWithPoints'
              RedemptionRequestCashBackStmntCr:
                $ref: '#/components/examples/RedemptionRequestCashBackStmntCr'
              RedemptionRequestCashBackACH:
                $ref: '#/components/examples/RedemptionRequestCashBackACH'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/RedemptionResponseV3'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/500_redemption'
        '403':
          $ref: '#/components/responses/Forbidden_redemption'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '428':
          $ref: '#/components/responses/FraudChallenge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      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-500_BUSINESS_VALIDATION_FAILED:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BUSINESS_VALIDATION_FAILED
          title: Request failed while validating the account
          detail: Request cannot be processed, account validation failure
    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
    RedemptionResponse:
      value:
        data:
          redemptionReferenceNumber: 1c4717c4-e3f3-4a71-8b67-b868908763ff
          redemptionId: '65878787'
          status: COMPLETED
    example-error-500_TEMPORARY_UNPROCESSABLE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: TEMPORARY_UNPROCESSABLE
          title: Request unprocessable momentarily
          detail: Request cannot be processed momentarily
    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: 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
    example-error-500_INSUFFICIENT_BALANCE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: INSUFFICIENT_BALANCE
          title: Insufficient reward balance on the account
          detail: Request cannot be processed due to insufficient reward balance
    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-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-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
    RedemptionRequestCashBackStmntCr:
      value:
        data:
          redemptionReferenceNumber: 1c4717c4-e3f3-4a71-8b67-b868908763ff
          redemptionAmount: 50
          conversionRate: 1
          rewards: 50
          redemptionTypeId: fffb0eab-be1e-4ad7-b776-117b5eacb117
          redemptionType: CASH_BACK
          fulfillmentMethod: STMNT_CR
    example-error-500_ACCOUNT_INELIGIBLE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: ACCOUNT_INELIGIBLE
          title: Account is not eligible for this program
          detail: Request cannot be processed, account is not eligible for this program
    example-error-500_BAD_STATUS_ACCOUNT:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BAD_STATUS_ACCOUNT
          title: Account is in bad status
          detail: Account is in CLOSED status, request cannot be processed
    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-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
    RedemptionRequestCashBackACH:
      value:
        data:
          redemptionReferenceNumber: 2d5817c4-e3f3-4a71-8b67-b868908763aa
          redemptionAmount: 100
          conversionRate: 1
          rewards: 100
          redemptionTypeId: aabbccdd-eeff-1122-3344-556677889900
          redemptionType: CASH_BACK
          fulfillmentMethod: RW_ACH
          externalAccountRefId: '987654321'
    RedemptionRequestPayWithPoints:
      value:
        data:
          redemptionReferenceNumber: 3e6917c4-e3f3-4a71-8b67-b868908763bb
          redemptionAmount: 75
          conversionRate: 1
          rewards: 75
          redemptionTypeId: 11223344-5566-7788-99aa-bbccddeeff00
          redemptionType: PAY_WITH_POINTS
          fulfillmentMethod: STMNT_CR
          transactionInfo:
            authorizationCode: AUTH12345
            transactionDesc: Purchase at Amazon using Pay With Points
  responses:
    500_redemption:
      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:
            INTERNAL_SERVER_ERROR:
              $ref: '#/components/examples/example-error-500'
            BAD_STATUS_ACCOUNT:
              $ref: '#/components/examples/example-error-500_BAD_STATUS_ACCOUNT'
            INSUFFICIENT_BALANCE:
              $ref: '#/components/examples/example-error-500_INSUFFICIENT_BALANCE'
            ACCOUNT_INELIGIBLE:
              $ref: '#/components/examples/example-error-500_ACCOUNT_INELIGIBLE'
            BUSINESS_VALIDATION_FAILED:
              $ref: '#/components/examples/example-error-500_BUSINESS_VALIDATION_FAILED'
            TEMPORARY_UNPROCESSABLE:
              $ref: '#/components/examples/example-error-500_TEMPORARY_UNPROCESSABLE'
    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'
    RedemptionResponseV3:
      description: Contains information about the outcome of the redemption operation for the given account.
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RedemptionResponseDataV3'
          examples:
            RedemptionResponseV3:
              $ref: '#/components/examples/RedemptionResponse'
    Forbidden_redemption:
      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'
    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. 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'
    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'
    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'
    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'
  schemas:
    TransactionInfo:
      type: object
      additionalProperties: false
      description: Optional metadata supplied by partner for pay with points redemption.
      properties:
        authorizationCode:
          type: string
          description: Authorization code generated by merchant at point of sale.
          example: 5R20BK11W6
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,50}$
        transactionDesc:
          type: string
          description: Free-text description of the source transaction tied to redemption.
          example: Online order placed at Expedia.com for a hotel booking
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: true
      nullable: true
    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
    RedemptionResponseDataV3:
      type: object
      additionalProperties: false
      deprecated: false
      description: Root object that holds a redemption id and current rewards balance upon a successful redemption.
      properties:
        data:
          $ref: '#/components/schemas/RedemptionResponseV3'
      required:
      - data
      nullable: false
    RedemptionRequestDataV3:
      type: object
      additionalProperties: false
      deprecated: false
      description: Root object that holds redemption amount and related program attributes.
      properties:
        data:
          $ref: '#/components/schemas/RedemptionRequestV3'
      required:
      - data
      nullable: false
    RedemptionRequestV3:
      type: object
      additionalProperties: false
      deprecated: false
      description: Redemption amount and related program attributes.
      properties:
        redemptionReferenceNumber:
          type: string
          description: UUID to keep track of each redemption request from a partner. Generated by the partner and passed in each request.
          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}$
        redemptionAmount:
          type: number
          description: Dollar value of the rewards to be redeemed. Minimum and Maximum limits depend on program setup.
          example: 50
        conversionRate:
          type: number
          description: 'Denotes the dollar value of rewards (ex: 1 point = $0.01).'
          example: 0.01
        rewards:
          type: number
          description: Quantity of rewards/points consumed for this redemption.
          example: 50
        redemptionTypeId:
          type: string
          description: Unique identifier for the partner product brand.
          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}$
        redemptionType:
          type: string
          description: Type of redemption.
          example: CASH_BACK
          maxLength: 30
          minLength: 1
          pattern: ^[a-zA-Z_]{1,30}$
        fulfillmentMethod:
          type: string
          description: Method of fulfillment.
          example: STMNT_CR
          maxLength: 20
          minLength: 1
          pattern: ^[a-zA-Z_]{1,20}$
        externalAccountRefId:
          type: string
          description: External account reference ID required for ACH-based fulfillment.
          example: '1214534'
          maxLength: 30
          minLength: 1
          pattern: ^[0-9a-zA-Z]{1,30}$
          nullable: true
        transactionInfo:
          $ref: '#/components/schemas/TransactionInfo'
      required:
      - conversionRate
      - fulfillmentMethod
      - redemptionAmount
      - redemptionReferenceNumber
      - redemptionType
      - redemptionTypeId
      - rewards
      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
    RedemptionResponseV3:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains redemption id and status of redemption request.
      properties:
        redemptionReferenceNumber:
          type: string
          description: UUID received in the API request will be sent back in the API response upon a successful redemption.
          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}$
        redemptionId:
          type: string
          description: Unique id generated by Barclays for a redemption.
          example: '142342342'
          maxLength: 20
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,20}$
        status:
          type: string
          description: Redemption status
          enum:
          - ACCEPTED
          - IN_PROCESS
          - COMPLETED
          - FAILURE
          - CANCELLED
          - RETURNED
          example: COMPLETED
      required:
      - redemptionId
      - redemptionReferenceNumber
      - status
      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