Visa Consent Management Service API Reference
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 required |
string Consent identifier. |
header Parameters
| X-Correlation-Id | string [ 1 .. 36 ] characters 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 The reason for the consent revocation. Example: "User-initiated" |
Responses
200 Updated consent.
| X-Correlation-Id | string [ 1 .. 36 ] characters Unique ID for the API response; X-Correlation-Id is echoed back. Used for end-to-end tracing/debugging. |
Response Schema: application/json
| consentCaptureCountry
required | string <ISO 3166-1 alpha 2> 2 characters
The country where the user's consent was captured.
Example: "US" |
| consentCaptureDateTime
required | string
The date and time that the consent was captured from the user, in the user's local time zone.
Format is based on RFC 3339, with the following stipulations:
- ‘T’ is used as separator between date and time.
- Only fractional seconds are optional - all other parts of the datetime are required.
- Fractional seconds may contain up to 3 decimal places.
- The time zone provided will be maintained and returned on subsequent retrieval.
Example: "2021-01-12T10:15:20.343-06:00" |
| consentCaptureRegionState
required | string <ISO 3166-2 subdivision> [ 1 .. 3 ] characters
The region or state where the user's consent was captured, represented as the subdivision part of ISO 3166-2.
Example: "TX" |
| consentDirectoryID
required | string
This value refers to a previously-configured Consent Directory entry, in whose context a consent may be created.
Example: "123e4567-e89b-12d3-a456-426614174000" |
| consentID
required | string
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.
Example: "123e4567-e89b-12d3-a456-426614174000" |
| createdDateTime
required | string
When the consent was created in either an initiated or active state.
Example: "2021-01-12T16:15:21.672Z" |
| expirationDateTime
required | string
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.
Format is based on RFC 3339, with the following stipulations:
- ‘T’ is used as separator between date and time.
- Only fractional seconds are optional - all other parts of the datetime are required.
- Fractional seconds may contain up to 3 decimal places.
- All datetimes will be converted to GMT (+00:00) for storage and subsequent retrieval.
Example: "2026-02-05T17:31:00Z" |
| frequency
required | string
Default: "STREAMING"
An enum representing the consent frequency.
- STREAMING:
- The consent item types in the consent are made available on a streaming basis, whenever a triggering event occurs.
- PERIODIC:
- The consent item types in the consent are available on a periodic basis.
- ON_DEMAND:
- The consent item types in the consent are available on demand from the Resource Provider.
- CONTEXT_BASED:
- The consent item types in the consent are available subject to additional filtering.
Enum:"STREAMING""PERIODIC""ON_DEMAND""CONTEXT_BASED" |
| presentedContentVersion
required | string [ 1 .. 10 ] characters
The version of the content presented to the user.
Example: "1.0" |
| presentedLanguage
required | string
The language of the content presented to the user.
Example: "en-US" |
| presenterOrganizationID
required | string
This attribute identifies a previously-onboarded organization.
Example: "123e4567-e89b-12d3-a456-426614174000" |
| primaryPurposes
required | Array of objects [ 1 .. 10 ] items
A list of primary consent purposes. |
| Array
| beneficiaryOrganizationIDs required |
Array of strings The beneficiary IDs which are using the resource for the enclosing purpose. Example: ["123e4567-e89b-12d3-a456-426614174000"] |
| consentItemTypes required |
Array of strings [ 1 .. 10 ] items The consent item types. Example: ["TRANSACTION_DATA"] |
| purposeType required |
string [ 0 .. 25 ] characters Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location). Example: "PERSONAL_FINANCE_MGMT" |
| privacyPolicyVersion required |
string [ 1 .. 10 ] characters The version of the privacy policy presented to the user. Example: "4.1" |
| resourceProviderOrganizationIDs required |
Array of strings The list of Resource Provider identifiers who are participating in this consent. Example: ["123e4567-e89b-12d3-a456-426614174000"] |
| status 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. - 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). - 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
required | string
When the consent was last updated.
Example: "2021-01-12T16:15:21.672Z" |
| userID
required | string [ 1 .. 320 ] characters
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.
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.
Example: "con***@visa.com" |
| userIDType
required | string
The type of the provided user identifier (userID).
Enum:"EMAIL_ADDRESS""PHONE_NUMBER""VCARDID""PAN""CLIENT_DEFINED"
Example: "EMAIL_ADDRESS" |
| consentCaptureCity | string [ 1 .. 80 ] characters
The city where the user's consent was captured.
Example: "Austin" |
| constraints | object
Additional consent constraints. |
| | | |
| --- | --- |
| maxNumberUses | integer
The maximum number of uses for the consent item types captured in the consent. |
| remainingNumberUses | integer
The remaining number of uses for the consent item types captured in the consent.. |
| timespan | object
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. |
| | | |
| --- | --- |
| endDateTime | string
End datetime.
Format is based on RFC 3339, with the following stipulations:
- ‘T’ is used as separator between date and time.
- Only fractional seconds are optional - all other parts of the datetime are required.
- Fractional seconds may contain up to 3 decimal places.
- All datetimes will be converted to GMT (+00:00) for storage and subsequent retrieval.
Example: "2022-07-12T16:15:21.672Z" |
| startDateTime | string
Start datetime.
Format is based on RFC 3339, with the following stipulations:
- ‘T’ is used as separator between date and time.
- Only fractional seconds are optional - all other parts of the datetime are required.
- Fractional seconds may contain up to 3 decimal places.
- All datetimes will be converted to GMT (+00:00) for storage and retrieval.
Example: "2022-01-12T16:15:21.672Z" |
| consumerContactInformation | object
Masked contact information for the end consumer. |
| | | |
| --- | --- |
| emailAddress | string
Email address.
Example: "con***@visa.com" |
| isEmailAddressVerified | boolean
Indicates whether the email address has been verified by the caller. |
| isPhoneNumberVerified | boolean
Indicates whether the phone number has been verified by the caller. |
| phoneNumber | string [ 7 .. 15 ] characters
Phone number, which may include only numerical digits.
Example: "***555" |
| externalConsentID | string [ 0 .. 50 ] characters
A client-provided identifier for the consent being created. Uniqueness of this value should be enforced by the client.
Example: "qwertyK" |
| financialInstruments | Array of objects
The list of financial instruments applicable for this consent. |
| Array
| accountNumber | string [ 1 .. 50 ] characters 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.Example: "400000******0000" |
| instrumentID | string Unique identifier for the instance of financial instrument. Example: "f38de9d8-129a-40ea-b149-b8b64a7eda33" |
| instrumentType | string The type of financial instrument. Enum:"PAYMENT_CARD""VCARDID""BANK_ACCOUNT""PAYMENT_TOKEN" |
| identityVerificationDetails | object The Identity verification details represent an attestation of the consumer identity and the details of the authentication performed on the consumer. Visa uses authentication details for various risk purposes. The identity of the consumer is necessary for ensuring proper capture of the consent. If the attestationType is ID_TOKEN, the attestation is represented by a base64 urlencoded string - a standard JWT format. |
| --- | --- |
| attestation | string [ 1 .. 2000 ] characters The attestation contents, format as determined by the attestationType. |
| attestationType | string The type of identity verification attestation. Value:"ID_TOKEN" |
| userID | string [ 1 .. 320 ] characters The user identifier used for IDV, if it differs from the root-level userID attribute. 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. Example: "con***@visa.com" |
| userIDType | string The type of the provided user identifier (userID). Enum:"EMAIL_ADDRESS""PHONE_NUMBER""VCARDID""PAN""CLIENT_DEFINED" Example: "EMAIL_ADDRESS" |
| previousConsentID | string 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: "" |
| secondaryPurposes | Array of objects [ 1 .. 10 ] items A list of secondary consent purposes. |
| Array |
| beneficiaryOrganizationIDs required |
Array of strings The beneficiary IDs which are using the resource for the enclosing purpose. Example: ["123e4567-e89b-12d3-a456-426614174000"] |
| consentItemTypes required |
Array of strings [ 1 .. 10 ] items The consent item types. Example: ["TRANSACTION_DATA"] |
| isOptedIn required |
boolean 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. |
| purposeType required |
string [ 0 .. 25 ] characters Represents the consent purpose. The set of possible values is contained in the data dictionary for Purposes (TBD location). 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:
badRequestThe 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 required |
string [ 1 .. 100 ] characters API developers must use this field to drive their error handling logic Example: "badRequest" |
| details | Array of objects Array of fields - Data validation errors should use this array to specify fields that failed validation using the location field |
| Array |
| location required |
string The value of this field is using an expression to point to a field that failed validation. This field is required if error details are specified. Example: "purpose" |
| message | string <= 1024 characters The specific error for this field Example: "Must be a non-empty value" |
| reason | string <= 100 characters The specific reason for this error Example: "Must be a non-empty single word value" |
| message | string [ 1 .. 1024 ] characters 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. 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.