Visa Visa Consent Management API API

openapi: 3.0.1
info:
  title: Foreign Exchange Rates Visa Consent Management API API
  description: Visa Consent Management API
  version: '1'
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox server
security: []
tags:
- name: Visa Consent Management API
  description: Visa Consent Management API
paths:
  /vcms/v1/consents/{consentID}/revoke:
    post:
      tags:
      - Visa Consent Management API
      summary: Revoke Consent
      description: 'This API revokes a current consent.

        A consent may be revoked if it is in either ACTIVE or PAUSED state. Attempting to revoke a consent in any other state results in a 409 error with <code>invalidConsentStateTransition</code> reason.'
      parameters:
      - name: X-Correlation-Id
        in: header
        description: Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging.
        required: false
        explode: false
        schema:
          maxLength: 36
          minLength: 1
          type: string
      - name: consentID
        in: path
        description: 'Consent identifier.

          '
        required: true
        explode: false
        schema:
          type: string
      requestBody:
        description: Request body for revocation payload.
        content:
          application/json:
            schema:
              properties:
                revocationReason:
                  maxLength: 120
                  minLength: 1
                  type: string
                  description: 'The reason for the consent revocation.

                    '
                  example: User-initiated
        required: true
      responses:
        '200':
          description: 'Updated consent.

            '
          headers:
            X-Correlation-Id:
              description: Unique ID for the API response; <code>X-Correlation-Id</code> is echoed back. Used for end-to-end tracing/debugging.
              style: simple
              explode: false
              schema:
                maxLength: 36
                minLength: 1
                type: string
          content:
            application/json:
              schema:
                title: Consent object in response for Transaction Events
                type: object
                description: "Consent object returned in the responses.\nA consent represents the end-user permission to access its transaction events or historical data.\nThe limits of a consent are represented by:\n  1. What: Type of the consent - what data or events or payments or actions (payments, etc.) are permitted\n  2. Context:\n    a. Time-based retrictions/validity for the Consent.\n    b. Beneficiaries and the consent requestor information\n  3. Why: Purpose of the consent\n  4. Terms and Conditions applicable for the Consent\nThe consent is typically unique for a combination of the following, but it not enforced by the API implementation: \n  1. Client ID (Partner VDP Project)\n  2. Region (US as default)\n  3. Cardholder Identity (vCardID/PAN)\n  4. Consent Type (as defined in consentType definition)\n"
                allOf:
                - properties:
                    status:
                      title: Status of consent
                      type: string
                      description: "Valid status values of consent:\n  + INITIATED\n  + ACTIVE\n  + REVOKED\n  + EXPIRED\n  + CONSUMED\n  + PAUSED\n<table>\n  <thead>\n  <tr>\n    <td>Consent Status Value</td>\n    <td>Description</td>\n  </tr>\n  </thead>\n  <tbody>\n  <tr>\n    <td><code>INITIATED</code></td>\n    <td>\n      <ul>\n      <li>This is the initial status of a consent when created/saved without successful consumer authentication.</li>\n      <li>A consent in this status cannot be used to access consent items (data or other resources).</li>\n      </ul>\n    </td>\n  </tr>\n  <tr>\n    <td><code>ACTIVE</code></td>\n    <td>\n      <ul>\n      <li>The status of the consent is considered active when it can be used to access consent items (data or other resources).</li>\n      <li>Only after successful cardholder authentication, a consent is considered in <code>ACTIVE</code> status.</li>\n      </ul>\n    </td>\n  </tr>\n  <tr>\n    <td><code>REVOKED</code></td>\n    <td>\n      The consent is transitioned to this state only after it is revoked by the cardholder or by a party on behalf of the cardholder.\n    </td>\n  </tr>\n  <tr>\n    <td><code>EXPIRED</code></td>\n    <td>\n      When a consent's expiry date is reached, it is transitioned to this state.\n    </td>\n  </tr>\n  <tr>\n    <td><code>CONSUMED</code></td>\n    <td>\n      When the consent's applicability/policy is <code>ONE_TIME</code> and when the consent is used for the applicable use case, the consent is transitioned to this state.\n    </td>\n  </tr>\n  <tr>\n    <td><code>PAUSED</code></td>\n    <td>\n      In this state, the consent's purpose (e.g. data sharing, opt-in, etc) may not be fulfilled.  If not expired or otherwise invalidated, a consent in this status may be transitioned back to <code>ACTIVE</code>.\n    </td>\n  </tr>\n  </tbody>\n</table>\n"
                      example: REVOKED
                      enum:
                      - INITIATED
                      - ACTIVE
                      - REVOKED
                      - EXPIRED
                      - CONSUMED
                      - PAUSED
                    userID:
                      title: Masked User Identifier
                      maxLength: 320
                      minLength: 1
                      type: string
                      description: "The identifier of the user for whom the consent is created. The type of this identifier is defined by the value of the corresponding userIDType attribute. \nUser identifiers of type <code>EMAIL_ADDRESS</code> <code>PHONE_NUMBER</code> <code>PAN</code> and <code>CLIENT_DEFINED</code> are not retained as-is in the consent system, and will be returned as masked values in subsequent API responses.\n"
                      example: con***@visa.com
                    consentID:
                      title: Visa-generated identifier for the consent
                      type: string
                      description: 'UUID generated by Visa for every new consent.

                        The API client can create as many consentIDs as they want and are responsible for managing the lifecycle of consents.

                        A consentID is only accessible and visible to the clients that created it, until we implement the on-behalf-of (OBO) model for consent.

                        '
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174000
                - title: Consent object used for creation
                  type: object
                  properties:
                    frequency:
                      title: Defines the frequency criteria or policy for consent
                      type: string
                      description: "An enum representing the consent frequency.\n  * <code>STREAMING</code>:\n    * The consent item types in the consent are made available on a streaming basis, whenever a triggering event occurs.\n  * <code>PERIODIC</code>:\n    * The consent item types in the consent are available on a periodic basis.\n  * <code>ON_DEMAND</code>:\n    * The consent item types in the consent are available on demand from the Resource Provider.\n  * <code>CONTEXT_BASED</code>:\n    * The consent item types in the consent are available subject to additional filtering.\n"
                      default: STREAMING
                      enum:
                      - STREAMING
                      - PERIODIC
                      - ON_DEMAND
                      - CONTEXT_BASED
                    userIDType:
                      title: User Identifier Type
                      type: string
                      description: 'The type of the provided user identifier (userID).

                        '
                      example: EMAIL_ADDRESS
                      enum:
                      - EMAIL_ADDRESS
                      - PHONE_NUMBER
                      - VCARDID
                      - PAN
                      - CLIENT_DEFINED
                    primaryPurposes:
                      maxItems: 10
                      minItems: 1
                      type: array
                      description: 'A list of primary consent purposes.

                        '
                      items:
                        required:
                        - beneficiaryOrganizationIDs
                        - consentItemTypes
                        - purposeType
                        type: object
                        properties:
                          purposeType:
                            title: Purpose of Consent
                            maxLength: 25
                            minLength: 0
                            type: string
                            description: 'Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location).

                              '
                            example: PERSONAL_FINANCE_MGMT
                          consentItemTypes:
                            maxItems: 10
                            minItems: 1
                            type: array
                            description: 'The consent item types.

                              '
                            items:
                              title: Consent Item Types.
                              type: string
                              description: 'The classes of resources which the user may consent to sharing with a beneficiary.  The set of possible values is contained in the data dictionary for Consent Type Items (TBD location).

                                '
                              example: TRANSACTION_DATA
                          beneficiaryOrganizationIDs:
                            maxItems: 10
                            minItems: 1
                            type: array
                            description: 'The beneficiary IDs which are using the resource for the enclosing purpose.

                              '
                            items:
                              title: Visa-generated identifier for an organization.
                              type: string
                              description: 'This attribute identifies a previously-onboarded organization.

                                '
                              format: uuid
                              example: 123e4567-e89b-12d3-a456-426614174000
                    externalConsentID:
                      maxLength: 50
                      minLength: 0
                      type: string
                      description: A client-provided identifier for the consent being created. Uniqueness of this value should be enforced by the client.
                      example: qwertyK
                    presentedLanguage:
                      maxLength: 100
                      minLength: 2
                      type: string
                      description: 'The language of the content presented to the user.

                        '
                      format: BCP-47
                      example: en-US
                    previousConsentID:
                      description: This attribute may be used to reference a prior consent for which the new consent is a "renewal". This reference must have been created in the context of the same Consent Directory and for the same user.
                      example: ''
                      allOf:
                      - title: Visa-generated identifier for the consent
                        type: string
                        description: 'UUID generated by Visa for every new consent.

                          The API client can create as many consentIDs as they want and are responsible for managing the lifecycle of consents.

                          A consentID is only accessible and visible to the clients that created it, until we implement the on-behalf-of (OBO) model for consent.

                          '
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                    secondaryPurposes:
                      maxItems: 10
                      minItems: 1
                      type: array
                      description: 'A list of secondary consent purposes.

                        '
                      items:
                        required:
                        - beneficiaryOrganizationIDs
                        - consentItemTypes
                        - isOptedIn
                        - purposeType
                        type: object
                        properties:
                          isOptedIn:
                            type: boolean
                            description: 'Indicator as to whether the secondary consent was opted in or out by the consumer.

                              A value of true indicates the the consumer opted in to the secondary purpose.

                              '
                        allOf:
                        - required:
                          - beneficiaryOrganizationIDs
                          - consentItemTypes
                          - purposeType
                          type: object
                          properties:
                            purposeType:
                              title: Purpose of Consent
                              maxLength: 25
                              minLength: 0
                              type: string
                              description: 'Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location).

                                '
                              example: PERSONAL_FINANCE_MGMT
                            consentItemTypes:
                              maxItems: 10
                              minItems: 1
                              type: array
                              description: 'The consent item types.

                                '
                              items:
                                title: Consent Item Types.
                                type: string
                                description: 'The classes of resources which the user may consent to sharing with a beneficiary.  The set of possible values is contained in the data dictionary for Consent Type Items (TBD location).

                                  '
                                example: TRANSACTION_DATA
                            beneficiaryOrganizationIDs:
                              maxItems: 10
                              minItems: 1
                              type: array
                              description: 'The beneficiary IDs which are using the resource for the enclosing purpose.

                                '
                              items:
                                title: Visa-generated identifier for an organization.
                                type: string
                                description: 'This attribute identifies a previously-onboarded organization.

                                  '
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174000
                    consentCaptureCity:
                      maxLength: 80
                      minLength: 1
                      type: string
                      description: 'The city where the user''s consent was captured.

                        '
                      example: Austin
                    consentDirectoryID:
                      title: The Visa-generated identifier for a Consent Directory entry.
                      type: string
                      description: 'This value refers to a previously-configured Consent Directory entry, in whose context a consent may be created.

                        '
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174000
                    expirationDateTime:
                      title: The datetime until when the consent is valid
                      maxLength: 29
                      minLength: 20
                      type: string
                      description: "The consent is invalid after this datetime. After expiry, the consent is not renewable. When provided by the client, this value must be greater than the current date.\nFormat is based on RFC 3339, with the following stipulations: \n+ ‘T’ is used as separator between date and time.\n+ Only fractional seconds are optional - all other parts of the datetime are required.\n+ Fractional seconds may contain up to 3 decimal places. \n+ All datetimes will be converted to GMT (+00:00) for storage and subsequent retrieval.\n"
                      format: RFC3339
                      example: '2026-02-05T17:31:00Z'
                    privacyPolicyVersion:
                      maxLength: 10
                      minLength: 1
                      type: string
                      description: 'The version of the privacy policy presented to the user.

                        '
                      example: '4.1'
                    consentCaptureCountry:
                      maxLength: 2
                      minLength: 2
                      type: string
                      description: 'The country where the user''s consent was captured.

                        '
                      format: ISO 3166-1 alpha 2
                      example: US
                    consentCaptureDateTime:
                      maxLength: 29
                      minLength: 20
                      type: string
                      description: "The date and time that the consent was captured from the user, in the user's local time zone.\nFormat is based on RFC 3339, with the following stipulations: \n+ ‘T’ is used as separator between date and time.\n+ Only fractional seconds are optional - all other parts of the datetime are required.\n+ Fractional seconds may contain up to 3 decimal places.\n+ The time zone provided will be maintained and returned on subsequent retrieval.\n"
                      format: RFC3339
                      example: '2021-01-12T10:15:20.343-06:00'
                    presentedContentVersion:
                      maxLength: 10
                      minLength: 1
                      type: string
                      description: 'The version of the content presented to the user.

                        '
                      example: '1.0'
                    presenterOrganizationID:
                      title: Visa-generated identifier for an organization.
                      type: string
                      description: 'This attribute identifies a previously-onboarded organization.

                        '
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174000
                    consentCaptureRegionState:
                      maxLength: 3
                      minLength: 1
                      type: string
                      description: 'The region or state where the user''s consent was captured, represented as the subdivision part of ISO 3166-2.

                        '
                      format: ISO 3166-2 subdivision
                      example: TX
                    resourceProviderOrganizationIDs:
                      type: array
                      description: 'The list of Resource Provider identifiers who are participating in this consent.

                        '
                      items:
                        title: Visa-generated identifier for an organization.
                        type: string
                        description: 'This attribute identifies a previously-onboarded organization.

                          '
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                - properties:
                    constraints:
                      title: Consent Constraints
                      type: object
                      properties:
                        timespan:
                          type: object
                          properties:
                            endDateTime:
                              maxLength: 29
                              minLength: 20
                              type: string
                              description: "End datetime.\nFormat is based on RFC 3339, with the following stipulations: \n+ ‘T’ is used as separator between date and time.\n+ Only fractional seconds are optional - all other parts of the datetime are required.\n+ Fractional seconds may contain up to 3 decimal places.\n+ All datetimes will be converted to GMT (+00:00) for storage and retrieval.\n"
                              format: RFC3339
                              example: '2022-07-12T16:15:21.672Z'
                            startDateTime:
                              maxLength: 29
                              minLength: 20
                              type: string
                              description: "Start datetime.\nFormat is based on RFC 3339, with the following stipulations: \n+ ‘T’ is used as separator between date and time.\n+ Only fractional seconds are optional - all other parts of the datetime are required.\n+ Fractional seconds may contain up to 3 decimal places.\n+ All datetimes will be converted to GMT (+00:00) for storage and retrieval.\n"
                              format: RFC3339
                              example: '2022-01-12T16:15:21.672Z'
                          description: 'A timespan constraint applicable for the consent item types captured in the consent.

                            For example, consent for historical transaction data may have a constraint to include only transactions from the last 6 months.

                            That constraint would be captured here.

                            '
                        maxNumberUses:
                          maximum: 100
                          minimum: 0
                          type: integer
                          description: 'The maximum number of uses for the consent item types captured in the consent.

                            '
                          format: int32
                        remainingNumberUses:
                          title: Remaining Number of Uses
                          maximum: 100
                          minimum: 0
                          type: integer
                          description: 'The remaining number of uses for the consent item types captured in the consent..

                            '
                          format: int32
                      description: 'Additional consent constraints.

                        '
                    createdDateTime:
                      maxLength: 29
                      minLength: 20
                      type: string
                      description: When the consent was created in either an initiated or active state.
                      format: RFC3339
                      example: '2021-01-12T16:15:21.672Z'
                    updatedDateTime:
                      maxLength: 29
                      minLength: 20
                      type: string
                      description: When the consent was last updated.
                      format: RFC3339
                      example: '2021-01-12T16:15:21.672Z'
                    financialInstruments:
                      type: array
                      description: 'The list of financial instruments applicable for this consent.

                        '
                      items:
                        title: Masked Financial Instrument
                        type: object
                        properties:
                          instrumentID:
                            maxLength: 36
                            minLength: 36
                            type: string
                            description: 'Unique identifier for the instance of financial instrument.

                              '
                            format: uuid
                            example: f38de9d8-129a-40ea-b149-b8b64a7eda33
                          accountNumber:
                            maxLength: 50
                            minLength: 1
                            type: string
                            description: 'The account number.  Account numbers of type <code>PAYMENT_CARD</code> <code>BANK_ACCOUNT</code> and <code>PAYMENT_TOKEN</code> are not retained in the consent system as-is, and will be returned as masked values in subsequent API responses.

                              '
                            example: 400000******0000
                          instrumentType:
                            type: string
                            description: 'The type of financial instrument.

                              '
                            enum:
                            - PAYMENT_CARD
                            - VCARDID
                            - BANK_ACCOUNT
                            - PAYMENT_TOKEN
                        description: 'Financial instrument representation, with masked account number.

                          '
                    consumerContactInformation:
                      title: Masked Consumer Contact Information
                      type: object
                      properties:
                        phoneNumber:
                          maxLength: 15
                          minLength: 7
                          type: string
                          description: 'Phone number, which may include only numerical digits.

                            '
                          example: '***555'
                        emailAddress:
                          maxLength: 100
                          minLength: 5
                          type: string
                          description: 'Email address.

                            '
                          format: Email Address
                          example: con***@visa.com
                        isPhoneNumberVerified:
                          type: boolean
                          description: 'Indicates whether the phone number has been verified by the caller.

                            '
                        isEmailAddressVerified:
                          type: boolean
                          description: 'Indicates whether the email address has been verified by the caller.

                            '
                      description: 'Masked contact information for the end consumer.

                        '
                    identityVerificationDetails:
                      title: Identity verification details
                      type: object
                      properties:
                        userID:
                          description: "The user identifier used for IDV, if it differs from the root-level userID attribute.  \nIdentifiers of type <code>EMAIL_ADDRESS</code> <code>PHONE_NUMBER</code> <code>PAN</code> and <code>CLIENT_DEFINED</code> are not retained as-is in the consent system, and will be returned as masked values in subsequent API responses. \n"
                          allOf:
                          - title: Masked User Identifier
                            maxLength: 320
                            minLength: 1
                            type: string
                            description: "The identifier of the user for whom the consent is created. The type of this identifier is defined by the value of the corresponding userIDType attribute. \nUser identifiers of type <code>EMAIL_ADDRESS</code> <code>PHONE_NUMBER</code> <code>PAN</code> and <code>CLIENT_DEFINED</code> are not retained as-is in the consent system, and will be returned as masked values in subsequent API responses.\n"
                            example: con***@visa.com
                        userIDType:
                          title: User Identifier Type
                          type: string
                          description: 'The type of the provided user identifier (userID).

                            '
                          example: EMAIL_ADDRESS
                          enum:
                          - EMAIL_ADDRESS
                          - PHONE_NUMBER
                          - VCARDID
                          - PAN
                          - CLIENT_DEFINED
                        attestation:
                          maxLength: 2000
                          minLength: 1
                          type: string
                          description: 'The attestation contents, format as determined by the attestationType.

                            '
                        attestationType:
                          type: string
                          description: 'The type of identity verification attestation.

                            '
                          enum:
                          - ID_TOKEN
                      description: "The Identity verification details represent an attestation of the consumer identity and the details of the authentication performed on the consumer.<br/>\nVisa uses authentication details for various risk purposes. \nThe identity of the consumer is necessary for ensuring proper capture of the consent.<br/>\nIf the attestationType is <code>ID_TOKEN</code>, the attestation is represented by a base64 urlencoded string - a standard JWT format.\n"
                - required:
                  - consentCaptureCountry
                  - consentCaptureDateTime
                  - consentCaptureRegionState
                  - consentDirectoryID
                  - consentID
                  - createdDateTime
                  - expirationDateTime
                  - frequency
                  - presentedContentVersion
                  - presentedLanguage
                  - presenterOrganizationID
                  - primaryPurposes
                  - privacyPolicyVersion
                  - resourceProviderOrganizationIDs
                  - resourceProviderOrganizationIDs
                  - status
                  - updatedDateTime
                  - userID
                  - userIDType
        '400':
          description: "The <code>details</code> part of the error response can provide a list of fields that failed data validation constraints and reason values for this error include:\n  <ul>\n  <li><code>badRequest</code>The API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.\n  </ul>\n"
          headers:
            X-Correlation-Id:
              description: Unique ID for the API response; <code>X-Correlation-Id</code> is echoed back. Used for end-to-end tracing/debugging.
              style: simple
              explode: false
              schema:
                maxLength: 36
                minLength: 1
                type: string
          content:
            application/json:
              schema:
                allOf:
                - title: Standard Error Response Structure
                  description: API errors are reported using a Standard Error Response structure. All errors are categorized into Standard errors and Business errors. Standard errors can be returned by any API and should be handled in a common way. Business errors are returned only by some APIs and are documented for each API.
                  allOf:
                  - required:
                    - reason
                    type: object
                    properties:
                      reason:
                        maxLength: 100
                        minLength: 1
                        type: string
                        description: API developers must use this field to drive their error handling logic
                        example: badRequest
                      details:
                        type: array
                        description: Array of fields - Data validation errors should use this array to specify  fields that failed validation using the location field
                        items:
                          required:
                          - location
                

# --- truncated at 32 KB (613 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visa/refs/heads/main/openapi/visa-visa-consent-management-api-api-openapi.yml