invalidConsentStateTransition 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; X-Correlation-Id
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
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
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 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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'409':
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the
requested mutation. For example, an EXPIRED consent cannot
be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}~1revoke/post"
default: false
x-hideTryIt: true
"/vcms/v1/consents/{consentID}/constraints/remainingNumberUses":
put:
tags:
- Visa Consent Management API
summary: Update Remaining Consent Uses
description: |-
API for Visa partners (Consent Requestors) to update the remaining number of uses for a multi-use consent.
Notes:
+ This API is idempotent.
+ For an active consent, this value may be set to less than or equal to the current value, and only if maxNumberUses is set as non-zero on the consent. Any violation of the above conditions will result in a 409 error with invalidConsentModification reason. If set to zero, the status of the consent changes to CONSUMED and is no longer active.
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: Consent request body for PUT remaining number of uses.
content:
application/json:
schema:
title: Consent update request body for Consent remaining number of uses
PUT
required:
- status
type: object
properties:
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
required: true
responses:
'200':
description: 'Consent remainingNumberUses updated successfully
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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:
properties:
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
'400':
description: |
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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'409':
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the
requested mutation. For example, an EXPIRED consent cannot
be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}~1constraints~1remainingNumberUses/put"
default: false
x-hideTryIt: true
"/vcms/v1/consents":
post:
tags:
- Visa Consent Management API
summary: Save Consent
description: |-
API for Visa partners (Consent Requestors) to save a consumer-granted consent.
Notes:
+ This API is not idempotent, and there is no duplicate check to prevent clients from creating multiple consents with the same values.
+ The associated Consent Directory entry determines which, if any, identity verification attestation is required.
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
requestBody:
description: Consent request body for transaction data.
content:
application/json:
schema:
title: Transaction Data Consent object as it is used in the HTTP request
for creation
type: object
example:
userID: abcdef
frequency: PERIODIC
userIDType: CLIENT_DEFINED
constraints:
timespan:
endDateTime: '2024-09-07T00:00:00Z'
startDateTime: '2023-09-07T00:00:00Z'
maxNumberUses: '10'
primaryPurposes:
- purposeType: LOYALTYTPA
consentItemTypes:
- PAYMENTS_BILLPAY
beneficiaryOrganizationIDs:
- 332d32d4-df93-4133-bf5e-b269111bf7b3
externalConsentID: Queryrb
presentedLanguage: en-US
previousConsentID: ''
consentCaptureCity: Austin
consentDirectoryID: 189ab0a9-9ba9-4c1c-a750-06c68b33f5d3
expirationDateTime: '2024-09-07T00:00:00Z'
financialInstruments:
- accountNumber: '4000000000000001'
instrumentType: PAYMENT_CARD
privacyPolicyVersion: '1.0'
consentCaptureCountry: US
consentCaptureDateTime: '2023-09-07T00:00:00Z'
presentedContentVersion: '1.0'
presenterOrganizationID: 332d32d4-df93-4133-bf5e-b269111bf7b1
consentCaptureRegionState: AU
consumerContactInformation:
phoneNumber: "+919709193274"
emailAddress: bhawesh@visa.com
isPhoneNumberVerified: 'true'
isEmailAddressVerified: 'true'
identityVerificationDetails:
userID: consumer@visa.com
userIDType: EMAIL_ADDRESS
attestation: abc
attestationType: ID_TOKEN
resourceProviderOrganizationIDs:
- 332d32d4-df93-4133-bf5e-b269111bf7b4
allOf:
- properties:
userID:
title: 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 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.\n"
example: consumer@visa.com
- 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.
* 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.
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 subsequent 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 subsequent 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.
Not applicable to consents with STREAMING frequency.
maxNumberUses:
maximum: 100
minimum: 0
type: integer
description: 'The maximum number of uses for the consent item
types captured in the consent. Not applicable to consents
with STREAMING frequency.
'
format: int32
description: 'Additional consent constraints.
'
financialInstruments:
type: array
description: 'The list of financial instruments applicable for
this consent.
'
items:
title: Financial Instrument
required:
- accountNumber
- instrumentType
type: object
properties:
accountNumber:
maxLength: 42
minLength: 9
type: string
description: |
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
consumerContactInformation:
title: Consumer Contact Information
type: object
properties:
phoneNumber:
maxLength: 15
minLength: 7
type: string
description: 'Phone number, which may include only numerical
digits.
'
example: '15555555555'
emailAddress:
maxLength: 100
minLength: 5
type: string
description: 'Email address.
'
format: Email Address
example: consumer@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: 'Contact information for the end consumer.
'
identityVerificationDetails:
title: Identity verification details
required:
- attestation
- attestationType
type: object
properties:
userID:
description: "The user identifier used for IDV, if it differs
from the root-level userID attribute. \nIdentifiers 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.\n"
allOf:
- title: 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 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.\n"
example: consumer@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.
'
example: abc123
attestationType:
type: string
description: 'The type of identity verification attestation.
'
enum:
- ID_TOKEN
- THREED_SECURE
description: "The Identity verification details represent an attestation
of the consumer identity and the details of the authentication
performed on the consumer.ID_TOKEN, the attestation
is represented by a base64 urlencoded string - a standard JWT
format.userID attribute. If userID is specified,
then userIDType must also be specified.\n"
- required:
- consentCaptureCountry
- consentCaptureDateTime
- consentCaptureRegionState
- consentDirectoryID
- expirationDateTime
- frequency
- presentedContentVersion
- presentedLanguage
- presenterOrganizationID
- primaryPurposes
- privacyPolicyVersion
- resourceProviderOrganizationIDs
- userID
- userIDType
required: true
responses:
'201':
description: Consent granted (object created) successfully
headers:
Location:
description: Location
style: simple
explode: false
schema:
type: string
example: https://api.visa.com/consent-api/consents/a8023ee6-64a1-4c48-b1c8-7609faf41f1f
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
is echoed back. Used for end-to-end tracing/debugging.
style: simple
explode: false
schema:
maxLength: 36
minLength: 1
type: string
'400':
description: |
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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'409':
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the
requested mutation. For example, an EXPIRED consent cannot
be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
callbacks:
consentCreated: {}
consentAttributeChanged: {}
consentStatusChanged: {}
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents/post"
default: false
x-hideTryIt: true
"/vcms/v1/consents/{consentID}":
get:
tags:
- Visa Consent Management API
summary: Get Consent
description: This API retrieves the consent object identified by consent ID.
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
responses:
'200':
description: 'Get the consent object corresponding to consentID.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
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 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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}/get"
default: false
x-hideTryIt: true
patch:
tags:
- Visa Consent Management API
summary: Update Consent
description: Update Consent
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: Consent request body for PATCH Consent.
content:
application/json:
schema:
title: Consent update request body for Consent PATCH
type: object
properties:
status:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ ACTIVE
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
ACTIVE |
|
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.
|
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
consumerContactInformation:
title: Consumer Contact Information
type: object
properties:
phoneNumber:
maxLength: 15
minLength: 7
type: string
description: 'Phone number, which may include only numerical
digits.
'
example: "+15555555555"
emailAddress:
maxLength: 100
minLength: 5
type: string
description: 'Email address.
'
format: Email Address
example: consumer_second@visa.com
isPhoneNumberVerified:
type: boolean
description: 'Indicates whether the phone number has been verified
by the caller.
'
example: true
isEmailAddressVerified:
type: boolean
description: 'Indicates whether the email address has been verified
by the caller.
'
example: true
description: 'Contact information for the end consumer.
'
identityVerificationDetails:
title: Identity verification details
required:
- attestation
- attestationType
type: object
properties:
userID:
description: "The user identifier used for IDV, if it differs
from the root-level userID attribute. \nIdentifiers 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.\n"
allOf:
- title: 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 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.\n"
userIDType:
title: User Identifier Type
type: string
description: 'The type of the provided user identifier (userID).
'
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
- THREED_SECURE
description: "The Identity verification details represent an attestation
of the consumer identity and the details of the authentication
performed on the consumer.ID_TOKEN, the attestation is represented by a
base64 urlencoded string - a standard JWT format.userID
attribute. If userID is specified, then userIDType
must also be specified.\n"
example:
status: PAUSED
constraints:
remainingNumberUses: 5
secondaryPurposes:
- isOptedIn: true
purposeType: PERSONAL_FINANCE_MGMT
consentItemTypes:
- TRANSACTION_DATA
beneficiaryOrganizationIDs:
- 332d32d4-df93-4133-bf5e-b269111bf7b3
financialInstruments:
- accountNumber: '4000000000000001'
instrumentType: PAYMENT_CARD
consumerContactInformation:
phoneNumber: "+919999999999"
emailAddress: consumer_second@visa.com
isPhoneNumberVerified: true
isEmailAddressVerified: true
required: true
responses:
'200':
description: 'Update the consent object corresponding to consentID.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
the attestation is represented by a base64 urlencoded string
- a standard JWT format.\n"
- required:
- consentCaptureCountry
- consentCaptureDateTime
- consentCaptureRegionState
- consentID
- createdDateTime
- expirationDateTime
- periodDays
- presentedContentVersion
- presentedLanguage
- presenter
- privacyPolicyVersion
- purpose
- purposes
- resourceProviderOrganizationIDs
- status
- type
- vCardID
'400':
description: |
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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'409':
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the
requested mutation. For example, an EXPIRED consent cannot
be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}/patch"
default: false
x-hideTryIt: true
"/vcms/v1/consents/{consentID}/validate":
post:
tags:
- Visa Consent Management API
summary: Validate Consent
description: This API is used by Resource Providers to verify that a consent
is recorded against the provided user ID. If so, the consent object is returned.
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: Consent validate request body.
content:
application/json:
schema:
title: Request body for consent validate.
required:
- userID
type: object
properties:
userID:
title: 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 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.\n"
example: consumer@visa.com
identityVerificationDetails:
type: object
properties:
userID:
description: 'The user identifier used for IDV, if it differs
from the root-level userID attribute.
'
allOf:
- title: 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 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.\n"
example: consumer@visa.com
example:
userID: abcdef
identityVerificationDetails:
userID: consumer@visa.com
required: true
responses:
'200':
description: Consent response.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
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 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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'422':
description: 'The server understands the content type of the request entity,
and the syntax of the request entity is correct but was unable to process
the contained instructions.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: unprocessableEntity
message:
example: Unprocessable Entity
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}~1validate/post"
default: false
x-hideTryIt: true
"/vcms/v1/consents/{consentID}/status":
put:
tags:
- Visa Consent Management API
summary: Update Consent Status
description: |-
API for Visa partners (Consent Requestors) to update consent status.
Notes:
Status may be set in accordance with the following state transitions, with invalid transitions resulting in a 409 error with invalidConsentStateTransition reason.
+ ACTIVE -> PAUSED
+ PAUSED -> ACTIVE
+ ACTIVE -> CONSUMED
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: Consent request body for PUT Consent Status.
content:
application/json:
schema:
title: Consent update request body for Consent Status PUT
required:
- status
type: object
properties:
status:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ ACTIVE
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
ACTIVE |
|
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.
|
X-Correlation-Id
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:
properties:
status:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ ACTIVE
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
ACTIVE |
|
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.
|
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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'401':
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'403':
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'404':
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'406':
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'409':
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the
requested mutation. For example, an EXPIRED consent cannot
be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'410':
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'429':
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'500':
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
'503':
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there
is an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the
specification in RFC-7807, it is neither recommended to be
dereferenceable and point to a human-readable documentation
nor globally unique for the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in
English and readable for engineers, usually not suited for
non technical stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this
occurrence of the problem that is helpful to locate the problem
and give advice on how to proceed. Written in English and
readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this
problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
x-operationVersions:
- label: v1 - Latest
operationPointer: "#/paths/~1vcms~1v1~1consents~1{consentID}~1status/put"
default: false
x-hideTryIt: true
components:
schemas:
ConsentConstraintsForCreation:
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 subsequent
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 subsequent 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.
Not applicable to consents with STREAMING frequency.
maxNumberUses:
maximum: 100
minimum: 0
type: integer
description: 'The maximum number of uses for the consent item types captured
in the consent. Not applicable to consents with STREAMING
frequency.
'
format: int32
description: 'Additional consent constraints.
'
StandardError:
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is an error.
'
UserIdentifierType:
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
ConsentType:
title: Identifies the Usecase type or IDV/consent purpose
type: string
description: "The type of the consent describes the use cases applicable for
the consent.\nCARD_TRANSACTION_EVENTS applies to card transaction
data subscription (using webhooks/callback model), and CARD_TRANSACTION_DATA
applies to card transaction history data (using REST API request/response
model). \nThere will be other consent types applicable in the future like
PAYMENTS, etc.\n"
enum:
- CARD_TRANSACTION_DATA
- CARD_TRANSACTION_EVENTS
ConsumerContactInformation:
title: Consumer Contact Information
type: object
properties:
phoneNumber:
maxLength: 15
minLength: 7
type: string
description: 'Phone number, which may include only numerical digits.
'
example: '15555555555'
emailAddress:
maxLength: 100
minLength: 5
type: string
description: 'Email address.
'
format: Email Address
example: consumer@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: 'Contact information for the end consumer.
'
CloudEventEnvelopeSchema:
title: Message Envelope
type: object
properties:
id:
maxLength: 36
minLength: 36
type: string
description: 'Unique identifier for the message.
'
format: UUID
example: b0ea6631-cb51-fa2b-f426-150b5757e201
time:
maxLength: 29
minLength: 20
type: string
description: 'Datetime when the message was generated.
'
format: RFC3339
example: '2021-04-05T17:31:00Z'
source:
maxLength: 50
minLength: 1
type: string
description: 'Source of the message.
'
example: https://visa.com
subject:
maxLength: 39
minLength: 36
type: string
description: 'Consent identifier.
'
format: UUID
example: 01-a8023ee6-64a1-4c48-b1c8-7609faf41f1f
specversion:
maxLength: 10
minLength: 1
type: string
description: 'Version of the message envelope schema.
'
example: '1.0'
datacontenttype:
maxLength: 50
minLength: 1
type: string
description: 'Format of the message under the "data" object.
'
format: IANA Media Types
example: application/json
dataschemaversion:
maxLength: 10
minLength: 1
type: string
description: 'Extension attribute which provides a version for the schema
defined in the "data" element. Increments within a single major version
indicate that backward compatibility is preserved.
'
format: majorversion.minorversion
example: '1.0'
externalsubjectid:
maxLength: 50
minLength: 0
type: string
description: 'Client-provided consent identifier, which was optionally supplied
at consent creation in "externalConsentID".
'
example: clientdefinedidentifier123
ConsentValidateRequest:
title: Request body for consent validate.
required:
- userID
type: object
properties:
userID:
title: 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 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.\n"
example: consumer@visa.com
identityVerificationDetails:
type: object
properties:
userID:
description: 'The user identifier used for IDV, if it differs from the
root-level userID attribute.
'
allOf:
- title: 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 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.\n"
example: consumer@visa.com
AuthenticationMethod:
title: Authentication mechanism for verifying the identity of the consumer identity
or account
type: string
enum:
- CARDHOLDER_AUTH_BY_ISSUER
- VERIFIED_BY_VISA
ConsentDirectoryIdentifier:
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
TransactionDataToDate:
title: Ending point in date to fetch the card transactions when this consent
is applied for card transactions
type: string
description: |
The last point of the transaction / statement historical period that the cardholder has consented to provide access to the Consent Requestor
+ Controls the transaction data volume that is accessible to the beneficiaries using this consent.
+ Applicable especially for transaction history use cases. If transactionFromDate and transactionToDate are not specified, then beneficiaries have access any historical transaction data indefinitely until revoked.
format: date
VisaCardIdentifier:
title: Visa-generated univeral card identifier
maxLength: 42
minLength: 42
type: string
description: |
An interoperable Visa-generated card identifier scoped to the VDP project that it was created-in. It cannot be used outside this VDP project (client), unless there is a partner relationship established between the 2 VDP projects (clients).
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.\n"
example: con***@visa.com
TransactionDataConsentForCreation-1:
title: Transaction Data Consent object as it is used in the HTTP request for
creation
type: object
allOf:
- properties:
userID:
title: 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 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.\n"
example: consumer@visa.com
- 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.
* 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.
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 subsequent 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 subsequent 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.
Not applicable to consents with STREAMING frequency.
maxNumberUses:
maximum: 100
minimum: 0
type: integer
description: 'The maximum number of uses for the consent item types
captured in the consent. Not applicable to consents with STREAMING
frequency.
'
format: int32
description: 'Additional consent constraints.
'
financialInstruments:
type: array
description: 'The list of financial instruments applicable for this consent.
'
items:
title: Financial Instrument
required:
- accountNumber
- instrumentType
type: object
properties:
accountNumber:
maxLength: 42
minLength: 9
type: string
description: |
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
consumerContactInformation:
title: Consumer Contact Information
type: object
properties:
phoneNumber:
maxLength: 15
minLength: 7
type: string
description: 'Phone number, which may include only numerical digits.
'
example: "+15555555555"
emailAddress:
maxLength: 100
minLength: 5
type: string
description: 'Email address.
'
format: Email Address
example: consumer_second@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: 'Contact information for the end consumer.
'
identityVerificationDetails:
title: Identity verification details
required:
- attestation
- attestationType
type: object
properties:
userID:
description: "The user identifier used for IDV, if it differs from
the root-level userID attribute. \nIdentifiers 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.\n"
allOf:
- title: 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 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.\n"
example: consumer@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.
'
example: abc123
attestationType:
type: string
description: 'The type of identity verification attestation.
'
enum:
- ID_TOKEN
- THREED_SECURE
description: "The Identity verification details represent an attestation
of the consumer identity and the details of the authentication performed
on the consumer.ID_TOKEN,
the attestation is represented by a base64 urlencoded string - a standard
JWT format.userID
attribute. If userID is specified, then userIDType
must also be specified.\n"
- required:
- consentCaptureCountry
- consentCaptureDateTime
- consentCaptureRegionState
- consentDirectoryID
- expirationDateTime
- presentedContentVersion
- presentedLanguage
- presenterOrganizationID
- primaryPurposes
- privacyPolicyVersion
- resourceProviderOrganizationIDs
- userID
- userIDType
DeprecatedConsentPurpose:
required:
- beneficiaryOrganizationIDs
- consentItemTypes
- purposeType
type: object
properties:
isPrimary:
type: boolean
description: 'Indicates whether the purpose is the primary.
'
example: true
default: false
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
ConsentPurposes:
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
ConsentStatus:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ INITIATED
+ ACTIVE
+ REVOKED
+ EXPIRED
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
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
ConsentStatusForUpdate:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ ACTIVE
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
ACTIVE |
|
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.
|
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.\n"
example: consumer@visa.com
- 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.
* 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.
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 subsequent 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 subsequent 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.
Not applicable to consents with STREAMING frequency.
maxNumberUses:
maximum: 100
minimum: 0
type: integer
description: 'The maximum number of uses for the consent item types
captured in the consent. Not applicable to consents with STREAMING
frequency.
'
format: int32
description: 'Additional consent constraints.
'
financialInstruments:
type: array
description: 'The list of financial instruments applicable for this consent.
'
items:
title: Financial Instrument
required:
- accountNumber
- instrumentType
type: object
properties:
accountNumber:
maxLength: 42
minLength: 9
type: string
description: |
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
consumerContactInformation:
title: Consumer Contact Information
type: object
properties:
phoneNumber:
maxLength: 15
minLength: 7
type: string
description: 'Phone number, which may include only numerical digits.
'
example: '15555555555'
emailAddress:
maxLength: 100
minLength: 5
type: string
description: 'Email address.
'
format: Email Address
example: consumer@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: 'Contact information for the end consumer.
'
identityVerificationDetails:
title: Identity verification details
required:
- attestation
- attestationType
type: object
properties:
userID:
description: "The user identifier used for IDV, if it differs from
the root-level userID attribute. \nIdentifiers 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.\n"
allOf:
- title: 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 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.\n"
example: consumer@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.
'
example: abc123
attestationType:
type: string
description: 'The type of identity verification attestation.
'
enum:
- ID_TOKEN
- THREED_SECURE
description: "The Identity verification details represent an attestation
of the consumer identity and the details of the authentication performed
on the consumer.ID_TOKEN,
the attestation is represented by a base64 urlencoded string - a standard
JWT format.userID
attribute. If userID is specified, then userIDType
must also be specified.\n"
- required:
- consentCaptureCountry
- consentCaptureDateTime
- consentCaptureRegionState
- consentDirectoryID
- expirationDateTime
- frequency
- presentedContentVersion
- presentedLanguage
- presenterOrganizationID
- primaryPurposes
- privacyPolicyVersion
- resourceProviderOrganizationIDs
- userID
- userIDType
ConsentFrequency:
title: Defines the frequency criteria or policy for consent
type: string
description: |
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.
default: STREAMING
enum:
- STREAMING
- PERIODIC
- ON_DEMAND
- CONTEXT_BASED
MaskedConsumerContactInformation:
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.
'
BaseConsent:
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.
* 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.
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
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
Purpose:
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
ResourceType:
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
ConsentPeriodDays:
title: The period the consent will be valid for
minimum: 1
type: integer
description: The consent is invalid after the number of days past the activation
date. It cannot be renewed, currently. A new consent must be created after
consent expiry.
format: int32
example: 30
ConsentExpirationDate:
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'
DeprecatedConsentPurposes-1:
maxItems: 10
minItems: 1
type: array
description: 'A list of consent purposes.
'
example: []
items:
required:
- beneficiaryOrganizationIDs
- consentItemTypes
- purposeType
type: object
properties:
isPrimary:
type: boolean
description: 'Indicates whether the purpose is the primary.
'
example: true
default: false
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
ErrorResponse:
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is an error.
'
ConsentPurpose:
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
OrganizationIdentifier:
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
ConsentConstraintsForResponse:
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.
'
IDVDetails:
title: Identity verification details
required:
- attestation
- attestationType
type: object
properties:
userID:
description: "The user identifier used for IDV, if it differs from the root-level
userID attribute. \nIdentifiers 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.\n"
allOf:
- title: 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 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.\n"
example: consumer@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.
'
example: abc123
attestationType:
type: string
description: 'The type of identity verification attestation.
'
enum:
- ID_TOKEN
- THREED_SECURE
description: "The Identity verification details represent an attestation of
the consumer identity and the details of the authentication performed on the
consumer.ID_TOKEN, the attestation
is represented by a base64 urlencoded string - a standard JWT format.userID attribute. If userID
is specified, then userIDType must also be specified.\n"
TransactionDataFromDate:
title: Starting point in date to fetch the card transactions when this consent
is applied for card transactions
type: string
description: |
The earliest point of the transaction / statement historical period that the cardholder has consented to provide access to the Consent Requestor
+ Controls the transaction data volume that is accessible to the beneficiaries using this consent.
+ Applicable especially for transaction history use cases. If transactionFromDate and transactionToDate are not specified, then beneficiaries have access any historical transaction data indefinitely until revoked.
format: date
ConsentConstraintsForUpdate:
title: Consent Constraints
type: object
properties:
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.
'
FinancialInstrument:
title: Financial Instrument
required:
- accountNumber
- instrumentType
type: object
properties:
accountNumber:
maxLength: 42
minLength: 9
type: string
description: |
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
FinancialInstrumentWithID:
title: Financial Instrument with Identifier
type: object
description: 'Financial instrument representation, including identifier.
'
allOf:
- properties:
instrumentID:
maxLength: 36
minLength: 36
type: string
description: 'Visa-generated unique identifier for the instance of financial
instrument.
'
format: uuid
example: f38de9d8-129a-40ea-b149-b8b64a7eda33
- title: Financial Instrument
required:
- accountNumber
- instrumentType
type: object
properties:
accountNumber:
maxLength: 42
minLength: 9
type: string
description: |
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.
Validations by instrumentType:
+ PAYMENT_CARD : 13-16 length , numeric
+ VCARDID : 42 length, alphanumeric
+ BANK_ACCOUNT : 9-34 length alphanumeric
+ PAYMENT_TOKEN : 13-16 length , numeric
example: '4000000000000000'
instrumentType:
type: string
description: 'The type of financial instrument.
'
example: PAYMENT_CARD
enum:
- PAYMENT_CARD
- VCARDID
- BANK_ACCOUNT
- PAYMENT_TOKEN
description: 'Financial instrument representation.
'
TransactionDataConsentInResponse-1:
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
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
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.\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.
* 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.
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 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
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 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. \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 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.\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.ID_TOKEN,
the attestation is represented by a base64 urlencoded string - a standard
JWT format.\n"
- required:
- consentCaptureCountry
- consentCaptureDateTime
- consentCaptureRegionState
- consentID
- createdDateTime
- expirationDateTime
- periodDays
- presentedContentVersion
- presentedLanguage
- presenter
- privacyPolicyVersion
- purpose
- purposes
- resourceProviderOrganizationIDs
- status
- type
- vCardID
DeprecatedConsentPurposes:
maxItems: 10
minItems: 1
type: array
description: 'A list of consent purposes.
'
items:
required:
- beneficiaryOrganizationIDs
- consentItemTypes
- purposeType
type: object
properties:
isPrimary:
type: boolean
description: 'Indicates whether the purpose is the primary.
'
example: true
default: false
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
Problem:
type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem type
only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and point
to a human-readable documentation nor globally unique for the problem
type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English and
readable for engineers, usually not suited for non technical stakeholders
and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence of
the problem that is helpful to locate the problem and give advice on how
to proceed. Written in English and readable for engineers, usually not
suited for non technical stakeholders and not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server for this
occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence of
the problem, e.g. by adding a fragment identifier or sub-path to the problem
type. May be used to locate the root of this problem in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
MaskedFinancialInstrument:
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 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
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.
'
MaskedIDVDetails:
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 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. \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 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.\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.ID_TOKEN, the attestation
is represented by a base64 urlencoded string - a standard JWT format.\n"
UserIdentifier:
title: 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 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.\n"
example: consumer@visa.com
responses:
BaseErrorResponse:
description: Default Error Response
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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: 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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is an
error.
'
ServiceUnavailableError:
description: |
The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.
There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
Please contact Visa Support at developer@visa.com if the issue persists.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: notReady
message:
example: Service is unavailable
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
InputValidationErrorResponse:
description: |
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.
X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- required:
- status
- properties:
reason:
example: badRequest
message:
example: Input validation error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
ConflictError:
description: 'The current state of consent is incompatible with the requested
mutation. For example, an EXPIRED consent cannot be revoked.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: invalidConsentStateTransition
message:
example: The current state of consent is incompatible for the requested
mutation. For example, an EXPIRED consent cannot be revoked.
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
UnprocessableEntityError:
description: 'The server understands the content type of the request entity,
and the syntax of the request entity is correct but was unable to process
the contained instructions.
'
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: unprocessableEntity
message:
example: Unprocessable Entity
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
NotFoundErrorResponse:
description: The specified resource was not found
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- required:
- status
- properties:
reason:
example: notFound
message:
example: Consent not found
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
UnauthorizedErrorResponse:
description: |
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
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: Unauthorized
message:
example: Access to resource is not authorized
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
APINoLongerSupportedError:
description: |
Gone - Indicates that the resource at this end point is no longer available.
This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: Gone
message:
example: Resource no longer available
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
ForbiddenErrorResponse:
description: |
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.
Check for the following:
+ You are using a project and the credential for the project that includes the API being accessed.
+ You created a project and received sandbox credentials for the API’s being called.
+ You added the API being called to the project (if not already present) with the credentials that are being used.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: Forbidden
message:
example: Forbidden
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
InternalServerError:
description: |
Internal Server Error.
Please contact Visa Support at developer@visa.com with a complete error message, full http request and response details.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: serviceError
message:
example: Internal server error
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
TooManyRequestsError:
description: |
The Visa Developer Center project has clocked too many requests in a given amount of time.
Please contact Visa Support at developer@visa.com if you want to increase the time limits.
headers:
Retry-After:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: rateLimitExceeded
message:
example: Rate limit exceeded
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
NotAcceptableContentError:
description: |
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.
This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
headers:
X-Correlation-Id:
description: Unique ID for the API response; X-Correlation-Id
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
type: object
properties:
reason:
maxLength: 100
type: string
description: The specific reason for this error
example: Must be a non-empty single word value
message:
maxLength: 1024
type: string
description: The specific error for this field
example: Must be a non-empty value
location:
type: string
description: |
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:
maxLength: 1024
minLength: 1
type: string
description: 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
description: 'Standard error response body provided when there is
an error.
'
- properties:
reason:
example: NotAcceptable
message:
example: No acceptable media type
application/problem+json:
schema:
allOf:
- type: object
properties:
type:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that uniquely identifies the problem
type only in the context of the provided API. Opposed to the specification
in RFC-7807, it is neither recommended to be dereferenceable and
point to a human-readable documentation nor globally unique for
the problem type.
'
format: uri-reference
example: "/some/uri-reference"
default: about:blank
title:
maxLength: 100
minLength: 0
type: string
description: 'A short summary of the problem type. Written in English
and readable for engineers, usually not suited for non technical
stakeholders and not localized.
'
example: some title for the error situation
detail:
maxLength: 100
minLength: 0
type: string
description: 'A human readable explanation specific to this occurrence
of the problem that is helpful to locate the problem and give
advice on how to proceed. Written in English and readable for
engineers, usually not suited for non technical stakeholders and
not localized.
'
example: some description for the error situation
status:
maximum: 600
exclusiveMaximum: true
minimum: 100
type: integer
description: 'The HTTP status code generated by the origin server
for this occurrence of the problem.
'
format: int32
instance:
maxLength: 100
minLength: 0
type: string
description: 'A URI reference that identifies the specific occurrence
of the problem, e.g. by adding a fragment identifier or sub-path
to the problem type. May be used to locate the root of this problem
in the source code.
'
format: uri-reference
example: "/some/uri-reference#specific-occurrence-context"
parameters:
ContinuationTokenQueryParam:
name: index
in: query
required: false
explode: true
schema:
type: string
description: |
Identifier which denotes the starting point of the result set. Note that the identifiers are not contiguous, and may not be used to navigate to arbitrary pages.
The value should be used only from "_links" in the paginated result set.
TraceHeaderInRequest:
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
PostbackApiKeyQueryParam:
name: apiKey
in: query
required: true
explode: true
schema:
maxLength: 255
minLength: 1
type: string
description: postbackApiKey specified by the partner during onboarding
examples: {}
requestBodies: {}
headers:
Trace-Header-In-Response:
description: Unique ID for the API response; X-Correlation-Id is
echoed back. Used for end-to-end tracing/debugging.
style: simple
explode: false
schema:
maxLength: 36
minLength: 1
type: string
Retry-After-Header-In-Response:
description: |
Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed.
The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
Retry-After = HTTP-date || delay-seconds
examples:
+ Retry-After: Thu, 31 Dec 2020 23:59:59 GMT
+ Retry-After: 120
style: simple
explode: false
schema:
maxLength: 30
minLength: 1
type: string
callbacks:
ConsentAttributeChangedCallback:
"{callbackURL}":
post:
tags:
- Consent APIs
summary: Consent Attribute Changed Callback
description: |
These are API calls initiated by the Visa Consent System to the Visa Partner’s backend servers.
+ The callbackURL is specified by the Visa partners during onboarding.
+ Invoked whenever one or more mutable consent attributes is changed. The if details of the new consent values are required, the message recipient must fetch the consent details using the GET /consents/{consentId} API.
+ There will be 2 retries with random times from 1-30 minutes if there are any 5XX or 404 errors returned from the client/partner.
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
requestBody:
content:
application/json:
schema:
allOf:
- title: Message Envelope
type: object
properties:
id:
maxLength: 36
minLength: 36
type: string
description: 'Unique identifier for the message.
'
format: UUID
example: b0ea6631-cb51-fa2b-f426-150b5757e201
time:
maxLength: 29
minLength: 20
type: string
description: 'Datetime when the message was generated.
'
format: RFC3339
example: '2021-04-05T17:31:00Z'
source:
maxLength: 50
minLength: 1
type: string
description: 'Source of the message.
'
example: https://visa.com
subject:
maxLength: 39
minLength: 36
type: string
description: 'Consent identifier.
'
format: UUID
example: 01-a8023ee6-64a1-4c48-b1c8-7609faf41f1f
specversion:
maxLength: 10
minLength: 1
type: string
description: 'Version of the message envelope schema.
'
example: '1.0'
datacontenttype:
maxLength: 50
minLength: 1
type: string
description: 'Format of the message under the "data" object.
'
format: IANA Media Types
example: application/json
dataschemaversion:
maxLength: 10
minLength: 1
type: string
description: 'Extension attribute which provides a version
for the schema defined in the "data" element. Increments
within a single major version indicate that backward compatibility
is preserved.
'
format: majorversion.minorversion
example: '1.0'
externalsubjectid:
maxLength: 50
minLength: 0
type: string
description: 'Client-provided consent identifier, which was
optionally supplied at consent creation in "externalConsentID".
'
example: clientdefinedidentifier123
- properties:
data:
type: object
type:
type: string
description: 'Name of the event. Name will be "com.visa.consent.attribute_changed".
'
example: com.visa.consent.attribute_changed
responses:
'401':
description: 'Authorization error.
'
'403':
description: Forbidden
'500':
description: Internal Server Error
'503':
description: Service Unavailable
2XX:
description: Callback successfully processed; no retries will be performed.
ConsentStatusChangedCallback:
"{callbackURL}":
post:
tags:
- Consent APIs
summary: Consent Status Changed Callback
description: |
These are API calls initiated by the Visa Consent System to the Visa Partner’s backend servers.
+ The callbackURL is specified by the Visa partners during onboarding.
+ Invoked whenever a consent changes status.
+ There will be 2 retries with random times from 1-30 minutes if there are any 5XX or 404 errors returned from the client/partner.
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
requestBody:
content:
application/json:
schema:
allOf:
- title: Message Envelope
type: object
properties:
id:
maxLength: 36
minLength: 36
type: string
description: 'Unique identifier for the message.
'
format: UUID
example: b0ea6631-cb51-fa2b-f426-150b5757e201
time:
maxLength: 29
minLength: 20
type: string
description: 'Datetime when the message was generated.
'
format: RFC3339
example: '2021-04-05T17:31:00Z'
source:
maxLength: 50
minLength: 1
type: string
description: 'Source of the message.
'
example: https://visa.com
subject:
maxLength: 39
minLength: 36
type: string
description: 'Consent identifier.
'
format: UUID
example: 01-a8023ee6-64a1-4c48-b1c8-7609faf41f1f
specversion:
maxLength: 10
minLength: 1
type: string
description: 'Version of the message envelope schema.
'
example: '1.0'
datacontenttype:
maxLength: 50
minLength: 1
type: string
description: 'Format of the message under the "data" object.
'
format: IANA Media Types
example: application/json
dataschemaversion:
maxLength: 10
minLength: 1
type: string
description: 'Extension attribute which provides a version
for the schema defined in the "data" element. Increments
within a single major version indicate that backward compatibility
is preserved.
'
format: majorversion.minorversion
example: '1.0'
externalsubjectid:
maxLength: 50
minLength: 0
type: string
description: 'Client-provided consent identifier, which was
optionally supplied at consent creation in "externalConsentID".
'
example: clientdefinedidentifier123
- properties:
data:
type: object
properties:
message:
type: string
description: 'Text description of the status change.
'
example: Consent revoked
newStatus:
title: Status of consent
type: string
description: |
Valid status values of consent:
+ INITIATED
+ ACTIVE
+ REVOKED
+ EXPIRED
+ CONSUMED
+ PAUSED
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
| Consent Status Value | Description |
INITIATED |
|
ACTIVE |
|
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.
|
callbackURL is specified by the Visa partners during onboarding.
+ Invoked whenever a consent is created. The if details of the consent are required, the message recipient must fetch the consent details using the GET /consents/{consentId} API.
+ There will be 2 retries with random times from 1-30 minutes if there are any 5XX or 404 errors returned from the client/partner.
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
requestBody:
content:
application/json:
schema:
allOf:
- title: Message Envelope
type: object
properties:
id:
maxLength: 36
minLength: 36
type: string
description: 'Unique identifier for the message.
'
format: UUID
example: b0ea6631-cb51-fa2b-f426-150b5757e201
time:
maxLength: 29
minLength: 20
type: string
description: 'Datetime when the message was generated.
'
format: RFC3339
example: '2021-04-05T17:31:00Z'
source:
maxLength: 50
minLength: 1
type: string
description: 'Source of the message.
'
example: https://visa.com
subject:
maxLength: 39
minLength: 36
type: string
description: 'Consent identifier.
'
format: UUID
example: 01-a8023ee6-64a1-4c48-b1c8-7609faf41f1f
specversion:
maxLength: 10
minLength: 1
type: string
description: 'Version of the message envelope schema.
'
example: '1.0'
datacontenttype:
maxLength: 50
minLength: 1
type: string
description: 'Format of the message under the "data" object.
'
format: IANA Media Types
example: application/json
dataschemaversion:
maxLength: 10
minLength: 1
type: string
description: 'Extension attribute which provides a version
for the schema defined in the "data" element. Increments
within a single major version indicate that backward compatibility
is preserved.
'
format: majorversion.minorversion
example: '1.0'
externalsubjectid:
maxLength: 50
minLength: 0
type: string
description: 'Client-provided consent identifier, which was
optionally supplied at consent creation in "externalConsentID".
'
example: clientdefinedidentifier123
- properties:
data:
type: object
type:
type: string
description: 'Name of the event. Name will be "com.visa.consent.consent_created".
'
example: com.visa.consent.consent_created
responses:
'401':
description: 'Authorization error.
'
'403':
description: Forbidden
'500':
description: Internal Server Error
'503':
description: Service Unavailable
2XX:
description: Callback successfully processed; no retries will be performed.
x-tagGroups:
- name: API Reference
tags:
- Visa Consent Management API