Every API here is available over the APIs.io API and to AI agents over MCP.
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'
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
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
InternalServerErrorResponse:
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'
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
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
ForbiddenError:
properties:
Errors:
$ref: '#/components/schemas/Errors'
required:
- Errors
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
Errors:
type: object
required:
- Error
properties:
Error:
$ref: '#/components/schemas/ErrorList'
ResourceNotFoundError:
properties:
Errors:
$ref: '#/components/schemas/Errors'
required:
- Errors
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
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
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
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'
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
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
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
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.
'