How to use B2B Virtual Account Payment Method for buyers using VANs
B2B Virtual Account Payment Method

Rules and overrides

Buyer Setup Details

This section is intended to provide more detailed information to help you set up Buyer Templates and individual Buyers.  It includes information about field defaults, conditional logic, and field descriptions. Additionally, it specifies which fields are applicable to Request Virtual Account API versus the traditional Payment Process workflow.  

Buyers can be created two ways: from a pre-defined template or from scratch.  

 

Use Cases for a Buyer Template

  1. Common configurations across buyers that do not align with the VPA defaults (up to 20 templates per issuer).
  2. Multiple consistent buyer configurations – e.g. Travel use case and Payables use case.
  3. If future changes are expected that should apply to all buyers, you should set up a template now to simplify bulk edits later. In this case, you can easily use Update Template to apply changes to all Buyers rather than update each buyer individually.

 

Creating a Buyer when using a Template

  1. Use the Create Buyer Template API to define the custom fields set up the template that will be used for buyers.
  2. Use the Create Buyer API to create the individual buyer to be added to VPA.  Requires the Buyer Info and Processor information (if applicable).

 

Buyer Template and Individual Buyer Field Defaults

Regardless which route you take, we have defaulted many fields and thus made them Optional to simplify the setup. We have defaulted them based on best practices and common configurations across existing buyers.  If you are OK with the defaults,  you don’t need to provide those fields in the API request (unless is it marked Required).  If you would like to change the defaults,  include the fields you would like to change along with the desired values. The tables below provide the defaults. 

 

Keys points for these APIs

  • Many fields are defaulted decreasing the number of required fields.  See the default section below to see all field defaults.
  • You only need to include fields that differ from the default. 
  • If fields are not applicable to your buyer(s), do not include these fields in the API request at all (do not include empty tag). 
  • Once Buyer is setup successfully in VPA, it will also be set up in downstream platforms as well. 
  • Setting up a reconciliation file may require manual depending on the way files are set up. Talk to your Visa implementation resource for more information.  

Buyer Template Details

For Request Virtual Account users, please note the “RVA” column. This will tell you if the field is applicable to you or not. For example, Payment Configuration Tag says “required”, but RVA is set to "N" so that is only for those using the Process Payments workflow because there are no payments in the RVA use case.  

Parameter Name Required/
Optional 		RVA Size Default Validations/Notes
messageId Required Y 36
  • UniqueID to identify the request.
  • Must not contain security vulnerability characters.
clientId Required Y 25
  • ClientID associated with the bank.
  • Visa Implementation will provide this.
contactInfo Optional Y Parent tag
emailAddress Optional Y 100
  • Valid email address.
  • Used only if the third party wants to use the same email address for all email communications.
  • Used for VPC alerts and notifications.
phone1 Optional N 20 Used only if the third party wants to use the same phone for all communications.
Implementation Type Required Y 1
  • Valid Values are: 1 – VPA UI, 2 – VPA API and 3 – Visa Travel (Visa Commercial Pay)
  • If Buyers will log in to the VPA UI for an Issuer Direct relationship, select 1. If buyer is created by a Third party fintech use option 2.
Visa Business ID Required Y 11 Visa License BID for the Issuer
  • Valid Visa 11 digit Billing BID
  • Numeric
  • User should only change this from the Issuer BID if the third party will be billed
Billing Type Required Y 1 Value set at Bank level
  • Identifies who will be billed for use of the service
  • Valid Values are: I - Issuer, T - third party, M - Manual
paymentConfig Required Y Parent tag
expirationDays Optional N 3 30
  • The number of days a supplier has to receive their payment before the payment instruction expires.
  • Must be numeric.
  • Valid value: 1-999.
  • If left blank, it defaults to 30.
  • Not required but if field is provided but null/blank, then request will fail.
expirationBufferDays Optional N 2 5
  • Must be numeric.
  • Must not be more than 2 digits.
  • Valid value: 1-99.
  • Not required but if field is provided but null/blank, then request will fail.
billingCurrency Required Y 3
  • 3 digit ISO alpha currency code (e.g. USD).
  • Must be one of the supported active currencies.
allowableCurrencies Optional Y 3 (for each currency) Billing Currency
  • 3 digit ISO alpha code (e.g. USD).
  • Must be one of the supported billing currencies of the buyer.
  • Supports up to 150 currencies.
  • If Billing currency is not one of the allowable currencies, system will automatically add it.
securityCodeRequired Optional N Boolean Bank setting
  • Allow the designated supplier to access the CVV2 for all future payment instructions.
  • Valid values are true or false.
paymentAdviceOption Optional N 1 C for Consolidated
  • Valid values:
    • C - consolidated
    • S - split
  • All other values will be rejected.
stpPaymentConfig Optional N

Parent Tag

This section needs to be populated only if the bank is enabled for Straight Through Processing (STP) (Buyer-Initiated Payments).
stpPaymentEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • If bank is not enabled for STP, reject the request if the value is true.
remittanceNotificationEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • If bank is not enabled for STP remittance notification, reject the request if the value is true.
stripePaymentConfig Optional N

Parent tag

This section needs to be populated only if the bank is enabled for Stripe.
stripePaymentEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • If bank is not enabled for Stripe, reject the request if the value is true.
remittanceNotificationEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • If bank is not enabled for Stripe remittance notification, reject the request if the value is true.
boostPaymentConfig Optional N

Parent tag

This section needs to be populated only if the bank is enabled for Boost.
boostPaymentEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • If bank is not enabled for Boost, reject the request if the value is true.
paymentNotificationConfig Required Y Parent tag
defaultLanguageCode Optional N 10 en_US
  • Any valid locales like en_us for US English. Refer to the Language Code table.
  • Used for Buyer notifications.
dateFormat Required Y 10
  • Valid values are one of the supported date formats. See the Date Formats table for all available date formats.
attachRemittanceDetails Optional N Boolean Bank value
  • Valid values:
    • True
    • False
  • If bank is not enabled for Remittance details attachment, reject the request if the value is true.
supplierReminderNotificationEnabled Optional N Boolean Bank value
  • Valid values:
    • True
    • False
  • If bank is not enabled for Supplier Reminder Notification, reject the request if the value is true.
supplierReminderNotificationDays Optional N 2 7 if the supplier reminder notification is enabled
  • The number of days before the payment instruction expires when a reminder notification will be sent.
  • Valid values: 1-99
paymentSecurityConfig Optional N Parent tag
defaultSecurityFieldCode Optional N 1 1 (Postal code)
  • Valid values:
    • 1 – Postal code
    • 2 – Supplier ID
  • Buyers can choose to use either the Supplier ID or the supplier’s ZIP/postal code as the answer to the default security question.
defaultSecurityQuestion Optional N 256 “Credential Text”
  • Security vulnerability characters are not allowed.
  • This is the phrase the supplier will be prompted with when retrieving full account information
customizeSecurityQuestionsEnabled Optional N Boolean False
  • Valid values:
    • True
    • False
  • Buyers can create a custom security question. The same question must be used for all suppliers.
customSecurityQuestions Conditional N 100
  • At least one question needs to be sent if custom security question is enabled.
  • Security vulnerability characters should not be allowed for the questions.
  • Max of three questions. 100 characters each.
authorizationControlConfig Optional Y

Parent tag

This section needs to be populated only if the bank is enabled for auth controls.
authControlEnabled Conditional Y Boolean True for VIP pseudo and TSYS VAN buyers. True if mandate auth controls enabled. Otherwise, False.
  • Valid values:
    • True
    • False
  • Should be set to True for VPP and VIP token buyers.
  • For memo buyers, this can be True or False
  • If the value is not True, and the bank is enabled for mandate auth controls, reject the request.
  • Bank payment control indicator should be enabled.
issuerHoldingBID Conditional 8 The IssuerHoldingBID set for the bank
  • Required if auth controls are enabled & token type is not VPP.
  • Valid Visa 8-digit BID.
  • Must be numeric.
  • Should be populated only if the auth control is enabled for the template or the request will be rejected.
alertsEnabled Conditional Y Boolean
  • Required if auth control is enabled for the buyer (applicable only for VPC enabled template).
  • Enables VPC decline email notifications.
  • Valid values:
    • True
    • False
  • The system will reject the request if this is set to true and the auth controls is not enabled for the template.
buyerFeatureConfig Optional Y Parent tag
cardMaskingDigitsOnline Optional Y 2 12
  • RESERVED FOR FUTURE USE. Do not use.
  • Must be numeric.
  • Valid values: 0-12.
  • Controls masking of account number on the user interface.
  • To mask card numbers in API response, contact your Visa implementation resource to configure.
cardMaskingDigits Optional Y 2 12
  • Must be numeric.
  • Valid values: 0-12
  • Controls all recon files and response files.
  • To mask card numbers in API response, contact your Visa implementation resource.
onlinePaymentInstructionEnabled Optional N Boolean False
  • Denotes if online payment instruction (Pay Now) functionality is enabled for the buyer.
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
onlinePaymentRequisitionEnabled Optional N Boolean False
  • Denotes if online payment requisition functionality is enabled for the buyer.
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
fullAccountViewEnabled Optional N Boolean Bank value
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
pseudoAccountsEnabled Optional Y Boolean N
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
approvalWorkflowConfig Optional N Parent tag (Collection of approval workflow functions)
workflowFunctionsEnabled Optional N Boolean False
  • Valid values
    • True
    • False.
  • Bank needs to be enabled for this before it is enabled for the template.
workflowFunctionCodes Conditional N 2
  • Required for adding a workflow function (Workflow Function Enabled is set to True).
  • Valid Values:
    • AUCL – Card Limit Update
    • LCRC – Lodge/New Card
    • PYIN – Payment Instruction
    • PYRN – Payment Requisition
webServicesConfig Parent tag
webServicesEnabled Optional Y Boolean False
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
vbdsClientId Optional Y 50 Every third party will have this ID generated for subscribing to auth/settlement data from VBDS system.
clientId Optional Reserved for Future Use. Reserved for Future Use.
apiCodes Conditional Reserved for Future Use. Reserved for Future Use.
suppressSupplierNotification Optional N Boolean N
  • Valid values:
    • Y
    • N
  • Applicable only when the suppress notification is enabled for the bank.
  • Will suppress any supplier notifications such as Payment Remittance Advice, Security questions/answers, reminders, etc. Used when third party provides this information directly to the supplier.
paymentFileCommConfig Optional N

Parent tag

Applicable to buyers using the payment process flow, and whose payments are submitted via system-to-system interface.
inboundFileId Conditional N 40
  • Required if EDI 820 payment file is sent from the buyer.
  • Comm file ID associated with the EDI 820 inbound payment file.
  • Should be an existing bank level comm file already setup in COMMs as an inbound to receive EDI 820 format file.
edi997FileId Optional N 40
  • Only required if EDI 997 ack file needs to be sent to the buyer.
  • Comm file ID associated with the EDI 997 outbound ack file.
  • Should be an existing bank level comm file already setup in COMMs as an outbound to send a EDI 997 format file.
edi824FileId Optional N 40
  • Only required if EDI 824 ack file needs to be sent to the buyer.
  • Comm file ID associated with the EDI 824 outbound response file.
  • Should be an existing bank level comm file already setup in COMMs as an outbound to send a EDI 824 format file.
ResponseFileConfig Optional N

Parent tag

Applicable to buyers using the process payment flow and who submit files through system-to-system connection.
commFileId Conditional N 40
  • Comm File ID associated with the Response file outbound delivery.
  • Visa Implementation team will provide this ID.
ReconciliationFileConfig Optional N

Parent tag

This reconciliation file is used for the Payment Processing use case.
onlinePaymentReconciliationEnabled Optional N Boolean False
  • Denotes if online payment Reconciliation functionality is enabled for the buyers.
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
adhocReconciliationReportEnabled Optional N Boolean False
  • Valid values
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
  • Enables company admins to trigger the Adhoc Reconciliation file from the VPA UI.
commFileId Optional N 40
  • Comm File ID associated with the recon file outbound delivery.
  • Visa Implementation team will provide this ID.
templateName Conditional N 100 Most recent standard recon template
  • For Process Payment use case.
  • Name of the custom reconciliation file template.
  • Required if CommFileID is provided or adhoc recon report is enabled.
rvaReconciliationFileConfig Optional Y

Parent tag

This reconciliation file is applicable to those using the Request Virtual Account API.
commFileId Optional Y 40
  • Comm File ID associated with the RVA Recon file outbound delivery.
  • This will be provided by the Visa implementation team.
templateId Conditional Y 2 Most recent RVA Recon template version.
  • Required if RVA recon is enabled.
  • Denotes the id of the recon template to be used for generating the RVA reconciliation file.
  • Today there is only one version so you can leave this blank; system will default to the most recent version.
  • Valid value: 01 (standard version).
  • Should be valid RVA template ID.
proxyConfig Optional Y Parent tag
holdDays Optional Y 3 90 days
  • Numeric.
  • Maximum 3 digits.
  • SUAs are available for use after the hold days have completed.
  • For Payments, Hold days start when the payment is submitted.
  • For RVA, Hold days start when the payment requisition end period is reached.
autoRefreshEnabled Conditional Y Boolean True if the buyer is enabled for pseudo account or VPP, otherwise, it is False.
  • Valid values:
    • True
    • False
  • Required for Visa Pseudo Accounts and TSYS VPP VANs.
bucketedProxyEnabled Optional Y Boolean False
  • Valid values:
    • True
    • False
  • Can be set to True only if the bank is enabled for bucketed Proxy.
  • SUA Buckets feature is where VPA dynamically selects an SUA from a “bucket” of fixed accounts with the lowest credit limit that can be used to make the payment.
processorConfig Optional Y Parent tag
closeAccount Conditional Y Boolean True if processor integration is enabled for the bank or buyer is enabled for VIP/VPP tokens. Otherwise, false.
  • Ability to close the account at the processor, or close an account within the token vault.
  • Must be true for VIP pseudo accounts and TSYS VPP VAN.
  • If processor integration is off, the system should reject the request if the value is True.
  • Valid values:
    • True
    • False
UpdateVANconfig Optional Y

Parent tag

Applicable to buyers using TSYS VPP VANs.
vanEnabled Conditional Y Boolean
  • Valid values:
    • True
    • False
  • Bank needs to be enabled for this before it is enabled for the template.
fcsBankId Conditional Y 4 The Bank FCS ID if there is only one setup at the bank level.
  • Alphanumeric value.
  • Required if template is enabled for TSYS VPP.
  • Length is 4 digits.
  • Should be one of the values set up for the bank.

Approval Workflow Codes

Function Name Short Code
Payment Instruction PYIN
Payment Requisition PYRN
Lodge/Request a Card LCRC
Adhoc Update Credit Limit AUCL

Language Codes

Name Language Code
International French fr_FR
US English en_US
international English en_GB
Latin American Spanish es_ES
Brazilian Portuguese pt_BR
German de_DE
Italian it_IT

Date Formats

Date Format
MMDDYYYY
DDMMYYYY
YYYYMMDD
DD/MM/YYYY
DD/MM/YY
YYYY/MM/DD
YY/MM/DD
MM/DD/YYYY
MM/DD/YY
DD/MMM/YYYY
DD/MMM/YY
YYYY/MMM/DD
YY/MMM/DD
MMM/DD/YYYY
MMM/DD/YY
DD-MM-YYYY
DD-MM-YY
YYYY-MM-DD
YY-MM-DD
MM-DD-YYYY
MM-DD-YY
DD-MMM-YYYY
DD-MMM-YY
YYYY-MMM-DD
YY-MMM-DD
MMM-DD-YYY
MMM-DD-YY

Rules and Overrides for Request Virtual Account and Manage Payment Controls

SL No Rule Code Rule Description Override Override details
1 ATM Block ATM cash withdrawals. N n/a
2 ATML Block ATM cash withdrawals above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
3 PUR Block Purchases above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
4 ECOM Block all Internet-based transactions. N n/a
5 EAM Block all Internet based transactions above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
6 CNP Block all transactions made over the Internet, phone or mail order. N n/a
7 NOC Block all other cash access. This includes non-ATM transactions such as cash advances and purchase with cashback. N n/a
8 ADT Block purchases at adult-themed merchants. N n/a
9 XBR Block all cross border transactions N n/a
10 XBRA Block cross border transactions above a certain amount limit (enter whole dollar). Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
11 DOM Purchases conducted outside of the selected state will be blocked Y

cardAcceptorStateOrProvinceCode: Numeric code from lookup
12 BUS Check the box to block transactions conducted outside of business hours. Define the business hours, when transactions are ALLOWED, by selecting your local time zone and the days/times below. Transactions outside these hours will be blocked. Y

timezone: Supports global time zones

weekDayEffective: SUN/MON/TUE/WED/THU/FRI/SAT

Follow above - enter 3 letters with all caps

timeEffectiveStart: HH:mm

timeEffectiveEnd: HH:mm
13 FUEL Block purchases conducted at fuel/driver merchants (including gas stations,car washes, parking lots and tolls). N n/a
14 HOT All purchases made at hotel merchants will be declined. N n/a
15 AUTO All purchases made at auto-rental merchants will be declined. N n/a
16 AIR All purchases made at airline merchants will be declined. N n/a
17 REST All purchases made at restaurants will be declined. N n/a
18 JEWL All purchases made at jewelery store locations will be declined N n/a
19 ELEC All purchases conducted at electronics themed-merchants will be declined. N n/a
20 ALC All purchases conducted at alcohol and tobacco merchants will be declined. N n/a
21 GTM All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls). N n/a
22 OSS All purchases conducted at office supply merchants will be declined. N n/a
23 GROC All purchases conducted at grocery store and pharmacy merchants will be declined. N n/a
24 ENT All purchases conducted at entertainment and sports merchants will be declined (includes movie theaters,music stores and sporting good stores). N n/a
25 UTIL All purchases conducted at utilities will be declined (includes cable, phone and electric companies). N n/a
26 CLOTH All purchases conducted at clothing and general retail merchants will be declined(includes department stores, shoe stores and book stores). N n/a
27 MED All purchases made at medical merchants will be declined. N n/a
28 VPAS Exact amount match rule. Allows for only oe approved authorization and must match the amount in request, to the $.01. Note: Note: You can have multiple VPAS rule for an account. In this case, this rule will be repeated Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
29 CAID This rule allows transactions to only merchants with a specified card acceptor ID (CAID). Y

CAIDValue

Note: At least one (1) CAID value is required. A maximum of 200 values, including Acquiring IDs, are allowed.
Card Acceptor ID has these attributes:

15 alphanumeric characters
Cannot be left blank
Duplicate CAID values within the same Acquiring ID is not allowed.
Duplicate CAID values across different Acquiring IDs are allowed.
Special characters are not allowed
CAID and CAIDB cannot be used together due to conflicting rule nature.

acquiringInstitutionId

Acquiring Institution ID has these attributes:

  • Optional
  • 11 numeric characters
  • Cannot be left blank
  • Cannot be duplicated
30 TOLRNC Tolerance Rule: Each transaction must be within the minimum $ amount and the maximum $ amount. There can be multiple transactions but each must be within the defined range. Y

amountCurrencyCode: ISO Currency Code

minValue: Amount

maxValue: Amount
31 SPV Spend Velocity Rule Y

Note: Override codes marked with an asterisk * are required.

SpendLimitAmount*: Amount ; The maximum amount that can be collected from the card.

Note: This is based on the range criteria selected. I.e. if monthly is selected, it will reset every month to the SpendLimitAmount.
Accruals for spendLimitAmount are tracked and can be retrieved via the Get Payment Controls or Get Requisition Details APIs. The response includes:

  • consumedAmount: total amount spent to date
  • balanceAuthAmount: remaining amount available to spend

maxAuth: Number ; Max number of successful transactions/authorizations the user is allowed to make. This number defaults to zero.

Note: A zero in this field implies no limit on the number of transactions the user can make.
Accruals for maxAuth are tracked and can be retrieved via the Get Payment Controls or Get Requisition Details. The response includes:

  • consumedAuthCount: total authorizations processed to date
  • balanceAuthCount: remaining authorizations available

amountCurrencyCode*: ISO Currency Code ; the currency code for SpendLimitAmount

rangeType*: Number; There are three different range types. Some selections have additional required fields.

rangeType: 1 is Recurring.
For this rangeType, the SPV rule never expires. The SPV rule enabled for a card is reset with its original values on the recurring day for every month clearing the transaction fields (authorization amount, authorization count, and notifications sent and rangeType:1)
If you select this rangeType, you must also specify the recurringDay field. Select a number between 1-28.

rangeType: 2 is Monthly.
For this rangeType, the SPV rule never expires. The SPV rule enabled for a card is reset with its original values at the start of every month clearing the transaction fields (authorization amount, authorization count, and notifications sent and rangeType:2)
If you select this rangeType, you do not need to enter any additional fields.

rangeType: 3 is DateRange.
For this rangeType, the SPV rule is only valid for the specified date range.
If you select this rangeType, you must also specify:

  • startDate (in UTC)
  • endDate (in UTC)
Formats are YYYY-MM-DD or MM/DD/YYYY

rangeType: 4 is Weekly.
For this specific rangeType, the SPV rule remains valid until the end date of the requisition. The SPV rule, when activated for a card, is reset to its initial values each week on a recurring day, which results in the clearing of transaction details such as the authorization amount, the count of authorizations, and the notifications count.
If you select this rangeType, you must also specify:
"dayOfTheWeek" as one of the following values :SUN,MON,TUE,WED,THU,FRI,SAT
Users are advised to input the timezone for the reset to occur at the appropriate local time. In the absence of a user-specified timezone, the system will default to a daily reset based on Greenwich Mean Time (GMT).

rangeType: 5 is Daily.
For this specific rangeType, the SPV rule remains valid until the end date of the requisition. The SPV rule, when activated for a card, is reset to its initial values each day, which results in the clearing of transaction details such as the authorization amount, the count of authorizations, and the notifications count.
Users are advised to input the timezone for the reset to occur at the appropriate local time. In the absence of a user-specified timezone, the system will default to a daily reset based on Greenwich Mean Time (GMT).

updateFlag*: Potential values include:

  • NOCHANGE/UPDATE: To update the existing SPV by keeping transaction details as is (authorization amount, authorization count, and notifications count). This is the default value.
  • REPLACE: update existing SPV rule with the new rule and reset the accrual details to 0 (authorization amount, authorization count, and notifications count).

Note: To update an existing SPV rule, all fields specified in the existing SPV rule must be provided in the request. If not specified, the field(s) will be reset to the default value(s).

recurringDay: Applicable only when the range type is 1. Specify a number btween 1 and 28.

startDate: Applicable only when the range type is 3. You need to specify the start date of when the system should start applying the SPV rule

endDate: Applicable only when the range type is 3. You need to specify the end date of when the system should stop applying the SPV rule

dayOfTheWeek: Required only when the range type 4.The valid values are SUN,MON,TUE,WED,THU,FRI,SAT

spendLimitAmountTolerance: This option will allow users to specify a Spend Limit Amount Tolerance percentage of their total Spend Limit Amount so that additional spending beyond the preset limit is allowed.For example, if the spending limit is set at $1,000 and the Tolerance is set as 10 then the cardholder can spend up to $1,100(10% tolerance).

timeZone: Specifies the time zone for the range type provided in the request. This field is optional but its essential to define reset time zone for the recurring range type - Recurring day, Monthly, Weekly and Daily. If not defined it will be reset in GMT timezone. No impact to the “Date Range” type.
32 QSR MCC with fastfood merchants N n/a
33 BUSS MCCs with Business Services N n/a
34 CNTR MCCs with General Contractor Services N n/a
35 GOV MCCs with Government Services N n/a
36 MISC MCCs with Miscellaneous Retailer N n/a
37 PROF MCCs with Professional Services and Membership Organizations) N n/a
38 RETL MCCs with Retail Outlet Services N n/a
40 MCCB MCC Level Blocking; up to 15 ranges of granular merchant category level blocking Y

minMCC: Allowed MCC between 0000-9999

maxMCC: Allowed MCC value should be equal to or greater than minMCC
41 MCCX MCC Level Allow; Allow up to 15 ranges of granular merchant category code level Y

minMCC: Allowed MCC between 0000-9999

maxMCC: Allowed MCC value should be equal to or greater than minMCC
42 CAIDB This rule blocks transactions to only merchants with a specified card acceptor ID (CAID). Y

CAIDValue

Note: At least one (1) CAID value is required. A maximum of 200 values, including Acquiring IDs, are allowed.
Card Acceptor ID has these attributes:

15 alphanumeric characters
Cannot be left blank
Duplicate CAID values within the same Acquiring ID is not allowed.
Duplicate CAID values across different Acquiring IDs are allowed.
Special characters are not allowed
CAID and CAIDB cannot be used together due to conflicting rule nature.

acquiringInstitutionId

Acquiring Institution ID has these attributes:

  • Optional
  • 11 numeric characters
  • Cannot be left blank
  • Cannot be duplicated
43 DOMB State-level transaction restrictions (e.g., block card-present transactions from Nevada, Arizona, and New Mexico) Y

cardAcceptorStateOrProvinceCode: ISO USA State Code
44 XBRB XBRB location restrictions - block in countries Y

jurisdictionMerchantCountry: ISO Country Code
45 XBRX XBRX location restrictions - allow in countries Y

jurisdictionMerchantCountry: ISO Country Code
46 TCUX Transaction Currency restriction Y

TCUXValue: ISO Currency Code
47 ACCB This rule allows clients to block all authorization transactions on an account. N n/a
48 SPP The Spend Policy rule allows clients to define up to ten, independent groupings of spend limits (policies) on a virtual card, each with its own limit amount and optional transaction count. These limits can be applied either over a fixed date range or on a recurring cadence and are scoped to specific merchant categories, defined by Merchant Category Code (MCC) ranges. Spend within each grouping is accumulated and enforced independently. Y

timeZone: Optional value, default value for timezone is GMT if not provided

spendLimitAmount*: Amount; The maximum amount that can be collected from the card for the specific policy.

Note: This is based on the range criteria selected. I.e. if monthly is selected, it will reset every month to the SpendLimitAmount.
Accruals for spendLimitAmount are tracked and can be retrieved via the Get Payment Controls or Get Requisition Details APIs. The response includes:

  • consumedAmount: total amount spent to date
  • balanceAuthAmount: remaining amount available to spend

amountCurrencyCode

maxAuth: Number; Max number of successful transactions/authorizations the user is allowed to make. This number defaults to zero.

Note: A zero in this field implies no limit on the number of transactions the user can make.
Accruals for maxAuth are tracked and can be retrieved via the Get Payment Controls or Get Requisition Details. The response includes:

  • consumedAuthCount: total authorizations processed to date
  • balanceAuthCount: remaining authorizations available

recurringType*

accumulatedSpendResetIndicator: Valid Values are Yes or No.

merchantCategoryCodeRange: Example: "1000-1300,2000-2300,4000-4500"

Rules and Overrides for Virtual Card Requisition

SL No Rule Code Rule Description Override Override details
1 ATM Block ATM cash withdrawals. N n/a
2 ATML Block ATM cash withdrawals above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
3 PUR Block Purchases above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
4 ECOM Block all Internet-based transactions. N n/a
5 EAM Block all Internet based transactions above a threshold. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
6 CNP Block all transactions made over the Internet, phone or mail order. N n/a
7 NOC Block all other cash access. This includes non-ATM transactions such as cash advances and purchase with cashback. N n/a
8 ADT Block purchases at adult-themed merchants. N n/a
9 XBR All purchases outside of the United States will be blocked. N n/a
10 XBRA Purchases with amounts greater than the defined amount will be declined when conducted outside of the United States (enter whole dollar amount). Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
11 DOM Purchases conducted outside of the selected state will be blocked. Y

cardAcceptorStateorProvinceCode: Numeric code from lookup
12 BUS Check the box to block transactions conducted outside of business hours. Define the business hours, when transactions are ALLOWED, by selecting your local time zone and the days/times below. Transactions outside these hours will be blocked.

timezone: Eastern Time Zone/Central Standard Time/Mountain Standard Time/Pacific Standard Time

weekDayEffective: SUN/MON/TUE/WED/THU/FRI/SAT

timeEffectiveStart: HH:mm:ss

timeEffectiveEnd: HH:mm:ss
13 FUEL Block purchases conducted at fuel/driver merchants (including gas stations,car washes, parking lots and tolls). N n/a
15 HOT All purchases made at hotel merchantswill be declined. N n/a
16 AUTO All purchases made at auto-rental merchants will be declined. N n/a
17 AIR All purchases made at airline merchants will be declined. N n/a
18 REST All purchases made at restaurants will be declined. N n/a
19 JEWL All purchases made at jewelery store locations will be declined. N n/a
20 ELEC All purchases conducted at electronics themed-merchants will be declined. N n/a
21 ALC All purchases conducted at alcohol and tobacco merchants will be declined. N n/a
22 GTM All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls). N n/a
23 OSS All purchases conducted at office supply merchants will be declined. N n/a
24 GROC All purchases conducted at grocery store and pharmacy merchants will be declined. N n/a
25 ENT All purchases conducted at entertainment and sports merchants will be declined (includes movie theaters,music stores and sporting good stores). N n/a
26 UTIL All purchases conducted at utilities will be declined (includes cable, phone and electric companies). N n/a
27 CLOTH All purchases conducted at clothing and general retail merchants will be declined(includes department stores, shoe stores and book stores). N n/a
28 MED All purchases made at medical merchants will be declined. N n/a
29 VPAS Exact amount match rule. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount

Rules and Overrides for Request Virtual Account for TSYS VPP

The following table lists rules and overrides for buyers enabled for VANs. See B2B Virtual Account Payment Method for Buyers Using VANs to view a full description of the VPP program applicable for buyers using VANs. 

Note: The merchant category rules for buyers using VANs are opt-in rules.  If one is selected, only the merchants that meet that criteria will be able to take a payment.

SL No Rule Code Rule Description Override Override Details
1 SPV Spend Velocity Rule. The startDate and endDate must be in Eastern Standard Time (EST). Y

amountCurrencyCode: ISO Currency Code

spendLimitAmount: Amount

maxAuth: Number

startDate: MM/DD/YYYY or YYYY-MM-DD

endDate: MM/DD/YYYY or YYYY-MM-DD
2 VPAS Exact Amount Match Rule. Authorization amount must match the request, to the $.01. This rule only allows a single approved authorization. Y

amountCurrencyCode: ISO Currency Code

amountValue: Amount
3 TOLRNC Tolerance Rule: Authorization amount must be between the minimum $ and the maximum $ amount defined. This rule only allows a single approved authorization. Y

amountCurrencyCode: ISO Currency Code

minValue: Amount

maxValue: Amount
4 DOM Purchases conducted outside of the selected state will be enabled. State code is valid for USA (840) country code. Y

cardAcceptorStateOrProvinceCode: ISO USA State Code

CountryCode: ISO Country Code
5 BUS Check the box to block transactions conducted outside of business hours. Define the business hours, when transactions are ALLOWED, by selecting your local time zone and the days/times below. Transactions outside these hours will be blocked. Note: weekDayEffective is case sensitive. Only supports US-based time zones (PST, MST, CST and EST). Y

timezone: Eastern Time Zone / Central Standard Time / Mountain Standard Time / Pacific Standard Time

weekDayEffective: Sunday / Monday / Tuesday / Wednesday / Thursday / Friday / Saturday

timeEffectiveStart: HH:mm:ss

timeEffectiveEnd: HH:mm:ss
6 ATM Enable ATM cash withdrawals. N n/a
7 ECOM Enable all Internet-based transactions. N n/a
8 CNP Enable Card Not Present. N n/a
9 FUEL Allow purchases conducted at fuel/driver merchants. Allowed MCC Range: 5541 - 5542, 7542 - 7542. N n/a
10 AUTO Allow purchases made at auto-rental merchants. Allowed MCC Range: 3351-3441, 7512-7512. N n/a
11 AIR Allow purchases made at airline merchants. Allowed MCC Range: 3000-3300, 4511-4511. N n/a
12 REST Allow purchases made at restaurants. Allowed MCC Range: 5811-5812, 5814-5815, 5462-5463. N n/a
13 ELEC Allow purchases conducted at electronics themed-merchants. Allowed MCC Range: 4812-4814, 4816-4817, 5044-5045, 5731-5732, 5734-5734, 7372-7379. N n/a
14 ALC Allow purchases at alcohol and tobacco merchants. Allowed MCC Range: 5813-5813, 5921-5922. N n/a
15 GTM Allow purchases conducted at ground transportation merchants (includes taxis, trains, and bridge tolls). Allowed MCC Range: 4011-4112, 4121-4131, 4784-4784. N n/a
16 OSS Allow purchases conducted at office supply merchants. Allowed MCC Range: 5111-5112, 5943-5943, 7332-7361, 7392-7399 and 9402-9403. N n/a
17 GROC Allow purchases conducted at grocery store and pharmacy merchants. Allowed MCC Range: 5411-5461, 5464-5499. N n/a
18 ENT Allow purchases conducted at entertainment and sports merchants (includes movie theaters, music stores and sporting good stores). Allowed MCC Range: 7832-7994, 7996-7999. N n/a
19 UTIL Allow purchases at utilities (includes cable, phone and electric companies). Allowed MCC Range: 4814-4815, 4899-4900. N n/a
20 MED Allow purchases made at medical merchants. Allowed MCC Range: 4119-4119, 5975-5976, 8011-8099. N n/a
21 PHAR Allow purchases made at Pharmacies. Allowed MCC Range: 5122-5123, 5912-5913. N n/a
22 GENR Allowed purchases made at General Retail. Allowed MCC Range: 4225-4225, 5192-5410, 5611-5722, 5923-5942, 5944-5974 and 5977-5999. N n/a
23 LODG Allow purchases made at Hotels, Motels, Resorts, Specific lodging establishments. Allowed MCC Range: 3501-3838, 7011-7011. N n/a
24 OTHR Other MCC codes Y

startRange: Allowed MCC between 0000-9999

endRange: Allowed MCC value should be equal to or greater than startRange

Get Payment Controls API Response Details

Details for Processor PANs and Visa Pseudo Accounts

The following rules have additional parameters in the Get Payment Controls API response. This table only includes rules whose overrides will differ from the request. If a rule is not listed below, refer to the Rules and Overrides section for Request Virtual Account and Manage Payment Controls above for the rule formatting.

Rule Code Rule Description Override details
SPV Spend Velocity Rule

SpendLimitAmount: Amount; The maximum amount that can be collected from the card.

Note: This is based on the range criteria selected. For example,. if monthly is selected, it will reset every month to the SpendLimitAmount

maxAuth: Number ; Max number of successful transactions/authorizations the user is allowed to make. This number defaults to zero.

Note: A zero in this field implies no limit on the number of transactions the user can make.

amountCurrencyCode: ISO Currency Code ; the currency code for SpendLimitAmount

rangeType: Number; There are three different range types. Some selections have additional required fields.

  • rangeType: 1 is Recurring.
    For this rangeType, the SPV rule never expires. The SPV rule enabled for a card is reset with its original values on the recurring day for every month clearing the transaction fields (authorization amount, authorization count, and notifications sent and rangeType:1)
    If you select this rangeType, you must also specify the recurringDay field. Select a number between 1-28.
  • rangeType: 2 is Monthly.
    For this rangeType, the SPV rule never expires. The SPV rule enabled for a card is reset with its original values at the start of every month clearing the transaction fields (authorization amount, authorization count, and notifications sent and rangeType:2)
    If you select this rangeType, you do not need to enter any additional fields.
  • rangeType: 3 is DateRange.
    For this rangeType, the SPV rule is only valid for the specified date range.
    If you select this rangeType, you must also specify:
    • lens startDate (in UTC)
    • lensendDate (in UTC)

Formats are YYYY-MM-DD or MM/DD/YYYY

recurringDay: Applicable only when the range type is 1. You need to specify the day corresponding to the range type

startDate: Applicable only when the range type is 3. You need to specify the start date of when the system should start applying the SPV rule

endDate: Applicable only when the range type is 3. You need to specify the end date of when the system should stop applying the SPV rule

consumedAmount: Denotes the total transaction amount which has already been authorized on the account

consumedAuthCount: Denotes the total number of authorization which has already been authorized on the account

balanceAuthAmount: Denotes the balance transaction amount which can be authorized on this account. This is calculated as SpendLimitAmount - consumedAmount.

balanceAuthCount: Denotes the balance transaction count which can be authorized on this account. This is calculated as maxAuth - consumedAuthCount. If maxAuth is 0, then this value will also be 0 to denote unlimited authorizations can be performed on the account.

recurringDay: Returned only when the range type is 1.

dayOfTheWeek: Returned only when the range type 4.The valid values are SUN,MON,TUE,WED,THU,FRI,SAT

spendLimitAmountTolerance: Denotes a Spend Limit Amount Tolerance percentage of their total Spend Limit Amount so that additional spending beyond the preset limit is allowed.For example, if the spending limit is set at $1,000 and the Tolerance is set as 10 then the cardholder can spend up to $1,100(10% tolerance).This field is returned only when provided in the input

timeZone: Denotes the time zone for the range type provided in the request. This field is optional but its essential to define reset time zone for the recurring range type - Recurring day, Monthly, Weekly and Daily. If not defined it will be reset in GMT timezone. No impact to the “Date Range” type.This field is returned only when provided in input

Details for TSYS VANs

The following rules have additional parameters in the Get Payment Controls API response. This table only includes rules whose overrides will differ from the request. If a rule is not listed below, refer to the Rules and Overrides section for TSYS VANs above for the rule formatting.

Rule Code Rule Description Override details
SPV Spend Velocity Rule

SpendLimitAmountGet: Amount ; The maximum amount that can be collected from the card.

Note: This is based on the range criteria selected. For example, if monthly is selected, it will reset every month to the SpendLimitAmount

maxAuth: Number ; Max number of successful transactions/authorizations the user is allowed to make. This number defaults to zero.

Note: A zero in this field implies no limit on the number of transactions the user can make.

amountCurrencyCode: ISO Currency Code ; the currency code for SpendLimitAmount

startDate: Applicable only when the range type is 3. You need to specify the end date of when the system should start applying the SPV rule

endDate: Applicable only when the range type is 3. You need to specify the end date of when the system should stop applying the SPV rule

consumedAmount: Denotes the total transaction amount which has already been authorized on the account

consumedAuthCount: Denotes the total number of authorization which has already been authorized on the account

balanceAuthAmount: Denotes the balance transaction amount which can be authorized on this account. This is calculated as SpendLimitAmount - consumedAmount.

balanceAuthCount: Denotes the balance transaction count which can be authorized on this account. This is calculated as maxAuth - consumedAuthCount. If maxAuth is 0, then this value will also be 0 to denote unlimited authorizations can be performed on the account.
VPAS Exact Match Rule.

amountCurrencyCode: ISO Currency Code

amountValue: Amount

usedFlag: True/False