# Visa Consent Management Service

## Visa Consent Management API

### Revoke Consent  v1 - Latest

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 `invalidConsentStateTransition` reason.

#### Request

##### path Parameters

|     |     |
| --- | --- |
| consentID<br>required | string<br>Consent identifier. |

##### header Parameters

|     |     |
| --- | --- |
| X-Correlation-Id | string \[ 1 .. 36 \] characters <br>Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. |

##### Request Body schema: application/json

Request body for revocation payload.

|     |     |
| --- | --- |
| revocationReason | string \[ 1 .. 120 \] characters <br>The reason for the consent revocation.<br>Example: "User-initiated" |

### Responses

200
Updated consent.

|     |     |
| --- | --- |
| X-Correlation-Id | string \[ 1 .. 36 \] characters <br>Unique ID for the API response; `X-Correlation-Id` is echoed back. Used for end-to-end tracing/debugging. |

##### Response Schema: application/json

| consentCaptureCountry<br>required | string <ISO 3166-1 alpha 2>  2 characters <br>The country where the user's consent was captured.<br>Example: "US" |
| consentCaptureDateTime<br>required | string <RFC3339>  \[ 20 .. 29 \] characters <br>The date and time that the consent was captured from the user, in the user's local time zone.<br>Format is based on RFC 3339, with the following stipulations: <br>- ‘T’ is used as separator between date and time.<br>- Only fractional seconds are optional - all other parts of the datetime are required.<br>- Fractional seconds may contain up to 3 decimal places.<br>- The time zone provided will be maintained and returned on subsequent retrieval.<br>Example: "2021-01-12T10:15:20.343-06:00" |
| consentCaptureRegionState<br>required | string <ISO 3166-2 subdivision>  \[ 1 .. 3 \] characters <br>The region or state where the user's consent was captured, represented as the subdivision part of ISO 3166-2.<br>Example: "TX" |
| consentDirectoryID<br>required | string <uuid> <br>This value refers to a previously-configured Consent Directory entry, in whose context a consent may be created.<br>Example: "123e4567-e89b-12d3-a456-426614174000" |
| consentID<br>required | string <uuid> <br>UUID generated by Visa for every new consent.<br>The API client can create as many consentIDs as they want and are responsible for managing the lifecycle of consents.<br>A consentID is only accessible and visible to the clients that created it, until we implement the on-behalf-of (OBO) model for consent.<br>Example: "123e4567-e89b-12d3-a456-426614174000" |
| createdDateTime<br>required | string <RFC3339>  \[ 20 .. 29 \] characters <br>When the consent was created in either an initiated or active state.<br>Example: "2021-01-12T16:15:21.672Z" |
| expirationDateTime<br>required | string <RFC3339>  \[ 20 .. 29 \] characters <br>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.<br>Format is based on RFC 3339, with the following stipulations: <br>- ‘T’ is used as separator between date and time.<br>- Only fractional seconds are optional - all other parts of the datetime are required.<br>- Fractional seconds may contain up to 3 decimal places. <br>- All datetimes will be converted to GMT (+00:00) for storage and subsequent retrieval.<br>Example: "2026-02-05T17:31:00Z" |
| frequency<br>required | string<br>Default: "STREAMING"<br>An enum representing the consent frequency.<br>- `STREAMING`:<br>  - The consent item types in the consent are made available on a streaming basis, whenever a triggering event occurs.<br>- `PERIODIC`:<br>  - The consent item types in the consent are available on a periodic basis.<br>- `ON_DEMAND`:<br>  - The consent item types in the consent are available on demand from the Resource Provider.<br>- `CONTEXT_BASED`:<br>  - The consent item types in the consent are available subject to additional filtering.<br>Enum:"STREAMING""PERIODIC""ON_DEMAND""CONTEXT_BASED" |
| presentedContentVersion<br>required | string \[ 1 .. 10 \] characters <br>The version of the content presented to the user.<br>Example: "1.0" |
| presentedLanguage<br>required | string <BCP-47>  \[ 2 .. 100 \] characters <br>The language of the content presented to the user.<br>Example: "en-US" |
| presenterOrganizationID<br>required | string <uuid> <br>This attribute identifies a previously-onboarded organization.<br>Example: "123e4567-e89b-12d3-a456-426614174000" |
| primaryPurposes<br>required | Array of objects \[ 1 .. 10 \] items <br>A list of primary consent purposes. |
| Array

|     |     |
| --- | --- |
| beneficiaryOrganizationIDs<br>required | Array of strings <uuid>  \[ 1 .. 10 \] items <br>The beneficiary IDs which are using the resource for the enclosing purpose.<br>Example: \["123e4567-e89b-12d3-a456-426614174000"\] |
| consentItemTypes<br>required | Array of strings \[ 1 .. 10 \] items <br>The consent item types.<br>Example: \["TRANSACTION_DATA"\] |
| purposeType<br>required | string \[ 0 .. 25 \] characters <br>Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location).<br>Example: "PERSONAL_FINANCE_MGMT" | |
| privacyPolicyVersion<br>required | string \[ 1 .. 10 \] characters <br>The version of the privacy policy presented to the user.<br>Example: "4.1" |
| resourceProviderOrganizationIDs<br>required | Array of strings <uuid> <br>The list of Resource Provider identifiers who are participating in this consent.<br>Example: \["123e4567-e89b-12d3-a456-426614174000"\] |
| status<br>required | string

Valid status values of consent:

- INITIATED
- ACTIVE
- REVOKED
- EXPIRED
- CONSUMED
- PAUSED

| Consent Status Value | Description |
| --- | --- |
| `INITIATED` | - This is the initial status of a consent when created/saved without successful consumer authentication.<br>  - A consent in this status cannot be used to access consent items (data or other resources). |
| `ACTIVE` | - The status of the consent is considered active when it can be used to access consent items (data or other resources).<br>  - Only after successful cardholder authentication, a consent is considered in `ACTIVE` status. |
| `REVOKED` | The consent is transitioned to this state only after it is revoked by the cardholder or by a party on behalf of the cardholder. |
| `EXPIRED` | When a consent's expiry date is reached, it is transitioned to this state. |
| `CONSUMED` | When the consent's applicability/policy is `ONE_TIME` and when the consent is used for the applicable use case, the consent is transitioned to this state. |
| `PAUSED` | 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 `ACTIVE`. |

Enum:"INITIATED""ACTIVE""REVOKED""EXPIRED""CONSUMED""PAUSED"

Example: "REVOKED" |
| updatedDateTime<br>required | string <RFC3339>  \[ 20 .. 29 \] characters <br>When the consent was last updated.<br>Example: "2021-01-12T16:15:21.672Z" |
| userID<br>required | string \[ 1 .. 320 \] characters <br>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. <br>User identifiers of type `EMAIL_ADDRESS``PHONE_NUMBER``PAN` and `CLIENT_DEFINED` are not retained as-is in the consent system, and will be returned as masked values in subsequent API responses.<br>Example: "con***@visa.com" |
| userIDType<br>required | string<br>The type of the provided user identifier (userID).<br>Enum:"EMAIL_ADDRESS""PHONE_NUMBER""VCARDID""PAN""CLIENT_DEFINED"<br>Example: "EMAIL_ADDRESS" |
| consentCaptureCity | string \[ 1 .. 80 \] characters <br>The city where the user's consent was captured.<br>Example: "Austin" |
| constraints | object<br>Additional consent constraints. |
| |     |     |
| --- | --- |
| maxNumberUses | integer <int32>  \[ 0 .. 100 \] <br>The maximum number of uses for the consent item types captured in the consent. |
| remainingNumberUses | integer <int32>  \[ 0 .. 100 \] <br>The remaining number of uses for the consent item types captured in the consent.. |
| timespan | object<br>A timespan constraint applicable for the consent item types captured in the consent.<br>For example, consent for historical transaction data may have a constraint to include only transactions from the last 6 months.<br>That constraint would be captured here. |
| |     |     |
| --- | --- |
| endDateTime | string <RFC3339>  \[ 20 .. 29 \] characters <br>End datetime.<br>Format is based on RFC 3339, with the following stipulations: <br>- ‘T’ is used as separator between date and time.<br>- Only fractional seconds are optional - all other parts of the datetime are required.<br>- Fractional seconds may contain up to 3 decimal places.<br>- All datetimes will be converted to GMT (+00:00) for storage and subsequent retrieval.<br>Example: "2022-07-12T16:15:21.672Z" |
| startDateTime | string <RFC3339>  \[ 20 .. 29 \] characters <br>Start datetime.<br>Format is based on RFC 3339, with the following stipulations: <br>- ‘T’ is used as separator between date and time.<br>- Only fractional seconds are optional - all other parts of the datetime are required.<br>- Fractional seconds may contain up to 3 decimal places.<br>- All datetimes will be converted to GMT (+00:00) for storage and retrieval.<br>Example: "2022-01-12T16:15:21.672Z" |
| consumerContactInformation | object<br>Masked contact information for the end consumer. |
| |     |     |
| --- | --- |
| emailAddress | string <Email Address>  \[ 5 .. 100 \] characters <br>Email address.<br>Example: "con***@visa.com" |
| isEmailAddressVerified | boolean<br>Indicates whether the email address has been verified by the caller. |
| isPhoneNumberVerified | boolean<br>Indicates whether the phone number has been verified by the caller. |
| phoneNumber | string \[ 7 .. 15 \] characters <br>Phone number, which may include only numerical digits.<br>Example: "***555" |
| externalConsentID | string \[ 0 .. 50 \] characters <br>A client-provided identifier for the consent being created. Uniqueness of this value should be enforced by the client.<br>Example: "qwertyK" |
| financialInstruments | Array of objects<br>The list of financial instruments applicable for this consent. |
| Array

|     |     |
| --- | --- |
| accountNumber | string \[ 1 .. 50 \] characters <br>The account number. Account numbers of type `PAYMENT_CARD``BANK_ACCOUNT` and `PAYMENT_TOKEN` are not retained in the consent system as-is, and will be returned as masked values in subsequent API responses.<br>Example: "400000******0000" |
| instrumentID | string <uuid>  36 characters <br>Unique identifier for the instance of financial instrument.<br>Example: "f38de9d8-129a-40ea-b149-b8b64a7eda33" |
| instrumentType | string<br>The type of financial instrument.<br>Enum:"PAYMENT_CARD""VCARDID""BANK_ACCOUNT""PAYMENT_TOKEN" |
| identityVerificationDetails | object<br>The Identity verification details represent an attestation of the consumer identity and the details of the authentication performed on the consumer.<br>Visa uses authentication details for various risk purposes. <br>The identity of the consumer is necessary for ensuring proper capture of the consent.<br>If the attestationType is `ID_TOKEN`, the attestation is represented by a base64 urlencoded string - a standard JWT format. |
| |     |     |
| --- | --- |
| attestation | string \[ 1 .. 2000 \] characters <br>The attestation contents, format as determined by the attestationType. |
| attestationType | string<br>The type of identity verification attestation.<br>Value:"ID_TOKEN" |
| userID | string \[ 1 .. 320 \] characters <br>The user identifier used for IDV, if it differs from the root-level userID attribute.<br>Identifiers of type `EMAIL_ADDRESS``PHONE_NUMBER``PAN` and `CLIENT_DEFINED` are not retained as-is in the consent system, and will be returned as masked values in subsequent API responses. <br>Example: "con***@visa.com" |
| userIDType | string<br>The type of the provided user identifier (userID).<br>Enum:"EMAIL_ADDRESS""PHONE_NUMBER""VCARDID""PAN""CLIENT_DEFINED"<br>Example: "EMAIL_ADDRESS" |
| previousConsentID | string <uuid> <br>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.<br>Example: "" |
| secondaryPurposes | Array of objects \[ 1 .. 10 \] items <br>A list of secondary consent purposes. |
| Array

|     |     |
| --- | --- |
| beneficiaryOrganizationIDs<br>required | Array of strings <uuid>  \[ 1 .. 10 \] items <br>The beneficiary IDs which are using the resource for the enclosing purpose.<br>Example: \["123e4567-e89b-12d3-a456-426614174000"\] |
| consentItemTypes<br>required | Array of strings \[ 1 .. 10 \] items <br>The consent item types.<br>Example: \["TRANSACTION_DATA"\] |
| isOptedIn<br>required | boolean<br>Indicator as to whether the secondary consent was opted in or out by the consumer.<br>A value of true indicates the the consumer opted in to the secondary purpose. |
| purposeType<br>required | string \[ 0 .. 25 \] characters <br>Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location).<br>Example: "PERSONAL_FINANCE_MGMT" |

### 400
The `details` part of the error response can provide a list of fields that failed data validation constraints and reason values for this error include:
- `badRequest`The API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

##### Response Headers

##### Response Schema:     application/json                   application/json  application/problem+json

|     |     |
| --- | --- |
| reason<br>required | string \[ 1 .. 100 \] characters <br>API developers must use this field to drive their error handling logic<br>Example: "badRequest" |
| details | Array of objects<br>Array of fields - Data validation errors should use this array to specify fields that failed validation using the location field |
| Array

|     |     |
| --- | --- |
| location<br>required | string<br>The value of this field is using an expression to point to a field that failed validation.<br>This field is required if error details are specified.<br>Example: "purpose" |
| message | string <= 1024 characters <br>The specific error for this field<br>Example: "Must be a non-empty value" |
| reason | string <= 100 characters <br>The specific reason for this error<br>Example: "Must be a non-empty single word value" |
| message | string \[ 1 .. 1024 \] characters <br>Every error should have a human readable message describing the error. The message can very even for the same reason, thus providing additional details. API providers are free to change the message at any point of time. API clients should not use the message field to drive their business logic or to expose it directly to the consumers via UI or other means.<br>Example: "Input parameters validation failed" |

### 401
API authorized error caused due to any of the following reasons:
- x-pay-token is not present, blank, or not in a valid format.
- Timestamp field not in valid UTC timestamp format.
- Version field is invalid.
- Token's timestamp is more than 8 minutes off from the current time.
- Token hash mismatch.
- APIKey not present in request.
- APIKey is not active.
- APIKey not valid.
- APIKey not active.
- Request has more than one authentication token, which is not supported

##### Response Headers

##### Response Schema:     application/json                   application/json  application/problem+json

### 403
The 403 (Forbidden) HTTP Status code indicates that this Visa Developer Center project does not have permission to access the requested resource.
This can happen if you are trying to invoke an API request for a resource that is not part of your project.

### 404
The specified resource was not found

### 406
Not Acceptable - Indicates that the "Accept:" header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable.
### 409
The current state of consent is incompatible with the requested mutation. For example, an EXPIRED consent cannot be revoked.
### 410
Gone - Indicates that the resource at this end point is no longer available.
### 429
The Visa Developer Center project has clocked too many requests in a given amount of time.