Citi Token Lifecycle Events API

openapi: 3.2.0
info:
  description: These webhooks provides details about mVCA wallet token provisioning & lifecycle events
  version: ''
  title: Grace Mobile Virtual Cards Wallet Token Lifecycle Events API
servers:
- url: https://tts.apib2b.citi.com/tts/cards/mvca/v1/token-lifecycle-events
security:
- clientCredentials: []
tags:
- name: Token Lifecycle Events
paths:
  /token-lifecycle-events:
    post:
      summary: Token Lifecycle Event Details
      description: This webhook provides details about mVCA token lifecycle events
      operationId: lifecycle
      tags:
      - Token Lifecycle Events
      parameters:
      - name: Content-Type
        in: header
        description: Supports application/json
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Request contains a header field in the form of Authorization: Basic (credentials), where credentials is the Base64 encoding of clientid and client secret joined by a single colon :<br> `Format` : Basic (Base64 encoding of clientid:clientsecret)<br> `Example` : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
        required: true
        schema:
          type: string
      - 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
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        description: 'The idempotency key is a free identifier created by the client to identify a request. It is used by the service to identify subsequent retries of the same request and ensure idempotent behavior by sending the same response without executing the request a second time. <br> `Example` : 7da7a728-f910-11e6-942a-68f728c1ba70'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: <table><tr><td>Code</td><td>Event processed successfully</td></tr></table>
        '400':
          description: <table><tr><td>Bad Request Error</td><td>Missing or invalid request parameter</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: <table><tr><td>Unauthorized Error</td><td>Authentication Required</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: <table><tr><td>Forbidden Error</td><td>Not Authorized</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: <table><tr><td>Resource Not Found Error</td><td>Resource Not Found</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundError'
        '500':
          description: <table><tr><td>Internal Server Error Response</td><td>Internal server error.</td></tr></table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenLifeCycleEventRequest'
        description: TokenLifeCycleEventRequest
        required: true
components:
  schemas:
    ForbiddenError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    UnauthorizedError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    RcnInfo:
      properties:
        accountNumber:
          description: Card Account Number. Pattern^[0-9]+
          type: string
          format: numeric
          example: '1234567891234567'
          maxLength: 19
          minLength: 12
        expiry:
          description: Card expiry date in yyyy-MM format. Pattern^20[2-9][0-9]-(0[1-9]|1[012])$
          type: string
          format: yyyy-mm
          example: 2021-11
          maxLength: 7
          minLength: 7
        accountGuid:
          description: The globally unique identifier of the virtual card account
          type: string
          format: alphanumeric
          example: 123e4567-e89b-12d3-a456-426614174002
      required:
      - accountNumber
      - expiry
    BadRequestError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    Errors:
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    Error:
      properties:
        Source:
          description: The error description that corresponds to error code when there is any error occurred while retrieving the trsansaction.
          type: string
          format: alphanumeric
          example: Expiry date should be of 7 characters.
          maxLength: 255
          minLength: 1
        ReasonCode:
          description: The reason code specifies the error code that corresponds to the description
          type: string
          format: alphanumeric
          example: WTPM0002
          maxLength: 10
          minLength: 1
        Description:
          description: The error description that corresponds to error code when there is any error occurred while retrieving the trsansaction.
          type: string
          format: alphanumeric
          example: Expiry date should be of 7 characters.
          maxLength: 255
          minLength: 1
        recoverable:
          description: Recoverable to be sent to the Client
          type: boolean
          format: boolean
          example: 'true'
        Details:
          description: The error description that corresponds to error code when there is any error occurred while retrieving the trsansaction.
          type: string
          format: alphanumeric
          example: Expiry date should be of 7 characters.
          maxLength: 255
          minLength: 1
      required:
      - Source
      - ReasonCode
      - Description
      - recoverable
      - Details
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    InternalServerErrorResponse:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    WalletInfo:
      properties:
        walletId:
          description: The identifier of the Wallet Provider who requested the digitization. Only present when the token is provided to a Wallet Provider
          type: string
          format: numeric
          example: '123'
          maxLength: 3
          minLength: 1
        paymentAppInstanceId:
          description: The identifier of the Payment App instance within a device that will be provisioned with a token. Only present when supplied by a Wallet Provider.
          type: string
          format: alphanumeric
          example: 1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e
          maxLength: 48
          minLength: 1
        secureElementId:
          description: The identifier of the Secure Element to be provisioned with the token. Present only when the token is provisioned to a Secure Element and when provided by the Wallet Provider. Not required
          type: string
          format: alphanumeric
          example: 1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c
          maxLength: 128
          minLength: 1
    TokenInfo:
      properties:
        accountNumber:
          description: The token issued for this service request.
          type: string
          format: numeric
          example: '5345678901234521'
          maxLength: 19
          minLength: 12
        expiry:
          description: Expiry in yyyy-mm format
          type: string
          format: yyyy-mm
          example: 2026-10
          maxLength: 7
          minLength: 7
        accountGuid:
          description: The unique identifier of the token.
          type: string
          format: alphanumeric
          example: 123e4567-e89b-12d3-a456-426614174004
        createdDate:
          description: Date when the account was created, in ISO 8601 extended format. It can be either in UTC YYYY-MM-DDThh:mm:ss[.sss]Z or with an offset YYYY-MM-DDThh:mm:ss[.sss]±hh:mm, where [.sss] is optional and can be 1 to 3 digits.
          type: string
          format: string
          example: '2024-02-01T00:00:00Z'
        activatedDate:
          description: Date when the account was activated, in ISO 8601 extended format. It can be either in UTC YYYY-MM-DDThh:mm:ss[.sss]Z or with an offset YYYY-MM-DDThh:mm:ss[.sss]±hh:mm, where [.sss] is optional and can be 1 to 3 digits.
          type: string
          format: string
          example: '2024-02-01T00:00:00Z'
        lastUpdatedDate:
          description: Date when the account was last updated, in ISO 8601 extended format. It can be either in UTC YYYY-MM-DDThh:mm:ss[.sss]Z or with an offset YYYY-MM-DDThh:mm:ss[.sss]±hh:mm, where [.sss] is optional and can be 1 to 6 digits.
          type: string
          format: string
          example: '2024-02-12T15:19:36.633965Z'
    ResourceNotFoundError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    OwnerInfo:
      properties:
        issuerGuid:
          description: The globally unique identifier of the Issuer
          type: string
          format: alphanumeric
          example: 123e4567-e89b-12d3-a456-426614174001
        corpGuid:
          description: The globally unique identifier of the corporate
          type: string
          format: alphanumeric
          example: 123e4567-e89b-12d3-a456-426614174008
    VcnInfo:
      properties:
        accountNumber:
          description: Card Account Number. Pattern^[0-9]+
          type: string
          format: numeric
          example: '1234567891234567'
          maxLength: 19
          minLength: 12
        expiry:
          description: Card expiry date in yyyy-MM format. Pattern^20[2-9][0-9]-(0[1-9]|1[012])$  |
          type: string
          format: yyyy-mm
          example: 2021-11
          maxLength: 7
          minLength: 7
        accountGuid:
          description: The globally unique identifier of the virtual card account
          type: string
          format: alphanumeric
          example: 123e4567-e89b-12d3-a456-426614174003
        ownerInfo:
          description: Contains information about the Issuer and Corporate
          $ref: '#/components/schemas/OwnerInfo'
        createdDate:
          description: Date when the account was created, in ISO 8601 extended format. It can be either in UTC YYYY-MM-DDThh:mm:ss[.sss]Z or with an offset YYYY-MM-DDThh:mm:ss[.sss]±hh:mm, where [.sss] is optional and can be 1 to 3 digits.
          type: string
          format: string
          example: '2024-02-01T00:00:00Z'
        lastUpdatedDate:
          description: Date when the account was last updated, in ISO 8601 extended format. It can be either in UTC YYYY-MM-DDThh:mm:ss[.sss]Z or with an offset YYYY-MM-DDThh:mm:ss[.sss]±hh:mm, where [.sss] is optional and can be 1 to 6 digits.
          type: string
          format: string
          example: '2024-02-12T00:00:00Z'
      required:
      - accountNumber
      - expiry
    TokenLifeCycleEventRequest:
      properties:
        tokenInfo:
          description: The Token Information for this service request
          $ref: '#/components/schemas/TokenInfo'
        tokenType:
          description: The type of token requested for this digitization. Valid values are EMBEDDED_SE = Embedded Secure Element | CLOUD = Mastercard Cloud-Based Payments | STATIC = Static token.
          type: string
          format: string
          example: CLOUD
          maxLength: 16
          minLength: 1
        eventType:
          description: The type of the lifecycle event  [ CREATED, UPDATED, DELETED ]
          type: string
          format: string
          example: CREATED
        tokenRequestorId:
          description: The party that requested the digitization. Type - String (Numeric). Conditional - Required if tokens are assigned by MDES
          type: string
          format: numeric
          example: '12345678901'
          maxLength: 11
          minLength: 11
        reasonCode:
          description: The reason code for why the notification is being sent. This applies to all tokens in the Tokens array. Must be one of; STATUS_UPDATE - The status of the tokens has been changed, REDIGITIZATION_COMPLETE - The token has been re-digitized to the device, DELETED_FROM_CONSUMER_APP = The token has been deleted from the consumer application. The token may still be active.
          type: string
          format: string
          example: REDIGITIZATION_COMPLETE
          maxLength: 32
          minLength: 1
        status:
          description: The current status of token. Must be one of; INACTIVE - Token has not yet been activated, ACTIVE - Token is active and ready to transact, SUSPENDED - Token is suspended and unable to transact, DEACTIVATED - Token has been permanently deactivated. Max length - 32. Type - String. Conditional - required for notifyTokenUpdated if reasonCode = "STATUS_UPDATE". Not present otherwise.
          type: string
          format: alphanumeric
          example: SUSPENDED
          maxLength: 32
          minLength: 1
        correlationId:
          description: Value linking pre-digitization messages generated during provisioning.
          type: string
          format: alphanumeric
          example: D98765432104
          maxLength: 14
          minLength: 1
        suspendedBy:
          description: Who or what caused the token to be suspended. One or more values of; ISSUER = Suspended by the Issuer. PaymentAppProvider unable to unsuspend this token, (PAYMENT_APP_PROVIDER = Deprecated - Suspended by the PaymentAppProvider), TOKEN_REQUESTOR = Suspended by the Token Requestor, MOBILE_PIN_LOCKED = Suspended due to the Mobile PIN being locked, CARDHOLDER = Suspended by the Cardholder. Max length - Not applicable. Type - Array[String]. Conditional - Required if status = SUSPENDED.
          type: array
          items:
            type: string
          format: string
          example: '["CARDHOLDER"]'
        requestedBy:
          description: Who or what requested the token event. One of; ISSUER = Requested by the Issuer, TOKEN_REQUESTOR = Requested by the Token Requestor, MOBILE_PIN_LOCK = Requested by a Mobile PIN Lock, CARDHOLDER = Requested by the Cardholder, SYSTEM = Requested by the System.
          type: string
          example: CARDHOLDER
        walletInfo:
          description: Contains information about the wallet.
          $ref: '#/components/schemas/WalletInfo'
        vcnInfo:
          $ref: '#/components/schemas/VcnInfo'
        rcnInfo:
          $ref: '#/components/schemas/RcnInfo'
      required:
      - tokenInfo
      - tokenType
      - eventType
      - tokenRequestorId
      - correlationId
      - vcnInfo
      - rcnInfo
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://tts.apib2b.citi.com/tts/cards/mvca/v1/token-lifecycle-events/cv/api/oauth2/token
      description: 'All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See <a href="../../authentication/authentication-api-reference/" target="_blank">the Citi Authentication API reference</a> for information on requesting a token.


        '