Visa Consent Management Service

---
openapi: 3.0.1
info:
  title: Visa Consent Management Service
  description: ''
  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:
                          + INITIATED
                          + ACTIVE
                          + REVOKED
                          + EXPIRED
                          + CONSUMED
                          + PAUSED
                        <table>
                          <thead>
                          <tr>
                            <td>Consent Status Value</td>
                            <td>Description</td>
                          </tr>
                          </thead>
                          <tbody>
                          <tr>
                            <td><code>INITIATED</code></td>
                            <td>
                              <ul>
                              <li>This is the initial status of a consent when created/saved without successful consumer authentication.</li>
                              <li>A consent in this status cannot be used to access consent items (data or other resources).</li>
                              </ul>
                            </td>
                          </tr>
                          <tr>
                            <td><code>ACTIVE</code></td>
                            <td>
                              <ul>
                              <li>The status of the consent is considered active when it can be used to access consent items (data or other resources).</li>
                              <li>Only after successful cardholder authentication, a consent is considered in <code>ACTIVE</code> status.</li>
                              </ul>
                            </td>
                          </tr>
                          <tr>
                            <td><code>REVOKED</code></td>
                            <td>
                              The consent is transitioned to this state only after it is revoked by the cardholder or by a party on behalf of the cardholder.
                            </td>
                          </tr>
                          <tr>
                            <td><code>EXPIRED</code></td>
                            <td>
                              When a consent's expiry date is reached, it is transitioned to this state.
                            </td>
                          </tr>
                          <tr>
                            <td><code>CONSUMED</code></td>
                            <td>
                              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.
                            </td>
                          </tr>
                          <tr>
                            <td><code>PAUSED</code></td>
                            <td>
                              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>.
                            </td>
                          </tr>
                          </tbody>
                        </table>
                      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.
                          * <code>STREAMING</code>:
                            * The consent item types in the consent are made available on a streaming basis, whenever a triggering event occurs.
                          * <code>PERIODIC</code>:
                            * The consent item types in the consent are available on a periodic basis.
                          * <code>ON_DEMAND</code>:
                            * The consent item types in the consent are available on demand from the Resource Provider.
                          * <code>CONTEXT_BASED</code>:
                            * The consent item types in the consent are available subject to additional filtering.
                      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_

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