swagger: '2.0'
info:
  description: >-
    The Virtual Cards Notifications API allows clients to create and manage
    subscriptions and to receive notifications based on those subscriptions.
  version: ''
  title: Virtual Cards Notifications API
servers:
  - url: >-
      https://grace-engine-service-uat-icg-tts-grace-173707.namicgswd12u.nam.nsroot.net/tts/cards
    description: production gateway URL
  - url: https://tts.sandbox.apib2b.citi.com/tts/cards
    description: sandbox URL
schemes:
  - https
produces:
  - application/json
tags: []
security:
  - clientCredentials: []
paths:
  /vca/v1/authorizations/subscriptions:
    post:
      summary: Create Subscription
      description: Create a notification subscription for a Virtual Card program.
      operationId: createSubscription
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: client_id
          in: query
          required: true
          description: >-
            This is your unique identifier shared during your CitiConnect API
            onboarding. This is the same `client_id` used for oauth token
            generation
          type: string
        - name: Authorization
          in: header
          description: The OAuth Token prefixed with "Bearer" and space in between.
          required: true
          type: string
        - name: Content-Type
          in: header
          description: Supports application/json.
          required: true
          type: string
        - name: Region
          in: header
          description: region of the client(Apac/EMEA/NAM)
          required: true
          type: string
        - name: Country
          in: header
          description: country of the Client
          required: true
          type: string
        - name: Req-Sys-Id
          in: header
          description: Client Tracking ID
          required: true
          type: string
        - in: body
          name: SubscriptionRequest
          description: SubscriptionRequest
          required: true
          schema:
            $ref: '#/definitions/SubscriptionRequest'
      responses:
        '201':
          description: >-
            <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>SubscriptionResponse</td><td>Created</td></tr></table>
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        '400':
          description: >-
            <table><tr><td>Error-400</td><td>Bad
            Request</td></tr><tr><td>SubscriptionFailureResponse</td><td>Bad
            Request</td></tr></table>
          schema:
            $ref: '#/definitions/SubscriptionFailureResponse'
        '500':
          description: >-
            <table><tr><td>Error-403</td><td>Internal Server
            Error</td></tr><tr><td>Error-401</td><td>Internal Server
            Error</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d401'
  /vca/v1/authorizations/subscriptions/{subscriptionId}:
    get:
      summary: Retrieve Subscription
      description: Retrieve the details that were set on the subscription.
      operationId: getSubscription
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: client_id
          in: query
          required: true
          description: >-
            This is your unique identifier shared during your CitiConnect API
            onboarding. This is the same `client_id` used for oauth token
            generation
          type: string
        - name: Authorization
          in: header
          description: The OAuth Token prefixed with "Bearer" and space in between.
          required: true
          type: string
        - name: subscriptionId
          in: path
          description: Subscription ID
          required: true
          type: string
        - name: Region
          in: header
          description: region of the client(Apac/EMEA/NAM)
          required: true
          type: string
        - name: Country
          in: header
          description: country of the Client
          required: true
          type: string
        - name: Req-Sys-Id
          in: header
          description: Client Tracking ID
          required: true
          type: string
      responses:
        '200':
          description: >-
            <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>SubscriptionResponse</td><td>OK</td></tr></table>
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        '404':
          description: <table><tr><td>Error-404</td><td>Bad Request</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d404'
        '500':
          description: >-
            <table><tr><td>Error-403</td><td>Internal Server
            Error</td></tr><tr><td>Error-401</td><td>Internal Server
            Error</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d401'
    put:
      summary: Update an Existing Subscription
      description: Update an existing Virtual Cards notification subscription.
      operationId: updateSubscription
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: client_id
          in: query
          required: true
          description: >-
            This is your unique identifier shared during your CitiConnect API
            onboarding. This is the same `client_id` used for oauth token
            generation
          type: string
        - name: Authorization
          in: header
          description: The OAuth Token prefixed with "Bearer" and space in between.
          required: true
          type: string
        - name: Content-Type
          in: header
          description: Supports application/json.
          required: true
          type: string
        - name: subscriptionId
          in: path
          description: Subscription ID
          required: true
          type: string
        - name: Region
          in: header
          description: region of the client(Apac/EMEA/NAM)
          required: true
          type: string
        - name: Country
          in: header
          description: country of the Client
          required: true
          type: string
        - name: Req-Sys-Id
          in: header
          description: Client Tracking ID
          required: true
          type: string
        - in: body
          name: SubscriptionRequest
          description: SubscriptionRequest
          required: true
          schema:
            $ref: '#/definitions/SubscriptionRequest'
      responses:
        '200':
          description: >-
            <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td>SubscriptionResponse</td><td>OK</td></tr></table>
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        '400':
          description: >-
            <table><tr><td>SubscriptionFailureResponse</td><td>Bad
            Request</td></tr></table>
          schema:
            $ref: '#/definitions/SubscriptionFailureResponse'
        '404':
          description: <table><tr><td>Error-404</td><td></td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d404'
        '500':
          description: >-
            <table><tr><td>Error-403</td><td>Internal Server
            Error</td></tr><tr><td>Error-401</td><td>Internal Server
            Error</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d401'
    delete:
      summary: Delete Subscription
      description: Delete a Virtual Cards Notification subscription.
      operationId: deleteSubscription
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: client_id
          in: query
          required: true
          description: >-
            This is your unique identifier shared during your CitiConnect API
            onboarding. This is the same `client_id` used for oauth token
            generation
          type: string
        - name: Authorization
          in: header
          description: The OAuth Token prefixed with "Bearer" and space in between.
          required: true
          type: string
        - name: subscriptionId
          in: path
          description: Subscription ID
          required: true
          type: string
        - name: Region
          in: header
          description: region of the client(Apac/EMEA/NAM)
          required: true
          type: string
        - name: Country
          in: header
          description: country of the Client
          required: true
          type: string
        - name: Req-Sys-Id
          in: header
          description: Client Tracking ID
          required: true
          type: string
      responses:
        '204':
          description: >-
            <table><tr><td>Code</td><td>Details</td></tr><tr><tr><td></td><td>DELETED</td></tr></table>
        '404':
          description: <table><tr><td>Error-404</td><td>Not Found</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d404'
        '500':
          description: >-
            <table><tr><td>Error-403</td><td>Internal Server
            Error</td></tr><tr><td>Error-401</td><td>Internal Server
            Error</td></tr></table>
          schema:
            $ref: '#/definitions/Error%2d401'
securityDefinitions:
  clientCredentials:
    type: oauth2
    tokenUrl: https://tts.apib2b.citi.com/tts/cards/api/v1/oauth2/token
    flow: application
    scopes: null
definitions:
  SubscriptionRequest:
    required:
      - active
      - subscription
      - subscriptionName
    properties:
      subscriptionName:
        type: string
        format: alphanumeric
        example: Subscription_test-1654530803985
        description: >-
          Unique name for the subscription. It can include upper and lowercase
          alphabets, numbers, dashes and underscores.
        maxLength: 50
      active:
        type: boolean
        format: alpha
        example: true
        description: >-
          Specify whether the subscription should be active (true ) or inactive
          (false) for the API to create notifications only if the subscription
          is active.
      subscription:
        type: array
        description: >-
          Alert subscription conditions to filter the payment authorization
          messages
        items:
          $ref: '#/definitions/Subscription'
  Subscription:
    required:
      - expectedContent
      - fieldName
      - fieldOperator
      - operator
    properties:
      operator:
        type: string
        format: alpha
        example: WHERE
        description: >-
          Specify an operator to combine multiple conditions in the
          specifications.<br>* WHERE: By default, the first condition in the
          specifications should always have this value to represent the WHERE
          clause.<br>* AND: Use this in the second condition onwards to create
          notifications only if all specifications conditions are true.<br>* OR:
          Use this in the second condition onwards to create notifications if
          one of the specifications conditions is true.
        maxLength: 5
      fieldName:
        type: string
        format: alpha
        example: purchaseRequest.rcnAlias
        description: >-
          Specifies the field name for the condition to check. This is used in
          conjunction with the fieldOperator.programId is a required field in
          order to create a subscription<br><br> Possible values:<br>"programId"
          - VCA program ID. By default, the first condition in the
          specifications should always have this value in conjunction with the
          WHERE operator.
        maxLength: 30
      fieldOperator:
        type: string
        format: alpha
        example: EQUALS
        description: >-
          Specify the relational operator to use in the condition for the
          fieldName. This is used in conjunction with the expectedContent.<br>
          <br> Possible values:<br>"EQUALS": This applies to contentType "TEXT"
          and "INTEGER". Create notifications for the exact fieldName value
          specified in the condition.
        maxLength: 12
      expectedContent:
        $ref: '#/definitions/FieldContent'
      children:
        type: array
        description: >-
          Used to define specifications with nested conditions for a
          subscription.
        items:
          $ref: '#/definitions/Children'
  FieldContent:
    required:
      - contentType
      - value
    properties:
      contentType:
        type: string
        format: alphanumeric
        description: >-
          Specify the type of the fields value - TEXT or INTEGER for the EQUALS
          operator and INTEGER for the rest.
      value:
        type: string
        format: alphanumeric
        example: Travel Expense RCN
        description: Specify a value for a fieldName
  Children:
    required:
      - expectedContent
      - fieldName
      - fieldOperator
      - operator
    properties:
      operator:
        type: string
        format: alpha
        example: WHERE
        description: >-
          Specify an operator to combine multiple conditions in the
          specifications.<br>* WHERE: By default, the first condition in the
          specifications should always have this value to represent the WHERE
          clause.<br>* AND: Use this in the second condition onwards to create
          notifications only if all specifications conditions are true.<br>* OR:
          Use this in the second condition onwards to create notifications if
          one of the specifications conditions is true.
        maxLength: 5
      fieldName:
        type: string
        format: alpha
        example: purchaseRequest.rcnAlias
        description: >-
          Specifies the field name for the condition to check. This is used in
          conjunction with the fieldOperator.programId is a required field in
          order to create a subscription<br><br> Possible
          values:<br>"fundingSourceName" - Funding source
          name<br>"messageTypeIndicator" - Message type
          indicator<br>"authorizationResponseDetail" - Response
          code<br>"vcaAuthorizationResponseDetail" - In Control VCN service
          result code
        maxLength: 30
      fieldOperator:
        type: string
        format: alpha
        example: EQUALS
        description: >-
          Specify the relational operator to use in the condition for the
          fieldName. This is used in conjunction with the expectedContent.<br>
          <br> Possible values:<br>"EQUALS": This applies to contentType "TEXT"
          and "INTEGER". Create notifications for the exact fieldName value
          specified in the condition.
        maxLength: 12
      expectedContent:
        $ref: '#/definitions/FieldContent'
      children:
        type: array
        description: >-
          Used to define specifications with nested conditions for a
          subscription.
        items:
          $ref: '#/definitions/Children'
  SubscriptionResponse:
    properties:
      subscriptionId:
        type: string
        format: alphanumeric
        example: >-
          CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724070
        description: >-
          System generated unique identifier for a subscription, which is
          returned in the create subscription call. Access the individual
          subscription using its id to update, get details or delete a
          subscription permanently.
        minLength: 1
        maxLength: 255
      subscriptionName:
        type: string
        format: alphanumeric
        example: Enter_unique_subscription_name_here
        description: >-
          Unique name for the subscription. It can include upper and lowercase
          alphabets, numbers, dashes and underscores.
        minLength: 1
        maxLength: 50
      active:
        type: boolean
        format: alpha
        example: true
        description: >-
          Specify whether the subscription should be active (true ) or inactive
          (false) for the API to create notifications only if the subscription
          is active.
      subscription:
        type: array
        description: >-
          Alert subscription conditions to filter the payment authorization
          messages.
        items:
          $ref: '#/definitions/Subscription'
  Error:
    properties:
      errorCode:
        type: string
        example: ERS0001
        description: The error code
      errorDescription:
        type: string
        example: Subscription Name is mandatory
        description: Description of the error
  Error-401:
    properties:
      errorCode:
        type: string
        example: GRC0014
        description: The error code
      errorDescription:
        type: string
        example: >-
          We have encountered an error and couldnot receive your request. Please
          try again, or contact Citi support if you have any further questions
          or comments
        description: Description of the error
  SubscriptionFailureResponse:
    properties:
      errorMessage:
        type: array
        items:
          $ref: '#/definitions/ErrorMessage'
  ErrorMessage:
    required:
      - errorCode
      - errorDescription
    properties:
      errorCode:
        type: string
        enum:
          - EVB0700
          - EVB0701
          - EVB0702
          - EVB0703
          - EVB0704
          - EVB0705
          - EVB0706
          - EVB0707
          - EVB0708
          - EVB0709
          - EVB0710
          - EVB0711
          - EVB0712
          - EVB0713
          - EVB0714
          - EVB0715
          - EVB0716
          - EVB0717
          - EVB0718
          - EVB0719
          - EVB0720
          - EVB0721
          - EVB0722
          - EVB0723
          - EVB0724
          - EVB0725
          - GRC0005
          - GRC0010
          - GRC0003
          - GRC0016
          - EVB0357
          - EVB0201
          - EVB0066
          - EVB0726
          - EVB0727
          - EVB0728
      errorDescription:
        type: string
        description: "The error description that corresponds to error code when there is any<br>               error occurred while retrieving the trsansaction.            <br>            <br>              * `EVB0700` - subscriptionName is Mandatory<br>              * `EVB0701` - subscriptionName length should contain a min of 1 character and a max of 50 characters<br>              * `EVB0702` - subscriptionName field is invalid and can only have letters, numbers, dashes and underscores<br>              * `EVB0703` - active is Mandatory<br>              * `EVB0704` - operator field is Mandatory<br>              * `EVB0705` - WHERE operator can only be used in the first subscription.operator field, other subscription.operator fields should use only OR operator<br>              * `EVB0706` - fieldName is Mandatory<br>              * `EVB0707` - subscription.fieldName must have a value of programId for the first condition in the specifications in conjunction with the WHERE operator and the EQUALS fieldOperator<br>              * `EVB0708` - subscription.fieldName that is after the first subscription can only have a value of programId in conjunction with an operator value of OR and a fieldOperator value of EQUALS<br>              * `EVB0709` - fieldName should contain a min of 1 character and a max of 30 characters<br>\t\t\t  * `EVB0710` - fieldOperator is Mandatory<br>              * `EVB0711` - subscription.expectedContent.contentType must have a value of INTEGER when subscription.fieldName value equal \"programId\"<br>              * `EVB0712` - expectedContent.contentType is Mandatory<br>              * `EVB0713` - expectedContent.contentType length should contain a min of 1 character and a max of 7 characters<br>              * `EVB0714` - subscription.expectedContent.contentType is invalid and can only have a value of INTEGER for the EQUALS operator<br>\t\t\t  * `EVB0715` - expectedContent.value is Mandatory<br>              * `EVB0716` - expectedContent.value must only contain letters, digits, spaces, hyphens, slashes, commas, periods and underscores<br>              * `EVB0717` - children.operator is invalid and can only have a value of AND, OR<br>\t\t\t  * `EVB0718` - Invalid value for the field children.fieldName<br>              * `EVB0719` - Invalid value for the field children.fieldName. children.fieldName cannot contain a value of programId<br>\t\t\t  * `EVB0720` - children.fieldOperator is invalid and can only have a value of EQUALS<br>              * `EVB0721` - children.expectedContent.contentType can only have a value of TEXT when the children.fieldOperator field is EQUALS<br>              * `EVB0722` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is \"fundingSourceName\"<br>              * `EVB0723` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is \"messageTypeIndicator\"<br>\t\t\t  * `EVB0724` - children.expectedContent.contentType must have a value of TEXT  when children.fieldName value is \"authorizationResponseDetail\"<br>\t\t\t  * `EVB0725` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is \"vcaAuthorizationResponseDetail\"<br>\t\t\t  * `GRC0005` - Client Tracking ID is missing in the request header<br>\t\t\t  * `GRC0010` - Client Tracking ID length should contain a min of 1 character and a max of 36 characters<br>\t\t\t  * `GRC0003` - Invalid JSON input<br>\t\t\t  * `GRC0016` - Country code is not available in the request<br>\t\t\t  * `EVB0357` - ProgramId must be numeric<br>\t\t\t  * `EVB0201` - We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.<br>\t\t\t  * `EVB0066` - ClientId and programId combination is not valid<br>\t\t\t  * `EVB0726` - subscriptionId length should contain a min of 1 character and a max of 255 characters<br>\t\t\t  * `EVB0727` - No subscription found for the specified subscription ID<br>\t\t\t  * `EVB0728` - This subscription name is already registered for this subscriber"
  Error-404:
    properties:
      errorCode:
        type: string
        example: EVB0726
        description: The error code
      errorDescription:
        type: string
        example: No subscription found for the specified subscription ID
        description: Description of the error