openapi: 3.1.0
info:
  title: Client Management API
  description: RAI Partners Client Management API
  license:
    name: Proprietary — © RAI Partners Inc. All rights reserved.
    url: https://www.raipartners.com
  version: 1.0.0
servers:
  - url: https://api.raipartners.com/client-management
    description: Production
  - url: https://api.dev.raipartners.com/client-management
    description: Sandbox
tags:
  - name: Account
    description: Account functions
  - name: Authentication
    description: Authentication functions
paths:
  /accounts:
    get:
      tags:
        - Account
      summary: Retrieve the accounts
      description: Retrieve the accounts associated with the client.
      operationId: streamAccounts
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.0
      responses:
        '200':
          description: >-
            Successful stream of accounts. IMPORTANT: The accounts are returned
            in NDJSON format (one account json object per line), not as an
            array.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/AccountInformation'
        '400':
          description: Bad request.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '401':
          description: Unauthorized.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Unauthorized:
                  description: Unauthorized
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:unauthorized
                    title: Unauthorized
                    status: 401
                    detail: You are not authorized to perform this action.
        '403':
          description: Forbidden.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Forbidden:
                  description: Forbidden
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:forbidden
                    title: Forbidden
                    status: 403
                    detail: You are forbidden to perform this action.
        '404':
          description: not found.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
  /auth/client-secret/rotation:
    post:
      tags:
        - Authentication
      summary: Rotate the client secret
      description: Rotate and return the client secret
      operationId: rotateClientSecret
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.0
      responses:
        '200':
          description: The rotated secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotatedSecret'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Unauthorized:
                  description: Unauthorized
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:unauthorized
                    title: Unauthorized
                    status: 401
                    detail: You are not authorized to perform this action.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Forbidden:
                  description: Forbidden
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:forbidden
                    title: Forbidden
                    status: 403
                    detail: You are forbidden to perform this action.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Authenticate client
      description: Authenticate a client and retrieve the JWT token
      operationId: authenticateClient
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.0
      requestBody:
        description: The client credentials.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientTokenRequest'
        required: true
      responses:
        '200':
          description: The JWT token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTClientTokenResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security: []
  /transactions/{date}:
    get:
      tags:
        - Account
      summary: Retrieve the transactions
      description: Retrieve the transactions across all accounts for the given cycle date.
      operationId: streamTransactions
      parameters:
        - name: date
          in: path
          description: The cycle date for which the transactions are requested
          required: true
          schema:
            type: string
            format: date
          example: '2026-07-31'
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.0
      responses:
        '200':
          description: >-
            Successful stream of transactions. IMPORTANT: The transactions are
            returned in NDJSON format (one transaction json object per line),
            not as an array.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          description: Bad request.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '401':
          description: Unauthorized.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Unauthorized:
                  description: Unauthorized
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:unauthorized
                    title: Unauthorized
                    status: 401
                    detail: You are not authorized to perform this action.
        '403':
          description: Forbidden.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Forbidden:
                  description: Forbidden
                  value:
                    type: >-
                      urn:raipartners:api:clientmanagement:errors:authorization:forbidden
                    title: Forbidden
                    status: 403
                    detail: You are forbidden to perform this action.
        '404':
          description: not found.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:clientmanagement:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
components:
  schemas:
    AccountIdentification:
      type: object
      properties:
        id:
          type: string
          description: The 64 characters account identifier.
          example: f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2
          pattern: '[0-9a-f]{64}'
        number:
          type: string
          description: The 16 digit account number.
          example: '1234567890123456'
          pattern: \d{16}
      required:
        - id
        - number
    AccountInformation:
      type: object
      properties:
        accountIdentification:
          $ref: '#/components/schemas/AccountIdentification'
          description: The account identification.
        status:
          type: string
          description: The account status.
          enum:
            - AuthorizationProhibited
            - Bankrupt
            - ChargeOff
            - Closed
            - Frozen
            - InterestAccrualProhibited
            - Lost
            - Normal
            - Revoked
            - Stolen
          example: Normal
        internalStatus:
          type: string
          description: The account internal status.
          enum:
            - CreditBalance
            - Delinquent
            - DelinquentAndOverLimit
            - Normal
            - OverLimit
          example: Delinquent
        currentBalance:
          type: number
          description: The account current balance.
          example: 1000
        creditLimit:
          type: number
          description: The account credit limit.
          example: 10000
        annualRates:
          $ref: '#/components/schemas/Rates'
          description: The account annual rates.
        openingDate:
          type: string
          format: date
          description: The account opening date.
          example: '2022-01-31'
        paymentDueDate:
          type:
            - string
            - 'null'
          format: date
          description: The account payment due date.
          example: '2022-02-01'
        nextCycleDate:
          type: string
          format: date
          description: The account next cycle date.
          example: '2022-03-01'
        cycleToDatePaymentPosted:
          type: number
          description: The account cycle to date payment amount posted.
          example: 1000
        lastStatementPaymentAmount:
          type: number
          description: The account last statement payment amount.
          example: 1000
        primaryCardholder:
          $ref: '#/components/schemas/Individual'
          description: The account primary cardholder.
        secondaryCardholder:
          oneOf:
            - $ref: '#/components/schemas/Individual'
            - type: 'null'
      required:
        - accountIdentification
        - annualRates
        - creditLimit
        - currentBalance
        - cycleToDatePaymentPosted
        - internalStatus
        - lastStatementPaymentAmount
        - nextCycleDate
        - openingDate
        - primaryCardholder
        - status
    Individual:
      type: object
      properties:
        ssnId:
          type: string
          description: The individual social security number identifier.
          example: b2ce1ee6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2
          pattern: '[0-9a-f]{64}'
        ssn:
          type: string
          description: The 9 digit social security number.
          example: '123456789'
          pattern: \d{9}
        name:
          type: string
          description: The individual name.
          example: Doe, John
          maxLength: 50
          minLength: 5
        dob:
          type: string
          format: date
          description: The individual date of birth.
          example: '1970-01-01'
      required:
        - dob
        - name
        - ssn
        - ssnId
    Rates:
      type: object
      properties:
        cash:
          type: number
          description: The cash rate in percent.
          example: 19.99
        merchandise:
          type: number
          description: The merchandise rate in percent.
          example: 12.99
      required:
        - cash
        - merchandise
    ProblemDetail:
      type: object
      properties:
        type:
          type:
            - string
            - 'null'
          format: uri
          description: The URI of the problem type
          example: urn:raipartners:api
        title:
          type:
            - string
            - 'null'
          description: The title of the problem
          example: Bad Request
        status:
          type: integer
          format: int32
          description: The status code of the problem
          example: 400
        detail:
          type:
            - string
            - 'null'
          description: The details of the problem
          example: One or more required fields are missing.
        instance:
          type:
            - string
            - 'null'
          format: uri-reference
          description: The instance of the problem
          example: /account/12345/errors/abc-987
        properties:
          type:
            - object
            - 'null'
          additionalProperties: {}
          description: extra properties to enhance information about the problem
      required:
        - status
    RotatedSecret:
      type: object
      description: Client rotated secret
      properties:
        secret:
          type: string
          description: The new client secret.
          example: PX4eWb9rcRT1RBqvLw4GtuqyoUFWoGLr
      required:
        - secret
    ClientTokenRequest:
      type: object
      description: A client token request payload
      properties:
        client_id:
          type: string
          description: The client ID to use for authentication
          example: my-client-id
        client_secret:
          type: string
          description: The client secret to use for authentication
          example: my-super-auth-secret
      required:
        - client_id
        - client_secret
    JWTClientTokenResponse:
      type: object
      properties:
        scope:
          type: string
          description: The token scope as a space delimited set of values.
          example: read:user write:user
        access_token:
          type: string
          description: The JWT token.
          example: eyo.....
        expires_in:
          type: integer
          format: int32
          description: The token expiry in seconds.
          example: 300
        token_type:
          type: string
          description: The token type.
          example: Bearer
        not-before-policy:
          type: integer
          format: int32
          description: The not before policy in seconds.
          example: 0
        refresh_expires_in:
          type: integer
          format: int32
          description: The refresh token expiry in seconds.
          example: 300
      required:
        - access_token
        - expires_in
        - scope
        - token_type
    CurrencyInfo:
      type: object
      properties:
        code:
          type: string
          description: ISO-3 Currency code
          example: EUR
          pattern: '[A-Z]{3}'
        name:
          type: string
          description: Currency name
          example: Euro
          maxLength: 50
      required:
        - code
        - name
    ExchangeInfo:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/CurrencyInfo'
          description: Currency of the exchange
        amount:
          type: number
          description: Amount in foreign currency
          example: 24.2
        exchangeRate:
          type:
            - number
            - 'null'
          description: Exchange rate from USD to foreign currency
          example: 1.171487603
      required:
        - amount
        - currency
    Merchant:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          description: The optional merchant name.
          example: MUSEO OPERA SANTA CROCE
          maxLength: 50
        category:
          type:
            - string
            - 'null'
          description: The optional merchant category code (4 digit SIC).
          example: '7997'
          pattern: \d{4}
        description:
          type:
            - string
            - 'null'
          description: The optional merchant description.
          example: MUSEO OPERA SANTA CROCE  FIRENZE      IT
          maxLength: 50
        location:
          oneOf:
            - $ref: '#/components/schemas/MerchantLocation'
            - type: 'null'
    MerchantLocation:
      type: object
      properties:
        city:
          type:
            - string
            - 'null'
          description: The optional merchant city.
          example: FIRENZE
          maxLength: 50
        state:
          type:
            - string
            - 'null'
          description: The optional merchant state.
          example: IT
          maxLength: 2
        country:
          type:
            - string
            - 'null'
          description: The optional merchant country in ISO 3166-1 alpha-3 format.
          example: ITA
          maxLength: 3
    Transaction:
      type: object
      properties:
        referenceNumber:
          type: string
          description: The transaction reference number.
          example: 7434495GE9WRQ9QVE
        type:
          type: string
          description: The transaction type.
          enum:
            - Authorization
            - AuthorizationAdjustment
            - Sale
            - CashAdvance
            - Return
            - MerchandiseSaleReversal
            - CashAdvanceReversal
            - ReturnReversal
            - MerchandiseSaleAmountAdjustment
            - CashAdvanceAmountAdjustment
            - ReturnAmountAdjustment
            - Payment
            - PaymentReversal
            - PaymentAmountAdjustment
            - Adjustment
            - CashAdvanceItemChargeRefund
            - LatefeeRefund
            - MerchandiseFinanceChargeRefund
            - CashAdvanceFinanceChargeRefund
            - BackdatedPaymentAdjustment
            - MerchandiseItemChargeRefund
            - OverLimitChargeRefund
            - CreditInsuranceFeeRefund
            - BackdateCashAdvanceandSalesAdjustment
            - SmallBalanceChargeOff
            - ChargeOffTotalAccount
            - ChargeOffCashAdvanceInterest
            - ChargeOffBilledLateCharges
            - ChargeOffMerchandiseInterestandServiceCharge
            - ChargeOffCreditInsurance
            - ChargeOffAllFinanceCharges
            - ChargeOffAllCurrentCashAdvanceInterest
            - ChargeOffAllCurrentMerchandiseInterest
            - ChargeOffCycleToDateLateCharges
            - ChargeOffBilledCashAdvanceItemCharges
            - ChargeOffBilledMerchandiseItemCharges
            - ChargeOffBilledOverLimitFee
            - ChargeOffCycleToDateCashAdvanceItemCharges
            - ChargeOffCycleToDateMerchandiseItemCharges
            - ChargeOffCycleToDateOverLimitFees
            - AccountTransfer
            - NotSpecified
          example: Sale
        sys:
          type: string
          description: The 4 digit sys of the account.
          example: '6161'
          pattern: \d{4}
        prin:
          type: string
          description: The 4 digit prin of the account.
          example: '0000'
          pattern: \d{4}
        agent:
          type: string
          description: The 4 digit agent of the account.
          example: '1000'
          pattern: \d{4}
        account:
          $ref: '#/components/schemas/AccountIdentification'
          description: The parent account associated with this transaction.
        cardAccount:
          oneOf:
            - $ref: '#/components/schemas/AccountIdentification'
            - type: 'null'
        amount:
          type: number
          description: The transaction amount in US Dollars.
          example: 28.35
        date:
          type: string
          format: date
          description: The transaction date.
          example: '2023-01-01'
        postedDate:
          type: string
          format: date
          description: The date the transaction was posted.
          example: '2023-01-02'
        cycleDate:
          type: string
          format: date
          description: The cycle date assoicated with the transaction.
          example: '2023-01-02'
        merchant:
          oneOf:
            - $ref: '#/components/schemas/Merchant'
            - type: 'null'
        exchangeInfo:
          oneOf:
            - $ref: '#/components/schemas/ExchangeInfo'
            - type: 'null'
      required:
        - account
        - agent
        - amount
        - cycleDate
        - date
        - postedDate
        - prin
        - referenceNumber
        - sys
        - type
  securitySchemes:
    bearer-jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
