Visa B2B Payment Controls

There are different steps for inital usage and ongoing usage.

This section lists the steps you must follow to begin using Visa B2B Payment Controls. 

• Create a company. Set up an individual company or a global corporate buyer.
• Register your cards to that respective company. You can send via individual calls or use the bulk functionality. After registering the cards, use the service key in all subsequent calls to limit sending PCI.
• Set controls on your card portfolio. Provides flexibility to set initial controls on individual cards or the same controls across multiple cards.
• Set up notifications.  Optionally, set up email or SMS contacts for each card to receive ongoing notifications related to payment control decisions.

Note:  Prior to using APIs, the Visa implementation manager will work with you to set up the issuer and preferred configuration selections in Visa systems.  

This section lists the activities you must perform to use and manage Visa B2B Payment Controls.

• Manage card account information as needed for your companies.
• Manage payment controls for cards set up within your portfolio based on the business need in near-real time. Rule selection includes Spending Rules for payment protection, Merchant Category Rules, Location, Channel, and Business Hours.
• Leverage Get functionality to retrieve details about your company and card portfolio:
  • Pull details on the cards registered to a company.
  • Retrieve details on existing rules set on a card and see spend usage with the Spend Velocity Rule.
  • View all decline and limited authorization data including decline reason and merchant details.
  • View actual email and SMS decline notifications, rule, and merchant details.

Developer Note:  API fields sent in the message requests are not case sensitive.  All required fields must be present, but the order of sending fields is flexible.

This service allows you to set up a company as well as manage company changes within Visa B2B Payment Controls for which you will be managing rules on behalf of that company.  This service includes 4 operations:  create, update, delete, and get.  With these operations, you can create a new company, make updates to the existing company details, delete a company, as well as retrieve the details of an existing company and the associated accounts. See the API Reference page for more details.

You can set your companies up as individual companies or as a global buyer scenario with one master company. 

Note:  A company must first be registered before you can use the remaining Visa B2B Payment Controls APIs.

These operations are available for you to set up and manage your companies:

• Create Company – First, create a company for which you want to set up and manage rules.  Use this call to create the company within VPC.  In the request, you must provide issuer setup information as well as the company information.  Once set up in VPC, you will receive a company ID to use in subsequent calls to link the cards and actions to that company.
• Update Company – Use this call to make updates to an existing company in VPC. You may need to update a company setting, name, or contact information for an existing company. 
• Delete Company – Use this call to delete an existing company within VPC.  Depending on the reason, you may be able to use the update call instead.
  Note:  You cannot delete a company if there are cards associated with it.
• Get Company Details – Use this get call to retrieve all the details about a company setup in VPC.  You will see the company information as well as the last four digits of the card accounts associated to the company.

To use Visa B2B Payment Controls, you must register your applicable card portfolio to Visa Payment Controls (VPC).  You can register your full card portfolio in this initial step, or you can add additional cards prior to use.  You can also use this service to add existing cards to payment controls, update card parameters such as expiration date or card status, delete cards from the system, and retrieve card details from the system.  This service supports calls at an individual card level as well as bulk functionality for registration. See the API Reference page for more details.

• Create Account* – Use this operation to add your existing cards to VPC.  You must complete this step before you can set rules using Visa B2B Payment Controls.  You can register physical plastic cards or Visa virtual cards, but the card(s) must be set up prior to use.  Based on your program size, it might be a best practice to enroll your cards prior to launch instead of sending them individually. 
  • You can send individual cards or bulk cards within the same call when registering to the same company.
  • Each account registered will return a unique service key to use in subsequent calls to reduce PCI data being sent repeatedly.
• Update Account – Use this operation to make changes to your existing cards registered to VPC.  This can be used to make card expiration changes in addition to temporarily or permanently blocking a card from usage based on individual needs. 
• Delete Account* – Use this operation to remove cards from VPC.  You may want to use this if the card is no longer needed. Scenarios might include: an employee is leaving the organization or if there has been fraud.  If any card account is deleted, all rules will be removed from VPC, and notifications will be removed.
• Get Account Details* – Use this operation to retrieve details on an individual account or a group of accounts registered to a company.  This will return the account(s) settings.  You may want to use this to check existing settings prior to making any changes or to see any applied changes.

Note:  Operations marked with an asterisk * are eligible for bulk functionality.

After you have registered your company and card(s) to VPC, you are ready to begin setting controls on those cards. The Controls Management Service has three operations: set, delete, and get. These let you set rules on your cards, delete controls you no longer need, and get control details to see your existing rule configuration. See the API Reference page for more details.

• Set Controls* – Use this operation to send the full list of controls you want to apply to an individual card or multiple cards.  This operation is a full refresh (full replacement of existing rules) so you must send ALL the rules you want applied to the card within the single request.  These dynamic rules are applied in near real-time. You can set rules on an individual card or use the bulk functionality to apply the same rules to multiple cards.
  • The rule table provides the full list of available payment control rules and the specific parameters applicable for each rule. Some of the rules require you to send a single value and others have multiple parameters which require additional values. 
  • For example, some merchant rules only require that you send an alphabetic value, “HOT” where other spending rules, like Exact Match Rule “VPAS”, require that you send amount and currency parameters as well.
  • Rule Notes:
    • Multiple rules can be applied to a card account if they do not contradict each other.
    • Each account can have up to 200 rules applied.
    • Rules are applied nearly immediately, and the system does not support future dated rules.
    • The system uses GMT, so send both start dates and end dates for applicable rules using GMT.
    • When setting a spending rule, one ISO currency for rule setting should be specified in the request while the account is in use. 
• Delete Controls* – Use this operation to remove ALL rules from the card(s) in near real-time.  You can remove all rules from a card or use the Set Controls operation to replace existing rules with new rules. You cannot delete individual rules.
  Note:    If all rules are removed, you can set a block flag at the account level to block card usage. You can also request rules to be removed from multiple accounts at the same time. 
• Get Controls Details – Use this operation to retrieve the full list of all rules set on a card.  You can use this to see the full scope of applied rules before making changes using the Set Controls endpoint.  Additionally, this call returns the consumed balance and authorizations on the Spend Velocity Rule so you can manage the available balance. When using Spend Velocity Rule, send both start and end dates using GMT timezone. This is only applicable to SPV.

Note:   Operations marked with an asterisk * are eligible for bulk functionality

The Contact Management Service allows you to configure contacts to cards to receive decline notifications via email and SMS messages. You can also be set up for limited spend related authorization notifications. The Contact Management Service has three operations: create, delete, and get.   You can create an individual contact for a card or assign multiple contacts to a single card to receive notifications.  You can also delete existing contacts from an account.  Finally, you can get all contact details for a specific card that has been set up to receive notifications.

The Contact Management Service is optional. Use this service if you want your clients to receive decline notifications.  The email notifications are supported as html and can be customized with your logo and message preferences during implementation. See the API Reference page for more details.

Note:  You are responsible for validating that these are the correct contacts prior to use, because this service will send the notifications to the contacts provided.  You can remove any contact at a future time. 

• Create Contact* – Use this operation to assign email and SMS contacts to receive notifications for payment control declines or authorization for limited spend rules.  This can be used to set up a single contact for a card account or add multiple email and SMS contacts to a single card.
• Delete Contact* – Use this operation to remove existing email or SMS contacts that were associated to a card. The contacts you delete will stop receiving notifications.
  Note:     You can use bulk functionality to remove two or more contacts, associated with the same account number in a single call.
• Get Contact Details* – Use this operation to retrieve the details for the email or SMS contacts that are set up to receive payment control notifications. 

Note:  Operations marked with an asterisk * are eligible for bulk functionality.

Prior to using SMS, consult with your Visa implementation manager if SMS capability is enabled for usage within that respective country.

The Reporting Management Service allows you to retrieve both transactional decline details and notification details for a card. It contains two get operations. This service supports cardholder search and dashboard functionality within your user experience. See the API Reference page for more details.

• Get Notification History – Use this operation when you have configured notifications for cards and want to see the message level details.  You can view the exact message shared with the configured contact via email and or SMS.  For example, see message detail: “card xxxx was declined at merchant ABC for a purchase of $x.xx due to VPC rule abc.”
• Get Transaction History – Use this operation to see the transaction decline details for all card accounts. There is no notification setup required to use this operation.  It will provide the status of the transaction, merchant details, and the VPC reason the transaction was declined.  

The Visa B2B Payment Controls API supports bulk functionality in multiple requests for larger commercial portfolio management.  You can use the bulk functionality to register or delete multiple cards in a single call, add the same rules to multiple cards in a portfolio or remove rules, and add multiple contacts to a card to receive notifications.  Additionally, bulk functionality supports retrieving details in bulk fashion, such as account details and rules. You can use multiple sequence numbers to send multiple cards in the request.

Note:  Sending or receiving a larger bulk payload may result in increased response time. 

When you use an API that supports the bulk request option, you will receive a general 200 message if all the items are completed successfully; however, if one or more items is not successful, you will receive a general 207 message to indicate there are multiple results and you will need to review the individual account level status in the response to detect the specific failure.

The Visa B2B Payment Controls API provides rule-setting capabilities to protect commercial payments and supports small business use cases that need payment controls to limit spending.  It is targeted for those clients with existing card accounts to set dynamic rules at the card level.

If you have more robust payment needs, such as requesting a virtual account for on demand purchasing, or more comprehensive payment and reconciliation options, please consider using the B2B Virtual Account Payment Method API.  This Visa Business Solutions API solution provides payment and on-demand virtual account solutions, and also includes VPC protection.  

There are several code pages provided for your reference. These codes can be populated as needed based on the specific API and are explained in the field level specification. 

• Error Codes – This page  displays all common and service-specific error codes that Visa B2B Payment Controls may provide in the response. This page also includes all the response codes you can receive from Visa B2B Payment Controls when making a request.  Use this information to correct the request and resend for processing.
• Rule Codes – This page contains the rule code details and parameters that can be populated in the Set Controls request.  It includes sample formatting and field parameters for all payment controls.
• Master Codes – This page includes several other useful code tables for best practices.
  • Supported Languages – These codes are used in the Contact Management Service to define end-user language preferences for messages.
  • Supported Time Zones – These codes are used to define the time zone for international use.
  • Supported Currency Codes – This is a list of supported currencies with ISO codes that are used in spending rule requests.
    Note:  For a given account, all spending rules must be sent with the same currency while in use.
  • Supported Country Codes
  • Supported State Codes