openapi: 3.0.1
info:
title: Visa Card Program Management
description: ''
version: '1'
servers:
- url: https://sandbox.api.visa.com
description: Sandbox server
security: []
tags:
- name: 'Visa Card Program Enrollment '
description: >-
VCPE supports issuers that want to offer instant/digital issuance or
re-issuance; as well as allow their cardholders to upgrade and downgrade
cards in their banking app and enjoy new rewards programs in near
real-time without needing a physical card and without changing their
16-digit card number.
paths:
/vcpe/v2/pan/enrollment:
post:
tags:
- 'Visa Card Program Enrollment '
summary: Enrollment
description: Process enrollment and handover message to ALM.
operationId: enrollmentV2UsingPOST
parameters:
- name: Accept
in: header
description: >-
Content-Types that are acceptable for the response. Example-
application/json
required: true
explode: false
allowReserved: false
schema:
type: string
- name: Accept-Language
in: header
description: >-
List of acceptable languages for the response. Defaults to en-US if
not present. Example- en-US
required: false
explode: false
allowReserved: false
schema:
type: string
- name: Content-Type
in: header
description: The type of the request body. Example- application/json
required: true
explode: false
allowReserved: false
schema:
type: string
- name: Content-Language
in: header
description: >-
The language of the request body. Defaults to en-US if not present.
Example- en-US
required: false
explode: false
schema:
type: string
requestBody:
content:
application/json:
schema:
required:
- operationType
- updateReferenceID
type: object
properties:
operationType:
type: string
description: >-
Type of operation. Format: It is one of the following
values:
UPDATE
enrollmentInfo:
type: object
properties:
cardholderInfo:
required:
- primaryAccountNumber
type: object
properties:
primaryAccountNumber:
maxLength: 19
type: string
description: Primary account number
description: Required
accountLevelInfo:
type: object
properties:
productID:
maxLength: 2
type: string
description: >-
This is the product ID for the card number in the
Account Number field. It is required, when the
rpinEnrollment structure is provided in the request,
or when the linkEnrollment structure is present for
either the USHNW or VIRTUAL groupType. For example
if the product type of the card is Visa Traditional
Credit, the value of productID is A.
linkEnrollment:
type: object
properties:
group:
type: array
description: Required. Array of Groups
items:
type: object
properties:
action:
type: string
description: >-
(REQUIRED if linkEnrollment segment is
present)
Action taken on the record for an enrollment link. Format: It is one of the following values:
Add Record is for a new link.
Delete Record is for removing a link.
Change Can only be used to change the Primary Account flag.
groupID:
maxLength: 32
type: string
description: >-
(REQUIRED if linkEnrollment segment is
present)
Contains the issuer-supplied identifier for the group type specified in the Group Type field. Must not be PAI/PII data. Format: String; alphabetic, numeric, hyphens ( - ), and underscores ( _) [a-zA-Z0-9-_ ].
groupType:
type: string
description: >-
(REQUIRED if linkEnrollment segment is
present)
Group type. Format: It is one of the following values:
LOC Groups a primary card account with
authorized accounts from other
cardholders.
CUSTOMER Groups a set of card accounts for the same cardholder.
VIRTUAL Groups a primary card account with a set of virtual cards.
Note: A value for productID must be specified. Contact your Visa representative before
submitting a request using the VIRTUAL Group Type.
USHNW
Note: A value for productID must be specified.
A variety of customized Group Types may be available, depending on region, issuer, or other criteria. Additional Group Types and values for those Group Types may be required, depending on region, issuer, or other criteria. For information on these Group Types, see their respective Product Implementation Guides. Issuers should consult the respective Product Implementation Guides for details on how to submit primary/supplementary flags to generate accurate billing information for those related products with associated card fees. For more information, contact your Visa representative.
isPrimaryAccount:
type: string
description: >-
(Conditional) Whether the account the
account number is to be the primary
account number in the group.. Used for
group types that have a primary or owner
account. It is required when groupType is
LOC, or VIRTUAL. It should be set to Y for
Primary (physical plastic card). Issuers
should refer to the Product Implementation
Guide for requirements related to custom
group types. Format: It is one of the
following values:
Y The account number is to be the primary account number in the group.
BlankThe account number is not the primary account number.
description: >-
Optional. Contains linking information for the
account number. Link enrollment information is not
required when sending request only for RPIN
enrollment or replace enrollment.
rpinEnrollment:
type: object
properties:
rpin:
maxLength: 6
type: string
description: |2-
(REQUIRED if rpinEnrollment segment is present)
The six-digit Visa-provided Registered Program Identification Number (RPIN) in which this account is enrolled. The RPINs product ID in the Visa system must match the product ID provided in the web service call. Format: String; numeric; max length 6 characters.
action:
type: string
description: >-
(REQUIRED if rpinEnrollment segment is present)
Action for RPIN Enrollment. Format: It is one of the following values:
Add Use Add when submitting new card numbers;
record is for a new account number. All required
fields must be provided.
Change Use if changing any attribute in
rpinEnrollment data. A change record will fully
replace all data in the original record. Every
required field must be submitted in a change
record. If issuers wish to preserve previously
submitted optional data, this data must be
resubmitted.
Delete Use if removing an account number. For
delete records, all other fields are optional.
accountOpenDate:
maxLength: 10
type: string
description: |-
(REQUIRED if rpinEnrollment segment is present)
The date the account number was first opened with the issuer. Format: String in the form of YYYYMMDD.
rpinEffectiveDate:
maxLength: 10
type: string
description: >-
(Optional) The RPIN effective date, which can be
a past or future date, but it must be a date
that is after the RPIN create-date and before
the RPIN end-date. If the date does not follow
these rules, the request is rejected with an
Invalid Date reject reason. It will default to
the current date if the correct date is not
provided. Format: String; YYYYMMDD.
description: >-
Optional. Contains information to enroll the account
number in a given Registered Program Identification
Number (RPIN). This field is not required when
sending request only for linking or replacement.
replaceEnrollment:
type: object
properties:
linkReasonCode:
maxLength: 1
type: string
description: >-
(Conditional) The reason for replacement.
Format: It is one of the following values:
L Lost: Consumer reports the card has been lost.
S Stolen: Consumer reports the card has been stolen.
U Upgrade/Downgrade: Consumer has been issued a new product.
O Other: Used when no other value applies.
C Converted
R Reissued
N Not known
unlinkIndicator:
maxLength: 1
type: string
description: >-
(Conditional) Unlink indicator. This must be set
to Y when deleting a replacement relationship.
Format: It is one of the following values:
Y User is trying to unlink the account number
oldAccountNumber:
maxLength: 19
type: string
description: >-
(REQUIRED if replaceEnrollment segment is
present)
A valid account number specifying the card is being replaced by the card number in the Account Number field.
description: >-
Optional. Contains information about card
replacement for the account number. This information
can be sent independently of other structures such
as rpinEnrollment or linkEnrollment
customerContactInfo:
type: object
properties:
email:
maxLength: 100
type: string
description: >-
(Conditional) Account holders email address.
Required when prefMethodOfContact is E.
action:
type: string
description: >-
(REQUIRED if customerContactInfo segment is
present)
If an action other than Add is selected, the webservice call will be rejected.
Format: It is one of the following values:
Add Use this to add new customer information. All required fields must be provided.
address:
type: object
properties:
zip:
maxLength: 5
type: string
description: >-
(Conditional) Account holders zipcode.
Required for the US, but can be left blank
for a non-US address. Format: String;
numeric.
city:
maxLength: 30
type: string
description: >-
(REQUIRED if customerContactInfo segment is
present)
City associated with the account holders address. Format: String; alphanumeric; UTF-8, white space, carat (^), period (.), single quote (), asterisk (*), and hyphen (-) are allowed.
line1:
maxLength: 40
type: string
description: >-
(Required) First line associated with the
account holders address. Format: String;
alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:),
forward slash (/), period (.), single quote
(), asterisk (*), and hyphen (-) are
allowed.
line2:
maxLength: 40
type: string
description: >-
(Optional) Second line associated with the
account holders address. Format: String;
alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:),
forward slash (/), period (.), single quote
(), asterisk (*), and hyphen (-) are
allowed.
state:
maxLength: 2
type: string
description: >-
(Conditional) State or province code
associated with the account holders
address. Required for the US, but can be
left blank for a non-US address. Example: NY
Format: String; ISO 3166-2.
companyName:
maxLength: 40
type: string
description: >-
(Conditional) Account holders company name.
Format: String; alphanumeric; UTF-8, white
space, comma (,), underscore (_), hashtag
(#), colon (:), forward slash (/), period
(.), single quote (), and hyphens (-) are
allowed.
description: >-
(Optional) Address details for the account
holder.
lastName:
maxLength: 25
type: string
description: >-
(REQUIRED if customerContactInfo segment is
present)
Account holders last name.
firstName:
maxLength: 15
type: string
description: >-
(REQUIRED if customerContactInfo segment is
present)
Account holders first name.
namePrefix:
maxLength: 5
type: string
description: (Optional) Account holders name prefix.
nameSuffix:
maxLength: 5
type: string
description: (Optional) Account holders name suffix.
mobileNumber:
maxLength: 10
type: string
description: >-
(Conditional) Account holders telephone number.
Required when prefMethodOfContact is C.
middleInitial:
maxLength: 1
type: string
description: (Optional) Account holders middle initial.
prefMethodOfContact:
maxLength: 1
type: string
description: >-
(Optional) Account holders preferred method of
contact; if a space or an empty string is
specified, the preferred method of contact is no
preference.
Format: It is one of the following values: M Physical mail.
E E mail.
C Mobile telephone.
description: >-
Optional, Contains account-number-specific
information such as name and address. It is only
accepted for certain Visa Product IDs but ignored
for all other product IDs. When specified, it must
have the accompanying rpinEnrollment structure in
its entirety.
updateReferenceID:
maxLength: 32
type: string
description: >-
Reference ID that is needed to track all account level
updates.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
'202':
description: Accepted. Request successfully persisted to queue.
'400':
description: Bad request. Incorrect parameters supplied.
'500':
description: Internal Server Error.
x-operationVersions:
- label: v2 - Latest
operationPointer: '#/paths/~1vcpe~1v2~1pan~1enrollment/post'
default: false
x-hideTryIt: true
components:
schemas:
date:
type: string
description: Date in GMT
format: date
Locale:
title: Locale
maxLength: 12
minLength: 2
pattern: ([a-zA-Z]{2,8})-([a-zA-Z]{2}|[0-9]{3})
type: string
description: >
Locale in in [IETF BCP 47 format](https://tools.ietf.org/html/bcp47)
The BCP 47 locale format is <Language Subtag>-<Extended Language Subtag
(Optional)>-<Script Subtag (Optional)>-<Region Subtag
(Optional)>-<Variant1 Subtag (Optional)>-<Variant2 Subtag (Optional)>
However, only following locale formats are supported by VCPE API:
<Language Subtag>-<Region Subtag>
Language Subtag: [a-zA-Z]{2,8}
Region Subtag: [a-zA-Z]{2} | [0-9]{3}
example: en-US
dateTime:
type: string
description: date Time in GMT
format: date-time
example: '2017-07-21T17:32:28Z'
StandardError:
title: Standard Error Response Structure
required:
- errorResponse
type: object
properties:
errorResponse:
$ref: '#/components/schemas/ErrorResponse'
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.
InvalidRpin:
type: object
properties:
result:
type: boolean
enum:
- false
errorMsg:
type: string
enum:
- INVALID_RPIN
errorCode:
type: string
enum:
- '2'
invalidRpin:
$ref: '#/components/schemas/rpin'
RpinAttributes:
title: RPIN Metadata Details
type: object
properties:
rpin:
$ref: '#/components/schemas/rpin'
country:
type: string
description: The country to which the RPIN belongs
example: '036'
endDate:
$ref: '#/components/schemas/date'
rpinBid:
$ref: '#/components/schemas/bid'
rpinName:
type: string
description: The RPIN Name.
example: VTR Premium
vertical:
type: string
description: The Vertical type
format: enum
example: CASHBACK
enum:
- CASHBACK
- COHOTEL
- COAIRLINE
- COGAS
- CORETAIL
- COAUTO
- COENTERTAIN
- COAFFINITY
- COFINSERV
- COOTHER
- COTRAVELSVC
- GENOTHER
- GENTRAVEL
- GENWEALTH
startDate:
$ref: '#/components/schemas/date'
cardCounts:
type: number
description: Cards enrolled in the RPIN.
format: integer
example: 1000000
programBid:
$ref: '#/components/schemas/bid'
rpinStatus:
type: string
description: Status of teh RPIN.
format: enum
example: CMF
enum:
- ACTIVE
- PENDING
- CHANGEPENDING
- DEACTIVATED
- DEACTIVATION_PENDING
- REJECTED
- APPROVED
spendRules:
type: array
items:
type: object
properties:
spendRuleName:
type: string
description: Name of Spend Rules associated with RPIN.
example: 'FRC_SPEND '
programName:
type: string
description: The Program to which RPIN is associated
example: VTR Premium
programType:
type: string
description: The Program type
format: enum
example: VTR Premium
enum:
- COBRAND
- GEN_REWARDS
- NON_REWARDS
- CASH
rpinBidName:
$ref: '#/components/schemas/bidName'
rpinCobrand:
type: string
description: The Cobrand or Affinity for the RPIN.
example: Grocery
rpinMetadata:
type: array
items:
type: object
properties:
attributeTagName:
type: string
description: UBID for the PAN's range. 8 in length.
format: enum
example: PORTFOLIO
enum:
- PORTFOLIO
- PROGRAM_SUB_CAT
- VERTICAL_SUB_CAT
- LOC
- CCP_ENABLED
- VIRTUAL
- REPORTING
- SECURED_CRD
- AUTOREG
attributeTagValue:
type: string
description: Value of the tag.
format: string
rpinProductId:
$ref: '#/components/schemas/productId'
rpinRefNumber:
type: string
description: The RPIN Reference Number.
example: 0047890ABN
programBidName:
$ref: '#/components/schemas/bidName'
accountRangeAssoc:
type: array
items:
type: object
properties:
arMax:
type: string
description: Account Range Maximum.
format: string
arMin:
type: string
description: Account Range Minimum.
format: string
autoRegAR:
type: string
description: If the account range registered is due to auto registration.
format: boolean
endDateOfAssoc:
$ref: '#/components/schemas/date'
starteDateOfAssoc:
$ref: '#/components/schemas/date'
lastCardEnrollDate:
$ref: '#/components/schemas/date'
CardAttributesDoc:
title: Card Attribute Details
type: object
properties:
pan:
$ref: '#/components/schemas/pan'
portfolio:
$ref: '#/components/schemas/CardPortfolioDetails'
linkDetails:
$ref: '#/components/schemas/LinkDetails'
updateChannel:
$ref: '#/components/schemas/updateChannel'
processingDetails:
$ref: '#/components/schemas/ProcessingDetails'
replacementDetails:
$ref: '#/components/schemas/ReplacementDetails'
lastUpdateTimestamp:
$ref: '#/components/schemas/dateTime'
ProcessingDetails:
title: Processing Details
type: object
properties:
cardProcProductId:
$ref: '#/components/schemas/productId'
spendQualifiedIndicator:
type: string
description: Spend Qualified Indicator
format: enum
example: 'N'
enum:
- 'N'
- B
- Q
InvalidPage:
type: object
properties:
result:
type: boolean
enum:
- false
errorMsg:
type: string
enum:
- INVALID_PAGE
errorCode:
type: string
enum:
- '00011'
invalidPage:
$ref: '#/components/schemas/page'
CardInfov1:
title: Card Attribute Details
type: object
properties:
sourceChannel:
$ref: '#/components/schemas/updateChannel'
lastAttrUpdateDate:
$ref: '#/components/schemas/lastAttrUpdateDate'
infoType:
type: string
description: >
Specify if caller is interested only in specific datasets. If not
specified, system will return all the data without filtering. Enum value
will display attributes as follows:
<li>PORTFOLIO - Will return RPIN enrollment details - RPIN, Account Open
Date, RPIN effective date</li>
<li>REPLACEMENT - Will return the complete replacement chain with
sequence number to indicate oldest to newest card in teh repalcement
chain</li>
<li>LINK - Will return all link relationships this card is part of.
Details of relationship will include teh link group ID, link group name,
and flag to indicate card's primary status in the relationship</li>
format: enum
example: PORTFOLIO
enum:
- PORTFOLIO
- REPLACEMENT
- LINK
LinkDetails:
title: Link group Details for queried PAN
type: array
items:
type: object
properties:
groupId:
type: string
description: Group ID for the group
example: New Fexible Pay Debit
groupType:
type: string
description: Group Type that the card is enrolled in
format: enum
example: CUSTOMER
enum:
- LOC
- USHNW
- USCROSSPROD
- CUSTOMER
pansInGrp:
type: array
description: Other PANs in the group
items:
$ref: '#/components/schemas/pan'
isPrimaryFlag:
type: string
description: Flag indicates if the card is primary in the group.
format: boolean
example: 'true'
CardAccountRangeDetails-1:
title: Issuer Level Details for the Card's Account Range
type: object
properties:
bin:
type: string
description: >-
The BIN associated to the PAN's account range. Can be 6 or 8 in
length.
example: '400003'
lbid:
$ref: '#/components/schemas/bid'
ubid:
$ref: '#/components/schemas/bid'
fundingSource:
type: string
description: UBID for the PAN's range. 8 in length.
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visa/refs/heads/main/openapi/visa-card-program-management.yml