B2B Virtual Account Payment Method Codes

Refer back to the API Reference Page, for API specifications on the B2B Virtual Account Method APIs. 

Navigate to the documentation page for more exhaustive information about the B2B Virtual Accounts Payment Method APIs. 

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.  

Create Buyer Details

If you are associating a buyer to a template, you only need to populate the Contact Info section (name, address, etc.) and the Processor Configuration section, if applicable. In the Processor Configuration section, when using processor PANs, these processors can be enabled for processor integration: FIS, FDR, TS1, TS2, and TSUK.

Processor integration is not required when using Visa Pseudo Accounts or TSYS VANs. If it is enabled, the system goes to the processor to retrieve the latest values such as expiration date, current balance, and available balance for the funding account(s).

Parameter Name in the API Required/Optional RVA Size Default (If empty tag) Validations/Notes
messageId Required Y 36  
  • Unique ID to identify the request.
  • Must not contain security vulnerability characters.
clientId Required Y 25   Client ID associated with the bank.
contactInfo Required Y     Parent tag
companyId Required Y 10  
  • Company ID at the issuer's processor (if applicable).
  • Must be numeric.
  • Must be unique to the company.
buyerId Optional Y 25 Defaults to Company ID.
  • This can be the same as the processor's Company ID, or it can be customized for the buyer.
  • This is displayed/referenced within the VPA UI.
  • Alphanumeric.
  • No special characters except _ (underscore) and - (hyphen).
buyerName Required Y 100  
  • Name of the buyer.
  • Alphanumeric.
  • Must be unique within a bank.
  • This name will appear in the VPA UI. 
  • If the value is only spaces or left blank, the request will be rejected.
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
contactName Required Y 100  
  • Name of the primary contact person for the buyer.
  • Alphanumeric.
  • If the value is only spaces or left blank, the request will be rejected.
phone1 Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Buyer contact phone number 1.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
phone1Ext Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Extension of buyer contact phone number 1.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
phone2 Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Buyer contact phone number 2.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
phone2Ext Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Extension of buyer contact phone number 2.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
phone3 Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Buyer contact phone number 3.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
phone3Ext Optional Y 20

Max 17 for UK region (CD: 3).

Max 10 for all other regions.

  • Extension of buyer contact phone number 3.
  • Alphanumeric with spaces.
  • No special characters except _ (underscore), - (hyphen, and , (comma).
emailAddress Required Y 100  
  • Buyer's contact email address.
  • Must be a valid email address.
addressLine1 Required 40  
  • Line 1 of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
addressLine2 Optional 40  
  • Line 2 of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
addressLine3 Optional 80  
  • Line 3 of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
City Required Y 20  
  • City name of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
State Optional Y 27  
  • State of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
countryCode Required Y 3  
  • ISO 3-digit alpha country code of the buyer's contact address. For example: USA.
zipCode Required Y 10  
  • Postal code of the buyer's contact address.
  • Alphanumeric with spaces and all special characters.
  • Security vulnerability characters are not allowed.
templateId Optional for Buyer API Y 30  
  • Unique identifier for a template associated with the Client ID (bank). 
  • Template ID of the template sent in the response when a template was first created.
  • Must be unique within a bank.
  • Alphanumeric.
  • No special characters except _ (underscore) and - (hyphen).
paymentConfig Optional N     Parent tag
expirationDays Optional N 2 30
  • Payment expiration days are used to calculate the payment expiration date (payment process date + payment expiration days). The payment expiration date is the last day by which the supplier should collect the payment.
  • The default value is 30 days. The default is used if the buyer does not provide in the payment or it was not configured for the supplier. 
  • Must be less than 3 digits and must be a whole number.
expirationBufferDays Optional N 2 5
  • Number of days after the payment expiration date by which the supplier must collect the payment (settlement of the card transaction should be completed).
  • Numeric.
  • Must be 2 digits or less.
  • Valid value: 1-99.
billingCurrency Optional Y/N 3  
  • The 3-digit ISO alpha currency code associated with the billing currency of card accounts belonging to the buyer. For example, USD for US Dollar.
  • Must be one of the supported active currencies.
allowableCurrencies Optional Y 3 (for each currency) Billing currency
  • Collection of string values.
  • List of currencies allowed for the buyer. Buyer can process payments in any of these currencies.
  • 3-digit ISO alpha currency code.
  • Must be supported currencies.
  • Supports a collection of up to 40 currencies.
  • If the billing currency is not in this list, the request will be rejected. 
securityCodeRequired Optional N Boolean Bank setting
  • Denotes if the security code is needed for the supplier to collect the payment.
  • Valid values: 
    • True
    • False
  • Can only be configured if the bank is enabled for it.
  • If the request is True, but the bank CVV2 is set to N, the request will be rejected. 
paymentAdviceOption Optional N 1 Default to C for Consolidated.
  • Used by the system to decide if all payments to the same supplier should be consolidated or sent separately in the payment advice notification.
  • Valid values:
    • C - Consolidated
    • S - Split
stpPaymentsConfig Optional N    

Parent tag

This section should only be populated if the bank is enabled for Straight Through Processing (STP).

stpPaymentEnabled Optional N Boolean False
  • Denotes if STP payments are enabled for the buyer.
  • Valid values
    • True
    • False
  • Should only populate this field if the bank is enabled for STP.
remittanceNotificationEnabled Optional N Boolean False
  • Denotes if the STP Payment Remittance notification is enabled for a buyer.
  • Valid values: 
    • True
    • False
  • Should only populate this field if the bank is enabled for the STP Payment Remittance notification.
accountHolderFirstName Optional N 100 Buyer contact name captured in the buyer section.
  • Account holder's first name used for processing the STP payment.
  • Should only populate this field if the bank and buyer are enabled for STP.
  • If this field is left blank, it will default to the buyer contact name.
accountHolderLastName Optional N 100 Buyer contact name captured in the buyer section.
  • Account holder's last name used for processing the STP payment.
  • Should only populate this field if the bank and buyer are enabled for STP.
  • If this field is left blank, it will default to the buyer contact name.
stripePaymentConfig Optional N    

Parent tag

This section should only be populated if the bank is enabled for Stripe.

stripePaymentEnabled Optional N Boolean False
  • Denotes if Stripe payments are enabled for the buyer.
  • Valid values:
    • True
    • False
  • Should only populate this field if bank is enabled for Stripe.
  • If the value is set to true, and the bank is not enabled for Stripe, the request will be rejected. 
remittanceNotificationEnabled Optional N 1 False
  • Denotes if the Stripe Payment Remittance notification is enabled for the buyer.
  • Valid values:
    • True
    • False
  • Should only populate this field if bank is enabled for Stripe.
  • If the value is set to true, and the bank is not enabled for Stripe, the request will be rejected. 
boostPaymentConfig Optional N    

Parent tag

This section should only be populated if the bank is enabled for Boost.

boostPaymentEnabled Optional N Boolean False
  • Denotes if Boost payments are enabled for the buyer.
  • Valid values:
    • True
    • False
  • Should only populate this field if bank is enabled for Boost.
  • If the value is set to true, and the bank is not enabled for Boost, the request will be rejected. 
paymentNotificationConfig Optional N     Parent tag
defaultLanguageCode Optional N 10 Default to en_US.
  • Denotes the language used in notifications sent to the buyer.
  • Valid values: See the Language Codes table.
dateFormat Optional  N 10  
  • Denotes the date format used for parsing data fields in the payment files sent in EDI, CSV, or tab format. 
  • Valid values: See the Date Formats table.
attachRemittance Details Optional  N Boolean Default to bank value.
  • Denotes if the remittance details file containing invoice details will be attached to the payment advice notification while processing a payment. 
  • Valid values: 
    • True
    • False
  • The bank must be enabled to receive the remittance details file before th buery can be enabled. 
supplierReminderNotificationEnabled Optional N 2 7, if the reminder notification is enabled. Otherwise, default is 0.
  • Denotes the number of days before the payment expiration date that the system sends a reminder notification to the supplier.
  • Must be less than payment expiration days.
  • Numeric. 2 digits.
  • Valid values: 1-99
paymentSecurityConfig Optional N     Parent tag
defaultSecurityFieldCode Optional N 1 1 (Postal code)
  • Denotes the field system used to authenticate the supplier when they click the URL sent in the payment advice notification to view the full card details. 
  • Valid values: 
    • 1 - Postal code
    • 2 - Supplier ID
defaultSecurityQuestion Optional N 257 "Credential Text"
  • Denotes the text for the default security question shown to the supplier when they click the URL sent in the payment advice notification to view the full card details. 
  • Security vulnerability characters are not allowed.
customizeSecurityQuestionsEnabled Optional N 1 False
  • Denotes whether the buyer wants to use custom security questions to authenticate the supplier when they click the URL sent in the payment advice notification to view the full card details. 
  • Valid values: 
    • True
    • False
  • This is only allowed if the bank is enabled for custom security questions. 
customSecurityQuestions Conditonal N 100 (for each string value)  
  • Collection of string values.
  • Text used for collection of security questions to be used at random to authenticate the supplier when they click the URL sent in the payment advice notification to view the full card details. The system sends the security questions and answers to the supplier when the supplier is setup for the buyer. 
  • At least one question must be sent if custom security question is enabled.
  • Security vulnerability characters are not allowed.
authorizationControlConfig Optional Y    

Parent tag

This section should only be poulated if the bank is enabled for auth controls.

authControlEnabled Conditional Y 1

Default to True for VPP and VIP buyers. 

Default to True if mandateAuthControls is enabled.

Otherwise, false.

  • Denotes if authorization controls should be enabled for the buyer.
  • Auth controls are mandatory for buyers using Visa Pseudo accounts and TSYS VANs, or PANs where auth controls are required by the bank. 
  • Valid values:
    • True
    • False
  • This field should only be populated if the bank is enabled for auth controls. 
issuerHoldingBID Optional Y 8  
  • Required if auth controls are enabled and the token type is not VPP.
  • Denotes the Holding BID (Business ID)  for the issuer.
  • Must be a valid Visa 8-digit BID.
  • Numeric.
alertsEnabled Conditional Y Boolean  
  • Applicable only if auth controls are enabled and the token type is not VPP.
  • Denotes if the system should send an alert when an authorization on a VPC enabled card is approved or declined.
  • Required if auth controls are enabled for the buyer.
  • Valid values: 
    • True
    • False
buyerFeatureConfig Optional       Parent tag
cardMaskingDigitsOnline Optional Y 2 12
  • Denotes the amount of numbers masked on the card number when displayed in the UI.
  • Numeric.
  • Valid values: 4-12
cardmaskingDigits Optional Y 2 12
  • Denotes the amount of numbers masked on the card number when displayed in the recon files, response files, etc. 
  • Numeric.
  • Valid values: 4-12
  • To mask card numbers in the API response, contact your Visa Implementation resource to configure.
onlinePaymentInstructionEnabled Optional N Boolean False
  • Denotes whether online payment instruction (Pay Now) is enabled for the buyer.
  • Valid values: 
    • True
    • False
onlinePaymentRequisitionEnabled Optional N Boolean False
  • Denotes whether online payment requisition is enabled for the buyer.
  • Valid values:
    • True
    • False
  • The bank must be enabled for online payment requisition before the buyer can be enabled. 
fullAccountViewEnabled Optional Y 1 Y
  • Denotes if the buyer can view the full 16-digit account number, expiration date, and CVV2.
  • Valid values:
    • True 
    • False
  • The bank must be enabled for full account view before the buyer can be enabled.
pseudoAccountsEnabled Optional Y Boolean False
  • Denotes whether Pseudo Accounts (VIP tokens) are enabled for the buyer.
  • Valid values:
    • True 
    • False
  • The bank must be enabled for pseudo accounts before the buyer can be enabled.
approvalWorkflowConfig Optional  N    

Parent tag

Collection of approval workflow functions.

workflowConfigEnabled Optional N Boolean False
  • Denotes if approval workflow is enabled for the buyer.
  • Valid values: 
    • True
    • False
workflowFunctionCodes Conditional N 4  
  • Denotes functionality codes for which approval workflow should be enabled.
  • Collection of string values.
  • Valid values: 
    • AUCL -Card Limit Update
    • LCRC - Lodge/NewCard
    • PYIN - Payment Instruction
    • PYRN - Payment Requisition
webServicesConfig   Y     Parent tag
webServicesEnabled Optional Y Boolean False
  • Denotes whether web services are enabled for the buyer.
  • Valid values: 
    • True
    • False 
vbdsClientId Optional 50   Unique identifier generated for third parties wanting to subscribe to auth/settlement data in VBDS system.
clientId Reserved for future use     Reserved for future use. Reserved for future use.
apiCodes Reserved for future use     Reserved for future use. Reserved for future use.
suppressSupplierNotification Optional N Boolean False
  • Suppresses supplier notifications like payment remittance advice, security questions/answers, reminders, etc. 
  • Used when a third party provides this information directly to the supplier. 
  • Valid values: 
    • Y
    • N
  • Applicable only when the suppress notification option is enabled for the bank.
inboundCommFileConfig Optional N    

Parent tag

Applicable to buyer who use the system-to-system connection to submit payments. 

Should be at least one if EDI payment processing is involeved. 

Comm File Info corresponding to the payment file (EDI 820, EDI 997 ack file) and response file (EDI 824).

inboundFieldId Conditional N 40  
  • Comm file ID associated with the EDI 820 inbound payment file.
  • Required if EDI 820 or SFF payment file is recieved via comms.
  • Comm file must be set up in COMMs.
  • The Comm File ID is provided by the Visa implementation team. 
edi997FileId Optional N 40  
  • Comm File ID associated with the EDI 997 outbount ack file corresponding to the payment file. 
  • The fileFormatType of the Payment File Info must be 280 or it will be rejected. 
  • Valid values are in the VSM database.
  • The Comm File ID is provided by the Visa Implementation team.
responseFileConfig Optional N    

Parent tag

Applicable to buyers who use the system-to-system connection to submit payments.

fileLevel 

Conditional  N 1  

Valid values: 

  • B - Bank
  • C - Company
commFileld Optional N 40  
  • Comm File ID associated with the Response file outbound. 
  • Required if the file level is B.
  • Comm File ID is provided by the Visa implementation team.
fileFormat Conditional N 1 4 - CSV V1
  • Response file format to be generated.
  • Numeric.
  • Valid values: 
    • 1 - XLS V0
    • 2 - CSV V0
    • 3 - XLS V1
    • 4 - CSV V1
recipientLoginIds Conditional N 50 (size supported for the login ID in VOL)  
  • Contains the list of user IDs of bank/buyer users who will recieve the response file in their VOL mailbox. 
  • Required if the comm file ID for the response file delivery must be generated by the system. 
  • Up to 50 user IDs. 
  • All users are entitled to VOL Mailbox and VPA Service.
  • Must be an existing mailbox user. 
reconciliationConfig Optional N     Parent tag
onlinePaymentReconciliationEnabled Optional N Boolean False
  • Denotes whether reconciliation files can be triggered from the UI. 
  • Valid values: 
    • True
    • False
  • This field only need to be populated if the bank is enabled for online payment reconciliation. 
adhocReconciliationReportEnabled Optional N Boolean False
  • Denotes whether adhoc reconciliation is enabled for the buyer.
  • Valid values
    • True
    • False
  • This field only need to be populated if the bank is enabled for adhoc reconciliation.
fileLevel Conditional N 1  
  • Denotes whether the recon Comm file configuration is to be delivered to the bank or company. 
  • Valid values: 
    • B - Bank
    • C - Company
commFileId Optional  N 40  
  • Comm file ID associated with the recon file outbound.
  • Required if the file level is B.
recipientLoginIds Conditional N Collection  
  • Contains the list of user ids of bank/buyer users receiving the recon file in their VOL Mailbox. 
  • Up to 50 user IDs. 
  • All users must be entitled to the VOL Mailbox and VPA service. 
templateName Conditional  N 100 Most recent standard recon template.
  • Name of the recon template used to generate the reconciliation file.
  • Required if the recon file or adhoc recon file are enabled for the buyer.
fileFormat Conditional N 1 2
  • Format in which the recon file should be generated.
  • Numeric.
  • Valid values: 
    • 1 - XLS
    • 2 - CSV
deliveryFrequency Conditional N 1  
  • Frequency of recon file delivery.
  • Numeric.
  • Valid values: 
    • 1 - Daily
    • 2 - Weekly 
    • 3 - Monthly 
deliveryTime Conditional N 6

1:00 AM for Daily if not provided. 

2 if it is weekly.

1 if it is monthly.

  • Valid format for daily frequency: HH:MM in 24 hours format. Must be in GMT. 
  • Valid format for weekly frequency: 1-7 denoting the days of the week. 1 - Sunday through 7 - Saturday.
  • Valid format for monthly frequency: 1-31.
rvaReconciliationFileConfig Optional Y    

Parent tag

Applicable to those using the Request Virtual Account API.

fileLevel Conditional   1  
  • Denotes whether the RVA recon Comm file configuration is delivered to the bank or company. 
  • Valid values: 
    • B - Bank
    • C - Company
commFileId Optional Y 40  
  • Comm File ID associated with the RVA recon file outbound.
  • Comm File ID is provided by the Visa implementation team.
templateId Conditional Y 2 01
  • ID of the recon template used for generating the RVA reconciliation file.
  • Currently there is only one version. This field can be left blank, and the system will default to the most recent version. 
  • Valid value: 01. 
  • Must be a valid RVA template ID.
recipientLoginIds Conditional Y Collection  
  • List of user IDs of bank/buyer users receiving the recon file in their VOL Mailbox. 
  • Up to 50 user IDs.
  • All users must be entitled to the VOL Mailbox and VPA service. 
fileFormat Conditional  Y 1 2
  • Format in which the RVA recon file should be generated.
  • Numeric.
  • Valid values: 
    • 1 - XLS
    • 2 - CSV
deliveryFrequency Conditional N 1  
  • Frequency of recon file delivery.
  • Numeric.
  • Valid values: 
    • 1 - Daily
    • 2 - Weekly 
    • 3 - Monthly 
deliveryTime Conditional N 6

1:00 AM for Daily if not provided. 

2 if it is weekly.

1 if it is monthly.

  • Valid format for daily frequency: HH:MM in 24 hours format. Must be in GMT. 
  • Valid format for weekly frequency: 1-7 denoting the days of the week. 1 - Sunday through 7 - Saturday.
  • Valid format for monthly frequency: 1-31.
proxyConfig Optional Y     Parent tag
holdDays Optional Y 3 120 days
  • Number of days an account will be kept on hold before being used for another payment. 
  • For payments, the hold days start from the day the payment was processed.
  • For Request Virtual Account, the hold days start from the day the end date of the RVA has been reached.
  • Numeric.
autoRefresh Enabled Conditional Y   False
  • Denotes whether bucketed proxy is enabled for the buyer's proxies.
  • SUA buckets are 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.
  • Valid values: 
    • True
    • False
  • Required only if the bank's card type code is 2.
processorConfig Optional Y     Parent tag
processorFields Optional  Y   For API buyers who do not use processor related fields (Pseudo account or VPP buyers), set default values for the processor related fields depending on the processor.

For VPP/VIP TS2 buyers, set these values:

  • Unit ID: 1000000
  • Agent Number: 0000
  • Company No.: 1111111
  • Account ID Option Set: 1111
  • Ace Option Set: 1111
  • MailerID Option Set: 1111
  • Cycle Frequency: Monthly (Equivalent Code)
  • Cycle Code: 15

For VPP/VIP TS1 buyers, set these values:

  • Unit ID: 10923
  • Agent Number: 1092
  • Company No.: 10923
  • Cycle Frequency: Monthly (Equivalent Code)
  • Cycle Code: 15

For VIP FDR buyers:

  • Principal Number: 0
  • Agent Number: 1600
  • Map ID: FDR
  • Cycle Frequency: Monthly (Equivalent Code)
  • Cycle Code: 15
unitId Optional Y    
  • Required if Platform Code is TS1, optional if Platform Code is TS2 or TSYS_UK.
  • Not applicable to non-TSYS processors.
  • See “ProcessorFields” for more details.
agentNumber Optional Y 4 0000
  • Required for all if buyer processor/platform code is TS1, TS2, and FDR. Not applicable for FIS. 
  • Numeric.
  • See "Processor Fields" for more details. 
accountIdoptionSet Optional Y 4 1111
  • Required for TS2 and TSYS UK.
  • Not applicable for TS1, FDR, or FIS processors. 
  • See "ProcessorFields" for more details.
aceOptionSet Optional Y   1111
  • Required for TS2 and TSYS UK. 
  • See "ProcessorFields" for more details.
bin Optional Y 6 or 8  
  • Required Platform Code is FIS and if Product Type is VPA.
  • Not required for buyers enabled for Visa Pseudo Accounts and VPP TSYS VANs.  
  • See “ProcessorFields” for more details.
hierarchyNode Optional Y 7  
  • Required if Product Type is VPA and Platform Code is FIS.
  • Not required for buyers enabled for Visa Pseudo Accounts and VPP TSYS VANs.  
  • See “ProcessorFields” for more details.
processTypeCode Optional Y 2  
  • Required if Product Type is VPA and Platform Code is FIS.
  • See “ProcessorFields” for more details.
productCode Optional Y 3  
  • Required if Product Type is VPA and Platform Code is FIS.  
  • See “ProcessorFields” for more details.
subProductCode Optional Y 3  
  • Required if Product Type is VPA and Platform Code is FIS.  
  • See “ProcessorFields” for more details.
corporationId   Y 2  
  • Required if Product Type is VPA and Platform Code is FIS.  
  • See “ProcessorFields” for more details.
principalNumber   Y 4  
  • Required if Platform Code is FDR.
  • See “ProcessorFields” for more details.
paymentCardControlAccountNumber Optional Y 16  
  • Applicable if Platform Code is FDR.
  • See “ProcessorFields” for more details.
companyNumber   Y 5 or 7  
  • Required if PlatformCode is TS1, TS2, TUK, or TSYS_UK.
  • See "Processor Fields" for more details.
mapId   Y 4  
  • Required if Platform Code is FDR.
  • See “ProcessorFields” for more details.
user4Code Optional Y 4  
  • Applicable if Platform Code is FDR.
  • See “ProcessorFields” for more details.
pricing strategy Optional Y 4  
  • Required if Platform Code is FDR.
  • See “ProcessorFields” for more details.
authorizationStrategyCode Optional Y 4  
  • Required if Platform Code is FDR.
  • See “ProcessorFields” for more details.
plasticCode Optional Y 4  
  • Required if Platform Code is FDR.
  • See “ProcessorFields” for more details.
CMIDDefaultValue Optional Y 8  
  • Required if PlatformCode is TS1, TS2, TUK, or TSYS_UK.
  • See "Processor Fields" for more details.
cycleFrequency   Y 1  
  • Required if processor integration is enabled.
  • Valid values: 
    • 1 - weekly
    • 2 - bi-weekly
cycleFrequencyCode   Y 2  
  • Required if processor integration is enabled.
  • See "Processor Fields" for more details.
vanConfig Optional Y     Parent tag
  • Applicable only to buyers using TSYS VPP VANs.
  • Issuer must be enabled for TSYS VPP VANs.
vanEnabled Optional  Y Boolean False
  • Denotes whether TSYS VPP VANs are enabled for the buyer.
  • Valid values: 
    • True
    • False
  • The bank needs to be enabled before it can be enabled for the buyer.
fcsBankId Conditional Y 4 Bank FCS ID if there is only one setup at the bank level
  • Bank Identifier in the TSYS VPP FCS system. 
  • Alphanumeric.
  • Required if buyer is enabled for TSYS VPP.
  • Must be one of the values set for the bank.
visaADMOptionId Conditional Y 5  
  • For the TSYS VPP Platform, used to assign the virtual account number. 
  • For the TSYS VPP, either Visa ADM OPTION ID or MASTERCARD ADM OPTION ID is required.
  • For the TS1 platform only, must be set up to assign a virtual account number from the same BIN as the primary account number. 
  • Alphanumeric value.
mcADMOptionId Conditional Y 5  
  • For the TSYS VPP Platform, used to assign the virtual account number. 
  • For the TSYS VPP, either Visa ADM OPTION ID or MASTERCARD ADM OPTION ID is required.
  • For the TS1 platform only, must be set up to assign a virtual account number from the same BIN as the primary account number. 
  • Alphanumeric value.
ADMClientId Conditional Y 4  
  • For TSYS VPP system, this is the number used to identify the company on the ACE Decision Max system for account assignment. 
  • Required if buyer is enabled for TSYS VPP.
  • Alphanumeric.
processingType Conditional Y 4  
  • Processing type for the virtual account number (VAN). 
  • Alphanumeric.
  • Required if buyer is enabled for TSYS VPP.

    

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 in the API

Required/ Optional

RVA

Size

Default (If empty tag)

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 Requied

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.
expirationBufferDays Optioal

N

2

5

  • Must be numeric.
  • Must not be more than 2 digits.
  • Valid value: 1-99.
billingCurrency Requied

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 50 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

N

 

 

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

N

10

 

  • Valid values are one of the supported date formats. See the Date Formats table for all available date formats.
  • Applicable to Payment File processing.

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

 

  • 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

  • Must be numeric.  
  • Valid values: 4-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: 4-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:
    • 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

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

This table lists the Rules and Overrides for Request Virtual Account and Manage Payment Controls for Visa Payment Controls.

Rules and Overrides for Request Virtual Account and Manage Payment Controls
SL No. Rule Code Rule Description Override Override Code Override Value
1 ATM Block ATM cash withdrawals. N n/a 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 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 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 n/a
8 ADT Block purchases at adult-themed merchants. N n/a n/a
9 XBR Block all cross border transactions N n/a 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 cardAcceptorState or ProvinceCode 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
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 n/a
14 HOT All purchases made at hotel merchants will be declined. N n/a n/a
15 AUTO All purchases made at auto-rental merchants will be declined. N n/a n/a
16 AIR All purchases made at airline merchants will be declined. N n/a n/a
17 REST All purchases made at restaurants will be declined. N n/a n/a
18 JEWL All purchases made at jewelery store locations will be declined N n/a n/a
19 ELEC All purchases conducted at electronics themed-merchants will be declined. N n/a n/a
20 ALC All purchases conducted at alcohol and tobacco merchants will be declined. N n/a n/a
21 GTM All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls). N n/a n/a
22 OSS All purchases conducted at office supply merchants will be declined. N n/a n/a
23 GROC All purchases conducted at grocery store and pharmacy merchants will be declined. N n/a 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 n/a
25 UTIL All purchases conducted at utilities will be declined (includes cable, phone and electric companies). N n/a 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 n/a
27 MED All purchases made at medical merchants will be declined. N n/a 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 Card Acceptor ID tolerance Y CAIDValue Card Acceptor id value - Numeric (up to 15 digits)
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

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

Y 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.

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:

  •  startDate (in UTC)
  • endDate (in UTC)

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

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

Rules and Overrides for Virtual Card Requisition

This table lists the Rules and Overrides for Virtual Card Requisition for Visa Payment Controls.

Rules and Overrides for Virtual Card Requisition
SL No. Rule Code Rule Description Override Override Code Override Value
1 ATM Block ATM cash withdrawals. N n/a 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 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 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 n/a
8 ADT Block purchases at adult-themed merchants. N n/a n/a
9 XBR All purchases outside of the United States will be blocked. N n/a 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 cardAcceptorState or ProvienceCode 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 n/a
15 HOT All purchases made at hotel merchantswill be declined. N n/a n/a
16 AUTO All purchases made at auto-rental merchants will be declined. N n/a n/a
17 AIR All purchases made at airline merchants will be declined. N n/a n/a
18 REST All purchases made at restaurants will be declined. N n/a n/a
19 JEWL All purchases made at jewelery store locations will be declined. N n/a n/a
20 ELEC All purchases conducted at electronics themed-merchants will be declined. N n/a n/a
21 ALC All purchases conducted at alcohol and tobacco merchants will be declined. N n/a n/a
22 GTM All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls). N n/a n/a
23 OSS All purchases conducted at office supply merchants will be declined. N n/a n/a
24 GROC All purchases conducted at grocery store and pharmacy merchants will be declined. N n/a 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 n/a
26 UTIL All purchases conducted at utilities will be declined (includes cable, phone and electric companies). N n/a 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 n/a
28 MED All purchases made at medical merchants will be declined. N n/a 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.

Request Virtual Account Rules and Overrides for TSYS VPP
SL No Rule Code  Rule Description  Override  Override Code  Override Value  Comments
SPV  Spend Velocity Rule  Y amountCurrencyCode  ISO Currency Code  The startDate and endDate must be in Eastern Standard Time (EST).
spendLimitAmount  Amount 
maxAuth  Number
startDate MM/DD/YYYY or YYYY-MM-DD
endDate MM/DD/YYYY or YYYY-MM-DD
VPAS  Exact Amount Match Rule.  Authorization amount must match the request, to the $.01.  This rule only allows a single approved authorization.  amountCurrencyCode  ISO Currency Code   
amountValue  Amount 
TOLRNC  Tolerance Rule: Authorization amount must be between the minimum $ and the maximum $ amount defined. This rule only allows a single approved authorization.  amountCurrencyCode  ISO Currency Code   
minValue  Amount 
maxValue  Amount 
DOM  Purchases conduted outside of the selected state will be enabled.  cardAcceptorState or ProvinceCode  ISO USA State Code  State code is valid for USA (840) country code 
CountryCode  ISO Country Code   
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

Note: weekDayEffective is case sensitive 

Only supports US-based time zones (PST, MST, CST and EST).

weekDayEffective  Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday
timeEffectiveStart  HH:mm:ss
timeEffectiveEnd  HH:mm:ss
ATM  Enable ATM cash withdrawals.  n/a  n/a  
ECOM  Enable all Internet-based transactions.  n/a n/a  
CNP  Enable Card Not Present.  n/a  n/a  
FUEL 

Allow purchases conducted at fuel/driver merchants.

Allowed MCC Range: 5541 - 5542, 7542 - 7542.

n/a n/a  
10  AUTO 

Allow purchases made at auto-rental merchants.

Allowed MCC Range: 3351-3441, 7512-7512.

n/a n/a  
11  AIR 

Allow purchases made at airline merchants.

Allowed MCC Range: 3000-3300, 4511-4511.

n/a n/a  
12  REST 

Allow purchases made at restaurants.

Allowed MCC Range: 5811-5812, 5814-5815, 5462-5463.

n/a 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/a n/a  
14  ALC 

Allow purchases at alcohol and tobacco merchants.

Allowed MCC Range: 5813-5813, 5921-5922.

n/a n/a  
15  GTM 

Allow purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls).

Allowed MCC Range:4011-4112, 4121-4131, 4784-4784.

n/a 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/a n/a  
17  GROC 

Allow purchases conducted at grocery store and pharmacy merchants.

Allowed MCC Range: 5411-5461, 5464-5499.

n/a 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/a n/a  
19  UTIL 

Allow purchases at utilities (includes cable, phone and electric companies).

Allowed MCC Range: 4814-4815, 4899-4900.

n/a n/a  
20  MED 

Allow purchases made at medical merchants.

Allowed MCC Range: 4119-4119, 5975-5976, 8011-8099

n/a n/a  
21     PHAR 

Allow purchases made at Pharmacies.

Allowed MCC Range: 5122-5123, 5912-5913

n/a 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/a n/a  
23  LODG 

Allow purchases made at Hotels, Motels, Resorts, Specific lodging establishment.s

Allowed MCC Range: 3501-3838, 7011-7011

n/a n/a  
24  OTHR  Other MCC codes  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 Code  Override Value
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.

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.

Get Payment Controls Details for TSYS VANs
Rule Code  Rule Description  Override Code  Override Value
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