openapi: 3.0.0 info: description: >- Subscription API allows Commercial application events and to receive notifications based on those subscriptions version: 2.0.0 title: vca events subscriptions x-ibm-name: vca-events-subscriptions contact: name: GLOBAL Commercial Cards API Production support email: >- dl.icg.global.commercial.cards.digital.production.support@imcap.ap.ssmb.com servers: - url: https://tts.apib2b.citi.com/tts/cards tags: - name: Subscription description: Operations related to event subscriptions paths: /vca/v2/events/subscriptions: post: summary: Create Subscription description: >- Create a subscription that will cause notifications to be generated for the specified events. operationId: createSubscription tags: - Subscription parameters: - name: Authorization in: header description: Bearer token obtained from the OAuth2 Client Credentials flow required: true schema: type: string - name: Region in: header description: region of the client(Apac/EMEA/NAM) required: true schema: type: string - name: Country in: header description: country of the Client required: true schema: type: string - name: Req-Sys-Id in: header description: Client Tracking ID required: true schema: type: string requestBody: description: SubscriptionRequest required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionRequest' responses: '201': description: >-
CodeDetails
SubscriptionResponseCreated
content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponse' '400': description: >-
errorCodeerrorDescription
EVB0700subscriptionName is Mandatory
EVB0701subscriptionName length should contain a min of 1 character and a max of 50 characters
EVB0702subscriptionName field is invalid and can only have letters, numbers, dashes and underscores
EVB0703active is Mandatory
EVB0704operator field is Mandatory
EVB0705WHERE operator can only be used in the first subscription.operator field, other subscription.operator fields should use only OR operator
EVB0706fieldName is Mandatory
EVB0707subscription.fieldName must have a value of programId for the first condition in the specifications in conjunction with the WHERE operator and the EQUALS fieldOperator
EVB0708subscription.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
EVB0709fieldName should contain a min of 1 character and a max of 30 characters
EVB0710fieldOperator is Mandatory
EVB0711subscription.expectedContent.contentType must have a value of INTEGER when subscription.fieldName value equal 'programId'
EVB0712expectedContent.contentType is Mandatory
EVB0713expectedContent.contentType length should contain a min of 1 character and a max of 7 characters
EVB0714subscription.expectedContent.contentType is invalid and can only have a value of INTEGER for the EQUALS operator
EVB0715expectedContent.value is Mandatory
EVB0716expectedContent.value must only contain letters, digits, spaces, hyphens, slashes, commas, periods and underscores
EVB0717children.operator is invalid and can only have a value of AND, OR
EVB0718Invalid value for the field children.fieldName
EVB0719Invalid value for the field children.fieldName. children.fieldName cannot contain a value of programId
EVB0720children.fieldOperator is invalid and can only have a value of EQUALS
EVB0721children.expectedContent.contentType can only have a value of TEXT when the children.fieldOperator field is EQUALS
EVB0722children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'fundingSourceName'
EVB0723children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'messageTypeIndicator'
EVB0724children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'authorizationResponseDetail'
EVB0725children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'vcaAuthorizationResponseDetail'
EVB0357ProgramId must be numeric
EVB0201We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.
EVB0066ClientId and programId combination is not valid
EVB0726subscriptionId length should contain a min of 1 character and a max of 255 characters
EVB0727No subscription found for the specified subscription ID
EVB0728This subscription name is already registered for this subscriber
EVB0729subscriptionEventType field is invalid and can only have one of the following values:'PAYMENT_AUTHORIZATION','CLEARING'
GRC0005Client Tracking ID is missing in the request header
GRC0010Client Tracking ID length should contain a min of 1 character and a max of 36 characters
GRC0003Invalid JSON input
GRC0016Country code is not available in the request
content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description:
ErrorNot Found
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '500': description:
ErrorInternal Server Error
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' /vca/v2/events/subscriptions/{subscriptionId}: delete: summary: Delete Subscription description: >- Deletes a subscription, with the effect that no further notifications will be generated for that subscription. operationId: deleteSubscription tags: - Subscription parameters: - name: subscriptionId in: path required: true schema: type: string - name: Authorization in: header description: Bearer token obtained from the OAuth2 Client Credentials flow required: true schema: type: string - name: Region in: header description: region of the client(Apac/EMEA/NAM) required: true schema: type: string - name: Country in: header description: country of the Client required: true schema: type: string - name: Req-Sys-Id in: header description: Client Tracking ID required: true schema: type: string responses: '204': description: >-
CodeDetails
DELETED
'400': description: >-
errorCodeerrorDescription
EVB0726subscriptionId length should contain a min of 1 character and a max of 255 characters
EVB0727No subscription found for the specified subscription ID
GRC0005Client Tracking ID is missing in the request header
GRC0010Client Tracking ID length should contain a min of 1 character and a max of 36 characters
GRC0016Country code is not available in the request
content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description:
ErrorNot Found
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '500': description:
ErrorInternal Server Error
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' get: summary: Get Subscription description: Retrieve the details of a subscription. operationId: getSubscription tags: - Subscription parameters: - name: subscriptionId in: path required: true schema: type: string - name: Authorization in: header description: Bearer token obtained from the OAuth2 Client Credentials flow required: true schema: type: string - name: Region in: header description: region of the client(Apac/EMEA/NAM) required: true schema: type: string - name: Country in: header description: country of the Client required: true schema: type: string - name: Req-Sys-Id in: header description: Client Tracking ID required: true schema: type: string responses: '200': description: >-
CodeDetails
SubscriptionResponseOK
content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponse' '400': description: >-
errorCodeerrorDescription
EVB0726subscriptionId length should contain a min of 1 character and a max of 255 characters
EVB0727No subscription found for the specified subscription ID
GRC0005Client Tracking ID is missing in the request header
GRC0010Client Tracking ID length should contain a min of 1 character and a max of 36 characters
GRC0016Country code is not available in the request
content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description:
ErrorNot Found
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '500': description:
ErrorInternal Server Error
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' put: summary: Update Subscription description: Update an existing subscription. operationId: updateSubscription tags: - Subscription parameters: - name: subscriptionId in: path required: true schema: type: string - name: Authorization in: header description: Bearer token obtained from the OAuth2 Client Credentials flow required: true schema: type: string - name: Region in: header description: region of the client(Apac/EMEA/NAM) required: true schema: type: string - name: Country in: header description: country of the Client required: true schema: type: string - name: Req-Sys-Id in: header description: Client Tracking ID required: true schema: type: string requestBody: description: SubscriptionRequest required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionRequest' responses: '200': description: >-
CodeDetails
SubscriptionResponseOK
content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponse' '400': description: >-
errorCodeerrorDescription
EVB0700subscriptionName is Mandatory
EVB0701subscriptionName length should contain a min of 1 character and a max of 50 characters
EVB0702subscriptionName field is invalid and can only have letters, numbers, dashes and underscores
EVB0703active is Mandatory
EVB0704operator field is Mandatory
EVB0705WHERE operator can only be used in the first subscription.operator field, other subscription.operator fields should use only OR operator
EVB0706fieldName is Mandatory
EVB0707subscription.fieldName must have a value of programId for the first condition in the specifications in conjunction with the WHERE operator and the EQUALS fieldOperator
EVB0708subscription.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
EVB0709fieldName should contain a min of 1 character and a max of 30 characters
EVB0710fieldOperator is Mandatory
EVB0711subscription.expectedContent.contentType must have a value of INTEGER when subscription.fieldName value equal 'programId'
EVB0712expectedContent.contentType is Mandatory
EVB0713expectedContent.contentType length should contain a min of 1 character and a max of 7 characters
EVB0714subscription.expectedContent.contentType is invalid and can only have a value of INTEGER for the EQUALS operator
EVB0715expectedContent.value is Mandatory
EVB0716expectedContent.value must only contain letters, digits, spaces, hyphens, slashes, commas, periods and underscores
EVB0717children.operator is invalid and can only have a value of AND, OR
EVB0718Invalid value for the field children.fieldName
EVB0719Invalid value for the field children.fieldName. children.fieldName cannot contain a value of programId
EVB0720children.fieldOperator is invalid and can only have a value of EQUALS
EVB0721children.expectedContent.contentType can only have a value of TEXT when the children.fieldOperator field is EQUALS
EVB0722children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'fundingSourceName'
EVB0723children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'messageTypeIndicator'
EVB0724children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'authorizationResponseDetail'
EVB0725children.expectedContent.contentType must have a value of TEXT when children.fieldName value is 'vcaAuthorizationResponseDetail'
GRC0005Client Tracking ID is missing in the request header
GRC0010Client Tracking ID length should contain a min of 1 character and a max of 36 characters
GRC0003Invalid JSON input
GRC0016Country code is not available in the request
EVB0357ProgramId must be numeric
EVB0201We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.
EVB0066ClientId and programId combination is not valid
EVB0726subscriptionId length should contain a min of 1 character and a max of 255 characters
EVB0727No subscription found for the specified subscription ID
EVB0729eventType field is invalid and can only have one of the following values:'PAYMENT_AUTHORIZATION','CLEARING'
content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description:
ErrorNot Found
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '500': description:
ErrorInternal Server Error
content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: securitySchemes: ClientCredentials: type: oauth2 description: OAuth2 Client Credentials flow flows: clientCredentials: tokenUrl: https://tts.sandbox.apib2b.citi.com/tts/cards/api/oauth2/token scopes: /api: ' ' schemas: SubscriptionRequest: type: object required: - subscriptionName - active - subscription properties: subscriptionName: description: >- Unique name for the subscription. It can include upper and lowercase alphabets, numbers, dashes and underscores. type: string example: Enter_unique_subscription_name_here maxLength: 50 eventType: description: >- Client Allowed values are either 1 of the below:If not provided default to 'PAYMENT_AUTHORIZATION' type: string enum: - PAYMENT_AUTHORIZATION - CLEARING maxLength: 30 active: description: >- Specify whether the subscription should be active (true ) or inactive (false) for the API to create notifications only if the subscription is active. type: boolean example: true subscription: description: >- Alert subscription conditions to filter the payment authorization messages type: array items: $ref: '#/components/schemas/Subscription' Subscription: type: object required: - operator - fieldName - fieldOperator - expectedContent properties: operator: description: >- Specify an operator to combine multiple conditions in the specifications.
* WHERE: By default, the first condition in the specifications should always have this value to represent the WHERE clause.
* AND: Use this in the second condition onwards to create notifications only if all specifications conditions are true.
* OR: Use this in the second condition onwards to create notifications if one of the specifications conditions is true. type: string example: WHERE maxLength: 5 fieldName: 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

Possible values:
"programId" - VCA program ID. By default, the first condition in the specifications should always have this value in conjunction with the WHERE operator. type: string example: purchaseRequest.rcnAlias maxLength: 30 fieldOperator: description: >- Specify the relational operator to use in the condition for the fieldName. This is used in conjunction with the expectedContent.

Possible values:
"EQUALS": This applies to contentType "TEXT" and "INTEGER". Create notifications for the exact fieldName value specified in the condition. type: string example: EQUALS maxLength: 12 expectedContent: $ref: '#/components/schemas/FieldContent' children: description: >- Used to define specifications with nested conditions for a subscription. type: array items: $ref: '#/components/schemas/Children' FieldContent: type: object required: - contentType - value properties: contentType: description: >- Specify the type of the fields value - TEXT or INTEGER for the EQUALS operator and INTEGER for the rest. type: string value: description: Specify a value for a fieldName type: string example: Travel Expense RCN Children: type: object required: - operator - fieldName - fieldOperator - expectedContent properties: operator: description: >- Specify an operator to combine multiple conditions in the specifications.
* WHERE: By default, the first condition in the specifications should always have this value to represent the WHERE clause.
* AND: Use this in the second condition onwards to create notifications only if all specifications conditions are true.
* OR: Use this in the second condition onwards to create notifications if one of the specifications conditions is true. type: string example: WHERE maxLength: 5 fieldName: 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

Possible values:
"fundingSourceName" - Funding source name
"messageTypeIndicator" - Message type indicator
"authorizationResponseDetail" - Response code
"vcaAuthorizationResponseDetail" - In Control VCN service result code type: string example: purchaseRequest.rcnAlias maxLength: 30 fieldOperator: description: >- Specify the relational operator to use in the condition for the fieldName. This is used in conjunction with the expectedContent.

Possible values:
"EQUALS": This applies to contentType "TEXT" and "INTEGER". Create notifications for the exact fieldName value specified in the condition. type: string example: EQUALS maxLength: 12 expectedContent: $ref: '#/components/schemas/FieldContent' children: description: >- Used to define specifications with nested conditions for a subscription. type: array items: $ref: '#/components/schemas/Children' SubscriptionResponse: type: object properties: subscriptionId: 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. type: string example: >- CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724070 maxLength: 255 minLength: 1 eventType: description: >- Client Allowed values are either 1 of the below:If not provided default to 'PAYMENT_AUTHORIZATION' type: string enum: - PAYMENT_AUTHORIZATION - CLEARING maxLength: 30 subscriptionName: description: >- Unique name for the subscription. It can include upper and lowercase alphabets, numbers, dashes and underscores. type: string example: Enter_unique_subscription_name_here maxLength: 50 minLength: 1 active: description: >- Specify whether the subscription should be active (true ) or inactive (false) for the API to create notifications only if the subscription is active. type: boolean example: true subscription: description: >- Alert subscription conditions to filter the payment authorization messages. type: array items: $ref: '#/components/schemas/Subscription' ErrorResponse: type: object properties: errorMessage: type: array items: $ref: '#/components/schemas/ErrorMessage' ErrorMessage: type: object 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 - EVB0729 errorDescription: description: >- The error description that corresponds to error code when there is any
error occurred while retrieving the transaction.

* `EVB0700` - subscriptionName is Mandatory
* `EVB0701` - subscriptionName length should contain a min of 1 character and a max of 50 characters
* `EVB0702` - subscriptionName field is invalid and can only have letters, numbers, dashes and underscores
* `EVB0703` - active is Mandatory
* `EVB0704` - operator field is Mandatory
* `EVB0705` - WHERE operator can only be used in the first subscription.operator field, other subscription.operator fields should use only OR operator
* `EVB0706` - fieldName is Mandatory
* `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
* `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
* `EVB0709` - fieldName should contain a min of 1 character and a max of 30 characters
* `EVB0710` - fieldOperator is Mandatory
* `EVB0711` - subscription.expectedContent.contentType must have a value of INTEGER when subscription.fieldName value equal "programId"
* `EVB0712` - expectedContent.contentType is Mandatory
* `EVB0713` - expectedContent.contentType length should contain a min of 1 character and a max of 7 characters
* `EVB0714` - subscription.expectedContent.contentType is invalid and can only have a value of INTEGER for the EQUALS operator
* `EVB0715` - expectedContent.value is Mandatory
* `EVB0716` - expectedContent.value must only contain letters, digits, spaces, hyphens, slashes, commas, periods and underscores
* `EVB0717` - children.operator is invalid and can only have a value of AND, OR
* `EVB0718` - Invalid value for the field children.fieldName
* `EVB0719` - Invalid value for the field children.fieldName. children.fieldName cannot contain a value of programId
* `EVB0720` - children.fieldOperator is invalid and can only have a value of EQUALS
* `EVB0721` - children.expectedContent.contentType can only have a value of TEXT when the children.fieldOperator field is EQUALS
* `EVB0722` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is "fundingSourceName"
* `EVB0723` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is "messageTypeIndicator"
* `EVB0724` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is "authorizationResponseDetail"
* `EVB0725` - children.expectedContent.contentType must have a value of TEXT when children.fieldName value is "vcaAuthorizationResponseDetail"
* `GRC0005` - Client Tracking ID is missing in the request header
* `GRC0010` - Client Tracking ID length should contain a min of 1 character and a max of 36 characters
* `GRC0003` - Invalid JSON input
* `GRC0016` - Country code is not available in the request
* `EVB0357` - ProgramId must be numeric
* `EVB0201` - We were unable to process your request. Please try again, or contact Citi support if you have any further questions or comments.
* `EVB0066` - ClientId and programId combination is not valid
* `EVB0726` - subscriptionId length should contain a min of 1 character and a max of 255 characters
* `EVB0727` - No subscription found for the specified subscription ID
* `EVB0728` - This subscription name is already registered for this subscriber
* `EVB0729` - eventType field is invalid and can only have one of the following values: 'PAYMENT_AUTHORIZATION', 'CLEARING' type: string