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 Provisioning Events…
servers:
- url: https://tts.apib2b.citi.com/tts/cards/mvca/v1/token-lifecycle-events
security:
- clientCredentials: []
tags:
- name: Token Provisioning Events
paths:
  /token-provisioning-events:
    post:
      summary: Token Provisioning Event Details
      description: This webhook provides details about mVCA token provisioning events
      operationId: provision
      tags:
      - Token Provisioning Events
      parameters:
      - name: Content-Type
        in: header
        description: Supports application/json
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Request should contain Authorization header OAuth  <br> **OAuth:** <br> Request contains a header field in the form of Authorization: Bearer (access_token), where access_token is generated using the OAuth url <br>

          `Example` : Bearer AAIkMjU2OTI4OGQtODY5Ny00ZjgzLTg0NzEtY2QyZWYwZjM5ZjJk_m3yqnGAbxR_ovVx5bs9OUfF0dd52qHadLtw2ARkwCw2BJcwg1zHsTOuvjPtsW5ioxxd2xXXjlDDCKLuvg15Ce1gzGxTu17xEvLOzSECLIdU_02JbpS3h9ee9GzB-u_MPfKseOiACXYAh_7AVWQhtRMLDKd8RgCUsNzTGXXBeE4'
        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/TokenProvisioningEventRequest'
        description: TokenProvisioningEventRequest
        required: true
components:
  schemas:
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    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
    ForbiddenError:
      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
    MetaData:
      properties:
        accountHolderData:
          description: Additional information that can be used to identify the account holder, such as name, address
          $ref: '#/components/schemas/AccountHolderDataSchema'
        paymentAccountReference:
          description: The unique account reference assigned to the PAN
          type: string
          format: alphanumeric
          example: 512381d9f8e0629211e3949a08002
          maxLength: 29
          minLength: 29
        deviceInfo:
          description: Contains information about the target device to be provisioned. Max length - Not applicable. Type - Map (DeviceInfo).
          $ref: '#/components/schemas/DeviceInfo'
        accountIdHash:
          description: SHA-256 hash of the Account holders account ID with the Payment App Provider. Typically expected to be an email address. Type - string (Alpha Numeric) Hex-encoded data (case-insensitive)
          type: string
          format: alphanumeric
          example: 5ae9c9890b326bd23bfa9db9672298ae3b10a9388e56ec17a001e191f24572aa
          maxLength: 64
          minLength: 1
        activeTokenCount:
          description: The number of active tokens that already exist for the Funding Account based on the token type. Secure Element and Cloud tokens are counted together. Valid values are 0 to 99. A value of 99 means there are 99 or more active tokens. Tokens that have been deleted from the wallet are excluded from the count. Max length - 2.
          type: string
          format: numeric
          example: '3'
          maxLength: 2
          minLength: 1
        consumerFacingEntityName:
          description: Entity name that account holder recognizes as being where they store their PAN (wallets, merchants, commerce platforms )
          type: string
          format: string
          example: MerchantName
          maxLength: 100
          minLength: 1
    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
    ResourceNotFoundError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    UnauthorizedError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    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'
    AccountHolderDataSchema:
      properties:
        accountHolderName:
          description: The name of the account holder in the format LASTNAME/FIRSTNAME or FIRSTNAME LASTNAME
          type: string
          format: string
          example: John Doe
          maxLength: 27
          minLength: 1
        accountHolderAddress:
          description: The address for the account holder. Verified as part of reaching the digitization decision.
          $ref: '#/components/schemas/BillingAddressSchema'
        sourceIp:
          description: The IP of the device initiating the request.
          type: string
          format: numeric
          example: 127.0.0.1
          maxLength: 64
          minLength: 7
        deviceLocation:
          description: Latitude and longitude where the device the consumer is attempting to authorize is located. In the format "(sign) latitude/(sign) longitude" with a precision of 2 decimal places. Ex:"38.63/-90.2". Latitude is between -90 and 90. Longitude between -180 and 180.
          type: string
          format: numeric
          example: 38.63/-90.2
          maxLength: 64
          minLength: 1
        consumerIdentifier:
          description: Consumer Identifier provided by the token requestor. Not required   Optionally present in AuthorizeService when provided by the wallet provider.
          type: string
          format: alphanumeric
          example: 1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c1b24f24a24b
          maxLength: 88
          minLength: 1
        accountHolderEmailAddress:
          description: The email address of the account holder. Not required - Optionally present in pushAccount request. Not present otherwise.
          type: string
          format: alphanumeric
          example: abcdef@xyz.com
          maxLength: 320
          minLength: 6
        accountHolderMobilePhoneNumber:
          description: The mobile phone number of the account holder. Not required.
          $ref: '#/components/schemas/PhoneNumberSchema'
    TokenProvisioningEventRequest:
      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 provisioning event  [ APPROVED, REQUIRE_ADDITIONAL_AUTHENTICATION, COMPLETED, REJECTED ]
          type: string
          format: string
          example: APPROVED
        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
        source:
          description: 'The source of this account information. Must be one of - ACCOUNT_ON_FILE : Source was an existing account on file, - ACCOUNT_ADDED_MANUALLY: Source was a new account entered manually be the account holder, - ACCOUNT_ADDED_VIA_APPLICATION: Source was new account added by another application (for example, Issuer banking app), - EXISTING_TOKEN_CREDENTIAL: Source was an existing token, - ACCOUNT_ADDED_VIA_BROWSER: Source was browser.

            '
          type: string
          example: ACCOUNT_ADDED_VIA_APPLICATION
          maxLength: 32
          minLength: 1
        correlationId:
          description: Value linking pre-digitization messages generated during provisioning.
          type: string
          format: alphanumeric
          example: D98765432104
          maxLength: 14
          minLength: 1
        tokenizedMetaData:
          description: Account holder information and other financial information
          $ref: '#/components/schemas/MetaData'
        walletInfo:
          description: Contains information about the wallet.
          $ref: '#/components/schemas/WalletInfo'
        walletProviderDecisioningInfo:
          description: Contains information about the decision recommended by the Wallet Provider.
          $ref: '#/components/schemas/WalletProviderDecisioningInfo'
        vcnInfo:
          $ref: '#/components/schemas/VcnInfo'
        rcnInfo:
          $ref: '#/components/schemas/RcnInfo'
      required:
      - tokenType
      - eventType
      - tokenRequestorId
      - correlationId
      - vcnInfo
      - rcnInfo
    BillingAddressSchema:
      properties:
        line1:
          description: First line of the billing address.
          type: string
          format: alphanumeric
          example: 100 1st Street
          maxLength: 64
          minLength: 1
        line2:
          description: Second line of the billing address.
          type: string
          format: alphanumeric
          example: Apt. 4B
          maxLength: 64
          minLength: 1
        city:
          description: The city of the billing address.
          type: string
          format: string
          example: St. Louis
          maxLength: 32
          minLength: 1
        countrySubdivision:
          description: The country subdivision (for example, the state in the U.S.) of the billing address.
          type: string
          format: alphanumeric
          example: MO
          maxLength: 12
          minLength: 1
        postalCode:
          description: The postal code (for example, zip code in the U.S.) of the billing address.
          type: string
          format: numeric
          example: '61000'
          maxLength: 16
          minLength: 1
        country:
          description: The country of the billing address. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166 -1
          type: string
          format: string
          example: USA
          maxLength: 3
          minLength: 3
    PhoneNumberSchema:
      properties:
        countryDialInCode:
          description: The country code for the phone number. E.g. 1 for US or 44 for UK
          type: string
          format: numeric
          example: '1'
          maxLength: 4
          minLength: 1
        phoneNumber:
          description: The phone number, may contain country code along with phone number when countryDialInCode is not present.
          type: string
          format: numeric
          example: '4692392391'
          maxLength: 20
          minLength: 1
    DeviceInfo:
      properties:
        deviceName:
          description: The name that the Account holder has associated to the device with the Payment App Provider.
          type: string
          format: string
          example: My Phone
          maxLength: 64
          minLength: 1
        serialNumber:
          description: The serial number of the device. May be masked.
          type: string
          format: alphanumeric
          example: 2F6D63
          maxLength: 64
          minLength: 1
        formFactor:
          description: The form factor of the device to be provisioned. New values can be added without notice and should be accpeted. Must be one of PHONE = Mobile phone, TABLET = Tablet computer, TABLET_OR_EREADER = Tablet computer or e-reader, WATCH = Watch, WATCH_OR_WRISTBAND = Watch or wristband, including a fitness band, smart strap, disposable band, watch add-on, security/ ID Band, CARD = Card, STICKER = Sticker, PC = PC or Laptop, DEVICE_PERIPHERAL = Device peripherals, such as a mobile phone case or sleeve, TAG = Tag, such as a key fob or mobile tag, JEWELRY = Jewelry, such as a ring, bracelet, necklace and cuff links, FASHION_ACCESSORY = Fashion accessory, such as a handbag, bag charm, glasses, GARMENT = Garment, such as a dress, DOMESTIC_APPLIANCE = Domestic appliance, such as a refrigerator, washing machine, VEHICLE = Vehicle, including vehicle attached devices, MEDIA_OR_GAMING_DEVICE = Media or gaming device, including a set top box, media player, television, UNDEFINED = Device type that is not yet defined. Used for wallets introducing a new device type that is not yet public knowledge.
          type: string
          format: string
          example: PHONE
          maxLength: 64
          minLength: 1
        isoDeviceType:
          description: The 2 digit device type provided on the iso messages that the token is being provisioned to. Only present when provided by a Wallet Provider. See Global Communication bulletins for values.
          type: string
          format: numeric
          example: 09
          maxLength: 2
          minLength: 1
        osName:
          description: The name of the device operating system. Must be one of; ANDROID = Google Android operating system, WINDOWS = Microsoft Windows operating system, TIZEN = Tizen operating system, IOS = Apple iOS operating system, PAGARE_EMBEDDED_OS = FitPay embedded operating system, ANDROID_WEAR = Android wear operating system, EMBEDDED_OS = All Embedded operating system and Real time Operating systems.
          type: string
          format: string
          example: ANDROID
          maxLength: 32
          minLength: 1
        osVersion:
          description: The version of the device operating system.
          type: string
          format: numeric
          example: 4.4.4
          maxLength: 32
          minLength: 1
        imei:
          description: The IMEI number of the device being provisioned.
          type: string
          format: numeric
          example: '352099001761481'
          maxLength: 15
          minLength: 15
        msisdn:
          description: The MSISDN of the device being provisioned. Type - String.
          type: string
          format: numeric
          example: '7307406945'
          maxLength: 15
          minLength: 1
        paymentTypes:
          description: Different types of Payments supported for the token. Must be one of; NFC = The token is NFC capable, DSRP = The token is DSRP capable, ECOMMERCE = The token can be used for e-commerce transactions.
          type: array
          items:
            type: string
          format: string
          example: '["NFC"]'
        storageTechnology:
          description: The architecture or technology used for token storage. Must be one of DEVICE_MEMORY - Device memory, DEVICE_MEMORY_PROTECTED_TPM - Device memory using a protected trust platform module, TEE - Trusted execution environment, SE - Secure element, SERVER - Server host, or VEE - Virtual Execution Environment.
          type: string
          format: string
          example: SE
          maxLength: 32
          minLength: 1
        cardCaptureTechnology:
          description: TThe technology used to capture the card details. New values can be added at any time and must not result in an error. Must be one of CAMERA = The card details were captured using the device camera, MANUAL = The card details were manually entered, UNKNOWN = It is not known how the card details were entered, READER_MODE = The card details were captured using reader mode.
          type: string
          format: string
          example: CAMERA
          maxLength: 32
          minLength: 1
    Errors:
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    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
    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
    InternalServerErrorResponse:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
    WalletProviderDecisioningInfo:
      properties:
        recommendedDecision:
          description: The decision recommended by the Wallet Provider. Must be one of; APPROVED = Services request was approved, DECLINED = Services request was declined, REQUIRE_ADDITIONAL_AUTHENTICATION = Services request requires additional authentication to be approved.
          type: string
          format: string
          example: REQUIRE_ADDITIONAL_AUTHENTICATION
          maxLength: 64
          minLength: 1
        recommendationStandardVersion:
          description: The standards version used by the Wallet Provider to determine the recommended decision.
          type: string
          format: numeric
          example: 1.0.0
          maxLength: 64
          minLength: 1
        deviceScore:
          description: Score given to the device by the Wallet Provider. Value between 1 and 5.
          type: string
          format: numeric
          example: '3'
          maxLength: 64
          minLength: 1
        accountScore:
          description: Score given to the account by the Wallet Provider. Value between 1 and 5.
          type: string
          format: numeric
          example: '4'
          maxLength: 64
          minLength: 1
        phoneNumberScore:
          description: Score given to the phone number by the Wallet Provider. Value between 1 and 5.
          type: string
          format: numeric
          example: '4'
          maxLength: 64
          minLength: 1
        accountLifeTime:
          description: The lifetime of the account with the Token Requestor.
          type: string
          format: numeric
          example: '4'
          maxLength: 2
          minLength: 1
        recommendationReasons:
          description: Reasons provided to the Wallet Provider on how the recommended decision was reached. Please refer to "Reason Codes" tab for all eligible values.
          type: array
          items:
            type: string
          format: string
          example: '["ACCOUNT_TOO_NEW"]'
    BadRequestError:
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      required:
      - Errors
  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.


        '