B2B Virtual Account Payment Method

How to Use B2B Virtual Account Payment Methods

Creating Buyers and Templates

You can create buyers and buyer templates in the B2B Virtual Account Payment Method system using the endpoints of the buyer management web service (WS).

Creating Buyers

You can use the Create Buyer endpoint of the Buyer Service to create a buyer from scratch or by using a pre-defined Buyer Template for the issuer. If you are creating a buyer from scratch, you must provide all information about the buyer within the Create Buyer API. If you are creating a buyer from a template, you only need to provide buyer specific information, e.g. Buyer Info fields. 

This API aims to eliminate manual work from Visa's implementation team. (This does not restrict Visa and the Issuer from making changes to the buyer from the user interface.) Visa Payables Automation (VPA) sets up the buyer per user specifications and completes setup steps in downstream systems.

The Company ID must be the same Company ID at the processor (if applicable for processor integration). The Buyer ID and Buyer Name are displayed to users throughout the VPA UI and can be different from the Processor ID and Processor Name, or can be the same as the Company ID. 

Manual intervention may be required in file setup and configuration for reconciliation files. Depending on the way the files are set up, you may need to work with the Visa implementation resource to complete that setup after the company is created. 

Please reference Buyer Setup Details to see the full list of defaulted values per best practices. 

Additionally, refer to the Rules and Overrides page for codes used for date format, language format, and workflow function codes. 

Creating Buyer Templates

You can create buyer templates (up to 20 per issuer) to simplify the on-going effort of setting up buyers. This allows you to create templates tailored towards your issuer's deployment model, streamlining the work for new buyer implementations. In the future, when creating a buyer, you can reference the template name, and those settings will be applied to the new buyer. 

Certain fields within the baseline template will be defaulted to reflect the best practice; however, this group of APIs allows you to modify the default value(s). For example, payment expiration days will default to the best practice value of 30 days, but this can be modified if needed.

Please reference the  Buyer Setup Details to see the full list of defaulted values per best practices. 

Additionally, refer to the Rules and Overrides page for codes used for date format, language format, and workflow function codes. 

Updating Buyers Individually and Via Templates

You can update buyers individually or via template in the B2B Virtual Account Payment Method system using the endpoints of the buyer management web service (WS).

Updating Individual Buyers

You can update an individual buyer's parameters using the Update Buyer API. You can use this API to update the buyer's parameters regardless of whether the buyer was created using a template or from scratch. For example, if the buyer's default expiration days is set to 45 in the template, you can use Update Buyer to change the value to 30 later for a specific buyer.  

After you create a buyer, the Template ID cannot be added or changed. In other words, you cannot add a Template ID to a buyer that was not initially created with a Template ID. Similarly, if you created the buyer with one template, you cannot update that buyer to use a different Template ID.  In both scenarios, you can update the individual buyer with Update Buyer. 

When updating a buyer, include key identifiers (Client ID, Buyer ID, etc.) and the fields you want to update. You do not need to provide every field. Changes will occur immediately.

Please reference Buyer Setup Details to see the full list of defaulted values per best practices. 

Additionally, refer to the Rules and Overrides page for codes used for date format, language format, and workflow function codes.

Updating Buyers via Template

You can change parameters associated with a Template ID using the Update Buyer Template API. For example, if the default expiration days was originally set to 45 days, you can update the template to 30 days.

Also, you have the option to change all existing buyers using the template or to only apply the change to new buyers created after the change is made. You control this option via the Sync Buyer Profile field. If the value is Y, all existing buyers will be updated with your changed parameters and any new buyers will be created with the updated parameters. If the field is set to N, your changes will not apply to existing buyers, and only new buyers created after the template update will inherit your changes.

The Sync Buyer Profile option allows you to make changes to your buyers in bulk, but please exercise caution when updating all of your buyers. Consider all potential impacts to existing buyers before editing their parameters. 

If you create a buyer using a template you cannot move it to another template. The Template ID cannot be edited after a buyer is created. 

When updating parameters, only include key identifiers (e.g. Client ID, Template ID, etc.) and the fields that need to be updated. You do not need to provide every field. 

Template changes will take place immediately. 

Please reference Buyer Setup Details to see the full list of defaulted values per best practices. 

Additionally, refer to the Rules and Overrides page for codes used for date format, language format, and workflow function codes.

Deleting Buyers and Buyer Templates

Due to potential negative impacts, you cannot use APIs to delete individual buyers or buyer templates. Please contact your Visa Implementation resource to delete buyers or buyer templates. 

Managing Funding Accounts for Pseudo Accounts and TSYS VANs

Funding accounts are required for Visa Pseudo Accounts and TSYS VPP implementations. Pseudo accounts and TSYS virtual account numbers (VANs) roll up to a higher-level funding PAN. Issuers and fintechs with buyers who use these account types can use the Funding Account APIs to add, update, or view details about a funding account associated with a buyer. 

Before using these APIS, all issuer BIN tokenization and mapping must be complete. 

Because API requests and responses may include 16-digit PANs, API consumers must be PCI Compliant. 

Adding a Funding Account

To use the Add Funding Account API, the issuer or fintech provides a 16-digit PAN to serve as the parent account for a buyer's pool(s) of accounts. The funding account/PAN is usually provided by the issuer and is specific to a corporate buyer. A funding account can be the parent account for multiple pools under a single buyer, but the funding account cannot be used across buyers. 

For issuers with processor integration enabled, the credit limit and expiration date are not required because VPA retrieves that information directly from the processor. For issuers without processor integration enabled, all key information is provided in the API, but that information must match the information at the processor or there might be issues during transaction authorization. 

After you add a funding account, you can create account pools for it using the Proxy Pool APIs. 

Updating a Funding Account

The capabilities of the Update Funding Account API depend on whether or not processor interaction is enabled.

For buyers with processor interaction enabled, only the default flag can be edited. Other edits must be made directly at the processor and VPA pulls the latest information from the processor.

For buyers without processor interaction, the default flag, credit limit, and expiration date can be updated using the Update Funding Account API. This will apply changes to the account in VPA, but changes must also be made at the processor to ensure both systems are in sync. 

If you update the credit limit or expiration date, only accounts ordered after the changes are made will have the updated information. 

Deleting a Funding Account

Due to the potential negative impacts, you cannot use APIs to delete funding accounts. Please contact your Visa Implementation resource to delete a funding account. 

Viewing Funding Account Details

You can get the current status of a funding account with the Get Funding Account Details API. Details include key fields such as the credit limit, expiration date, and the number of active pseudo accounts associated with the funding account. Because a funding account can be used for multiple pools, this API provides the total number of active accounts across all pools. Active accounts are all of the accounts requisitioned under a funding account, and does not include deleted accounts. 

If processor integration is enabled, VPA will go to the processor to obtain the available limit and current balance on the funding account.

Single Use Account Proxy Pool Maintenance

You can manage the virtual accounts in a SUA proxy pool using the Single Use Account (SUA) Pool Maintenance API. For the details of the request and response for this endpoint, refer to API Reference.

Creating a Proxy Pool

You can use the Create Proxy Pool API to create a proxy pool for any type of single use account: Processor PANs, Visa Pseudo Accounts, and TSYS VANs.

For processor PANs, after the proxy pool is set up, the issuer needs to load the initial accounts into the pool by using the Manage Proxy API, the SUA Bulk Upload file, or the VPA UI. For issuers with processor integration, any subsequent orders after the initial load will be automated, and VPA will go directly to the processor to requisition the specified number of accounts. If the number of account in the pool triggers the reorder threshold (defined by the Minimum Available Accounts field), VPA will requisition the number of accounts (as defined by the reorder count field) from the processor and load them into the VPA pool.

For Visa Pseudo Accounts and TSYS VANs, all accounts are automatically requisitioned when the proxy pool is created. For Visa Pseudo Accounts, VPA requisitions accounts directly from the Visa Token Vault. For TSYS VANs, VPA requisitions accounts from the TSYS Token Vault. The number of accounts to be loaded into the pool is defined in the initial order count field. After the Create Proxy Pool request is complete, accounts will begin loading into the proxy pool within 15 minutes. For any subsequent orders after the initial load, VPA will go directly to the applicable token vault when the threshold is triggered (as defined by the Minimum Available Accounts field) and requisition the number of accounts (as defined by the reorder count field).

For Visa Pseudo Accounts and TSYS VANs, the full 16-digit funding account must be passed. Because the funding account information is not masked within the API, the API consumer must be PCI Compliant to use this API. 

Updating a Proxy Pool

After a proxy pool is established, only certain settings can be updated. Whether or not you can edit certain settings depends on whether or not there are accounts already loaded into the pool.

You can update the reorder count, minimum available accounts, and proxy pool type fields at any time. If account have not yet been added to the pool, you can also update the initial order count, credit limit, auth control flag, and proxy account type. 

Deleting a Proxy Pool

You can delete a proxy pool by using the Delete Proxy Pool API if no accounts have been added to the pool, and if no account requests are already in progress.

Viewing Proxy Pool Details

You can view the proxy pool settings and the number of accounts in the pool by using the Get Proxy Pool Details API. The accounts in the pool are provided by these statuses:

  • Available accounts - ready to be used for a requisition
  • Used accounts - currently being used in an open requisition or is in the holding period
  • Deleted accounts - will not be used for any future requisitions

For Visa Pseudo Accounts and TSYS VANs, the full, 16-digit funding account is passed in the response. Because the funding account information is not masked within the API, the API consumer must be PCI Compliant to use this API.

Getting the Status of a Bulk Account Request for SUA Proxy Pool

The SUA Get Account Status API is used to retrieve the status of account creation requests submitted using the Manage Proxy API. You need to pass the proxy pool number and the unique Account Request ID which was passed as part of the response to the Manage Proxy request (requesting multiple accounts). The system sends the details of the accounts that were successfully created as part of the response to this API. For the details of the request and response for this API, refer to API Reference.

Note: For proxy pools associated with buyer enabled for the pseudo account feature, the pool is auto replenished.  So the Add, Update and bulk account request actions are not supported.

 

Managing Suppliers You Would Like to Pay

You can setup the suppliers you would like to pay in the B2B Virtual Account Payment Method system using the endpoints of the supplier web service (WS).

Creating Suppliers

You can use the CreateSupplier endpoint of the Supplier WS to create a supplier and optionally associate an account for the supplier. You can create the account directly at the processor (through the issuer) and pass it in the request. If processor interaction is enabled for your bank, you will also be able to request a new virtual account from the processor through the system. The B2B Virtual Account Payment Method system generates a unique ID for each account requested from the processor. It takes 24 hours for the requested account to be activate at the processor. You can use the GetAccountRequestStatus endpoint in the Account Management API to find the status of an account you have requested at the processor.  If the buyer is enabled for the pseudo account feature, you can request a new pseudo account and associate it to your supplier.  The system generates the pseudo account from VisaNet and associates it with the supplier.

You can setup a SIP or a BIP supplier using the Create Supplier endpoint. If you would like to setup a BIP (STP) supplier, get the STP ID from the SMS application or from the issuer and pass it in the CreateSupplier request. You can also setup a supplier without associating an account with it. These suppliers (Suppliers without a lodged account), you will be able to pay by either passing an account in the process payment request or by using the SUA proxy pool. For details of how the payments are processed, refer to the ProcessPayment endpoint under the payment services.   

To enable a supplier for authorization controls, set the “Payment Control Required” flag to “Y”. The system will register all the accounts associated with the supplier turned on for "Payment Control" in the Visa Payment Controls (VPC) system and set a 1 cent exact match rule. This is to ensure that the supplier is not able to use the card account until a payment is actually made. This flag needs to be sent as "Y" for a buyer enabled for pseudo accounts feature. 

The B2B Virtual Account payment Method system sends the details of the account either sent in the request or requested at the processor (once it is activated) in an email notification to the supplier (using his primary email address sent in the request). If “SecurityCodeRequired” flag is set to “Y”, then the full card account information (full 16-digit card account number, expiration date and the CVV2) will not be passed while associating an account to a supplier but will be passed in the payment advice notifications. Also the system does not send the account information for STP suppliers.

Note: The new account email notification is sent to the supplier only if the “Suppress Notification” option is not set in the buyer profile.

Make sure that the message id passed in the request is unique. This id is needed to track a particular request during troubleshooting. For details on the request and response for this endpoint, refer to API Reference.

Updating Suppliers

You can use the UpdateSupplier endpoint for updating the attributes of a supplier already setup in the B2B Virtual Account Payment Method system. Using this endpoint, you will not be able to update the attributes of the accounts. For the details of the request and response for this endpoint, refer to API Reference.

Managing Supplier Accounts

You can use the ManageSupplierAccount endpoint for managing accounts associated with a supplier. Using this endpoint, you will be able to add a new account to a supplier. If your bank is associated with one of the processors the B2B Virtual Account Payment Method system is integrated with, you will be able to request for a new account from the processor. You can also create the account at the processor and send it in the request to be associated with the supplier. This endpoint also supports the update of account attributes and closing/deleting an account. If an account is closed, the system does the following:

  1. Cancels all the outstanding payments (Payments yet to be collected by the supplier) associated with the card account.
  2. Sends a notification to the supplier and buyer with the details of the payments that were canceled.
  3. If the account is enabled for authorization controls, removes all authorization controls and de-registers the account from VPC
  4. Removes the association of this card account from the supplier.
  5. If the processor integration is turned on for your bank, the system will close the account at the processor also.
  6. If the card account is associated with another supplier, the account will be removed from the other supplier too.

Note: For buyers enabled for pseudo accounts, the system allows only "Request New Card" or "Remove Account" actions.

For the details of the request and response for this endpoint, refer to API Reference.

Disabling Suppliers

You can use the Disable Supplier endpoint for deleting a supplier from the system. The system does the following for the supplier being deleted:

  1. Cancels all the outstanding payments associated with that supplier
  2. Notifies the buyer and supplier with the details of all the payments that were canceled.
  3. Deletes/Closes all the card accounts associated with the supplier. (All the steps for deleting an account will be executed).

For the details of the request and response for this endpoint, refer to API Reference.

Getting Supplier Details

You can use the GetSupplierDetails endpoint for getting the details of a supplier already setup in the B2B virtual account payment method system. The details includes the supplier details and the details of all the accounts associated with the supplier.

For the details of the request and response for this endpoint, refer to API Reference.

Processing Payment Instructions and Requisitions using Virtual Cards or Pseudo Accounts

You can process payments to your SIP or BIP supplier or payment requisitions to request a virtual account to do the payment yourself using the Process Payment WS.  

Process a Payment to a SIP or BIP Supplier

You can process the following types of payments:

  • Conventional payment: Processes SIP and BIP payments and interacts with VPC for setting auth controls and/or the processor for adjusting credit limits depending on the configuration. This is available for both lodged and Single Use Accounts.
  • Payment requisition: Processes requisitions and interacts with VPC for setting auth controls and/or the processor for adjusting credit limits depending on the configuration.
  • STP only: Sends authorization/settlement request directly to CyberSource. Note: The supplier details passed through this endpoint is not saved in the system. Also, reconcilation is not available for this option.   

Conventional Payment Flow

The B2B Virtual Account Payment Method system does the following for the payment instructions (Conventional Payments):

Scenario 1: New Supplier: You are trying to pay a new supplier and passing the payment for the first time. 

  1. System sets up the supplier in the B2B Virtual Account Payment Method system.
  2. Picks an available account from a proxy pool based on the Account picking logic explained below:  
  3.  

    ACCOUNT PICKING LOGIC
    PAYMENT CURRENCY SUPPLIER IS VPC ENABLED POOL SELECTED
    Same as buyer Currency Yes
    Adjustable limit pool with Visa Payment Controls (VPC) enabled. If no accounts are available or no adjustable limit pools with VPC enabled are available, choose a card account from a SUA pool which is enabled for VPC. If no accounts in the SUA pool or no SUA pools with VPC enabled are available, reject the payment.
    Same as buyer Currency No Adjustable limit pool not enabled for VPC. If no accounts are available or no adjustable limit pools not enabled for VPC are available, choose a card account from a SUA pool which is not enabled for VPC. If no accounts in the SUA pool or no SUA pools that are enabled for VPC are available, reject the payment.
    Different from buyer currency
    Yes SUA pool enabled for VPC. If no accounts in the SUA pool or no SUA pools with VPC enabled are available, reject the payment.
    Different from buyer currency
    No SUA pool not enabled for VPC. If no accounts in the SUA pool or no SUA pools that are enabled for VPC are available, reject the payment.

     


  4. If it is an adjustable limit proxy, system will adjust the credit limit of the account picked by the payment amount.
  5. If the proxy is enabled for VPC, system will set the exact match rule on the account for the payment gross amount.
  6. Sends the payment advise notification to the supplier

Note:  For proxy pools associated with buyers enabled for the pseudo account feature, if there are no available accounts in the proxy pool picked, the system will generate a new pseudo account (from VisaNet) and use that for the payment.  If it is a regular account proxy pool, the request will be rejected f there are no accounts.

Scenario 2: Existing Supplier: You are trying to pay an existing supplier

  1. System uses the account number or proxy sent in the account number field to process the payment.
  2. If the account number is blank, system uses the default lodged account for the supplier sent in the request.
  3. If there is no lodged account for the supplier, the system picks an available account from a proxy pool based on the Account picking logic explained above
  4. If it is an adjustable limit proxy, system will adjust the credit limit of the account picked by the payment amount.
  5. If the proxy is enabled for VPC, system will set the exact match rule on the account for the payment gross amount.
  6. Sends the payment advice notification to the supplier. 

Note:  In both of the above scenarios, if security code is not required for the supplier, the secure URL for getting the account details (full 16 digit card account number, cvv2 and expiration date) will not be sent in the payment advice notification.

Scenario 3: A BIP (STP) supplier.

  1. System sets the supplier in the system as a STP supplier if it is a new supplier.
  2. For an existing STP supplier, if the account number is sent as blank in the request, system uses the default lodged account for the supplier sent in the request.
  3. If there is no lodged account for the supplier, the system picks an available account from a proxy pool based on the Account picking logic explained above
  4. If it is an adjustable limit proxy, system will adjust the credit limit of the account picked by the payment amount.
  5. Initiates the authorization for the payment amount through CyberSource.
  6. Sends an optional remittance notification to the supplier.

Note: In all the above scenarios, if the system does not find a lodged account or there are no available account in the proxy chosen, the system will reject the payment request. For pseudo account, the logic is the same except that if there are no available accounts in the proxy pool, the system generates a new pseudo account, places it in the proxy pool picked and uses the newly generated account to complete the processing of the payment. If you want the system to generate a pseudo account and lodge it to the supplier, send the last 6 digits or the full 16 digits of the funding account in the account number field. The system uses the funding account passed to request for a new pseudo account and lodges it to the supplier. You can also optionally request for a new pseudo account for an existing supplier by passing the funding account number.   

Scenario 4: Paying a supplier by passing the proxy pool number in the account number field.

You can also pass the proxy pool, which you would like to use for making a payment. The system will:

  1. Pick an available account in the proxy pool. 
  2. If the proxy pool is an adjustable limit pool, the system will adjust the credit limit of the account by the payment amount. 
  3. If the proxy pool is VPC enabled, the system will set the exact match rule on the account equaling to the payment amount.
  4. Sends the payment advice notification to the supplier
  5. If there are no available accounts in the proxy pool, the system will reject the request.
  6. If the proxy pool is of the wrong type (for example, if you use a proxy which is not enabled for VPC to pay a supplier for which VPC is enabled), the system will reject the request.

Note: In all the above scenarios, if the processor is down for nightly processing, the system will queue the payment and complete the processing after the down time.

For the details of the request and response for this endpoint, refer to API Reference.

Processing Payment requisition

You can request an account from a SUA proxy pool, for processing the payment yourself. The system does the following when you perform payment requisition:

  1. Picks an available account from the proxy pool you sent in the request. It uses a round robin method to pick the accounts, which are not in use.
  2. If the proxy pool is an adjustable limit pool, adjusts the credit limit by the payment amount.
  3. If the proxy pool is VPC enabled, the system sets the exact match rule equaling to the payment amount.
  4. Returns the full 16-digit account, expiry in the response of the payment requisition.
  5. You should use the getSecurityCode endpoint to get the CVV2 for the PAN returned for your payment requisition.
  6. If there are no available accounts, the system rejects the request

Resending a Payment

You can resend the payment instruction which you sent to a supplier using the Resend Payment endpoint. You can use this endpoint if the supplier has lost the original payment request. You can optionally increase the payment expiry date of the original payment using this endpoint if it is nearing the payment expiry date. For the details of the request and response for this endpoint, refer to API Reference.

Getting the Payment Detail URL

You can use the getPaymentDetailURL endpoint to get the secure URL which is sent in the payment advice notification. This URL is used for authenticating the supplier before showing the full payment information (including the 16-digit account, expiry date and CVV2 details). For the details of the request and response for this endpoint, refer to API Reference.

Note: This URL is generated only if the supplier notification is not suppressed in the buyer profile. 

Get Payment Controls

You can view the current state of the authorization controls on an account using the getPaymentControls endpoint. This endpoint will provide the list of all the authorization controls currently active on a virtual account (Processor PANs, Pseudo Accounts, and TSYS VANs). Additionally, it allows clients to get the accumulated balance ($ amount and # of authorizations) on the account so far, as well as the remaining amount ($ amount and # of authorizations) on a Spend Velocity Rule for an account.  For details about the fields in the request and response, refer to API Reference. For more information about the control details provided in the response, refer to the B2B Virtual Account Payment Method Codes page.  On this Codes page, there are two tables you need to refer to.  First, navigate to the Rules and Overides section for your use case and account type to view the override codes for all rules.  Second, the Get Payment Controls section will provide additional fields/overrides that are included in to the Get Payment Controls API (for your account type) on top of the override codes in the first table.  

Get Payment Details

You can use the getPaymentDetails endpoint to retrieve the details of all the payments made in the last 90 days. System optionally allows you to search for payments made within a date range, payments with a particular status, and a single payment by providing the tracking number (message id of the original process payment request). For the details of the request and response for this endpoint, refer to API Reference.

The system retrieves the details of the first 250 payments qualifying the search criteria you submitted in the request.. The response will indicate if there are more payment details to be retrieved.  If there are more, you can submit the request again for the next set of 250 payments.  You can do this until you have retrieved all the payment details. 

Canceling a Payment

You can cancel a payment which is not yet been collected by the supplier (in the unmatched status) using the cancelPayment endpoint. You need to pass the message id of the original payment request to cancel a payment. The system does the following when you cancel a payment:

  1. System sends the cancellation notification to the supplier requesting them not to collect the payment.
  2. If the payment was made using an adjustable limit account, reduces the credit limit by the payment amount.
  3. If the account was VPC enabled, removes the exact match rule equaling to the payment amount. If that is the last control on the account, places a 1 cent rule on the account so that no one is able to collect any amount using the account.
  4. Sends a notification to the buyer indicating the payment that was cancelled.
  5. The detail of the cancelled payment will also be sent in the reconciliation file if you have subscribed to the reconciliation file.

For the details of the request and response for this endpoint, refer to API Reference.

Requesting Virtual Accounts and Managing Authorization Controls

You can use the Account Management Services APIs for setting authorization Controls, request for virtual account with authorization controls set for assigning it to an employee (VVAM program), to get the status of a new account requested from the processor and to get the security code or CVV2 of an account.

Manage Virtual Card Requisitions

You can use the virtualCardRequisition endpoint to request an virtual account from a VVAM program proxy pool for assigning it to an employee. You may also optionally add authorization controls on the card you are requesting. For details of the authorization controls supported in this endpoint, refer to API Reference. Refer to the codes page for Virtual Card Requisition Rules and Overrides. You can also update the requisition parameters using this endpoint. For the details of the request and response for this endpoint, refer to API Reference

Note: The Virtual Card Requisition end point does not support the Tolerance, Spend Velocity and the Card Acceptor ID authorization rules.

Request Virtual Account

You can use the Request Virtual Account endpoint to request one or more virtual accounts or pseudo accounts from a proxy pool and set requisition parameters. You may also add customized authorization controls on the card(s) you are requesting.  You are required to set a minimum of one spending rule for account protection ( for example, the Spend Velocity Rule). For details on the authorization controls supported in this endpoint, refer to API Reference. You can also update the requisition parameters ( including requisition expiration date and authorization controls) using this endpoint. For details on the request and response for this endpoint, refer to API Reference. Refer to the Get Payment Controls response section on the codes page at Request Virtual Account and Manage Payment Controls Rules and Overrides for more details. 

Note: If you set the requisition start date as a future date, the account will be returned in the response and a $0.01 rule will be placed on the account for protection. Once the future payment date is reached, the authorization control will be set on the account.  This is based the requisition start date and requires the time zone value to be specified.   

You can request more than one account using this endpoint. All requisitions will have the same account parameters, i.e. start date, end date, authorization controls.  If this option is used, a file will be generated with the card information. ( See Request Virtual Account: Endpoint File for Multiple Accounts.) This connection can be configured through the Visa Implementation Manager.

A reconciliation file will be available, daily, weekly, or monthly containing settlement data received from payment requisitions generated through this endpoint.  Please work with your Visa Implementation Manager to arrange the delivery configuration.  This file will  contain settlements that have come through and will be matched with their requisition information.  This settlement file includes the ability to pass up to 50 optional fields through the initial request. This information will be delivered in the Request Virtual Account Reconciliation Extract File. Based on your delivery configurations, you will receive an empty file with headers if there are no settlements for the time period. 

Note:  For proxy pools associated with buyers enabled for the pseudo account feature, if there are no available accounts in the proxy pool picked, the system will generate a new pseudo account (from VisaNet) and use that for the payment.  If it is a regular account proxy pool, the request will be rejected if there are no available accounts. 

Manage Payment Controls

You can manage the authorization controls set on an account using the managePaymentControl endpoint. This endpoint allows you to manage the authorization controls on any account (virtual or plastic). It allows you to add/remove or update the authorization controls and their effective date set on an account. For details of the authorization, controls supported by this endpoint and for the details of the fields in the request and response, refer to API Reference

Note: The Manage Payment Controls end point supports all authorization rules including Tolerance, Spend Velocity, and Card Acceptor ID.

Get Payment Controls

You can view the current state of the authorization controls on an account using the getPaymentControls endpoint. This endpoint will provide the list of all the authorization controls currently active on a virtual account (Processor PANs, Pseudo Accounts, and TSYS VANs). Additionally,  it allows clients to get the accumulated balance ($ amount and # of authorizations) on the account so far, as well as the remaining amount ($ amount and # of authorizations) on a Spend Velocity Rule for an account.  For details about the fields in the request and response, refer to API Reference. For more information about the control details provided in the response for each account type, refer to codes page for Request Virtual Account and Manage Payment Controls Rules and Overrides.

Get Account Request Status

You can get the status of an account you have requested from the processor using the getAccountRequestStatus endpoint. You need to pass the unique account request id (which the system returned as the response for your account request). It takes 24 hours for the account to be active at the processor. If you send the request after 24 hours of requesting, the system will return the account number (of the newly created account) and its expiry date in the response. For the details of the request and response for this endpoint, refer to API Reference.

Getting the Security Code (CVV2) of an account

You can get the security code (CVV2) of an account using the getSecurityCode endpoint. You need to pass the full 16 digit of the account number and the expiry date of the account and the system will retrieve the security code and send it in the response. This endpoint can be used for retrieving the security code for both regular virtual accounts (processor based) and pseudo accounts (generated by Visa). For the details of the request and response for this endpoint, refer to API Reference.

Getting the status of the Exact Match control(s) on an account

You can get the details of all the exact match rules set on an account using the listPaymentControls endpoint. For the details of the request and response for this endpoint, refer to API Reference.

Note:  If you have not coded to this API, please use the Get Payment Controls API to get details about all rules on an account. 

Request Virtual Account Reconciliation Extract File Format

This is the file specification and layout for the Request Virtual Account Reconciliation Extract File. All settlements that come through originating from the Request Virtual Account API will be matched with the payment requisition information, including the requisition status.  The user has the ability to include up to 50 optional fields in the original requisition request, and it will be passed through to the reconciliation file.   The file is available daily, weekly, or monthly and can be configured through the Visa Implementation team. Based on your delivery configurations, you will receive an empty file with headers if there are no settlements for the time period. 

Note: There are three available statuses for the requisition: Active, Complete, and Delete.

Active "A"  - This indicates if a settlement is attributed to an open requisition.  The settlement is received within the requisition validity dates.
Complete "C" - This indicates if the settlement was received after the requisition validity end date.
Delete "D" - Deleted - The settlement was received for a deleted requisition.

Request Virtual Account Reconciliation Extract File Format Specification

FIELD NAME   FIELD SPECIFICATION(TYPE)  FILE SPECIFICATION
(LENGTH/FORMAT) 
FIELD DESCRIPTION DATA SOURC
Bank ID  Alphanumeric  15  The bank ID is the bank identifier as defined in Visa Payables Automation.   Derived from the client ID sent in the web service request 
Buyer ID  Alphanumeric  25  The buyer ID is the buyer identifier as defined in Visa Payables Automation.  Derived from the buyer ID sent in the web service request 
Account Number  Numeric  16 

The account number identifies the account for the defined requisition parameters. 

 

If the masking feature is enabled, the account number will be masked per the specifications in the Buyer Profile. 

The account picked from the proxy pool requested in the web service request 
Proxy Pool ID  Alphanumeric 19  Unique identifier of the single use proxy pool Web service request 
Requisition Start Date  Date  Buyer Date format 

Account validity start date.

This is based on the date format set up in the Buyer Profile. 

Web service request
Requisition End Date  Date  Buyer Date format 

Account validity end date. 

This is based on the date format set up in the Buyer Profile. 

Web service request
Time Zone  Alphanumeric 12 

The timezone used in the payment instruction.   This will be in the format of UTC-6, UTC+8, etc.  

Note: For VPP/buyers using VANs, the timezone should reflect EST.

Web service request
Billing Amount  Decimal  18, 2  The billing amount of the transaction. This will be transaction amount converted to the billing  currency. BASE II Settlement 
Billing Currency Code  Alphabetic The billing currency of the transaction.  ISO-alpha currency code. BASE II Settlement
Transaction Amount  Decimal 18, 2  BASE II value for posted and settled transaction; Value reflects decimal point followed by two values; dash or “-" sign indicates negative value. BASE II Settlement 
Transaction Currency Code  Alphabetic This is the currency code in which the transaction occurred.  BASE II Settlement 
Merchant Category Code  Alphanumeric This is the merchant category code associated with the transaction.   BASE II Settlement 
Merchant Name  Alphanumeric 50  This is the merchant name where transaction was processed. BASE II Settlement 
Merchant City  Alphanumeric 50 

This is the city that corresponds to the merchant name/location where the transaction was processed. 

Note: This field may contain the merchant's phone number. 

BASE II Settlement 
Merchant Country Code  Alphanumeric 50  This is the country code that corresponds to the merchant name/location where the transaction was processed..   BASE II Settlement 
Purchase ID  Alphanumeric 75 

The purchase ID passed in the posted and settled transaction. (May not be present in all cases.)

Only include the purchase ID if the merchant provides it. 

BASE II Settlement 
Settlement Date  Date  Buyer Date format 

BASE II value for posted and settled transactions.

This is based on the date format set up in the Buyer Profile. 

BASE II Settlement 
Credit Debit Indicator  Alphabetic This indicates whether the transaction is - Credit or D - Debit.  BASE II Settlement 
Transaction Reference Number  Alphanumeric 24    Transaction reference number passed for the posted and settled transaction. BASE II Settlement 
Requisition Status  Alphabetic  This is the status of the requisition.There are 3 possible values. Valid values are:
    A - Active - The date when the settlement occurred is within the requisition validity dates.
    C - Complete - The settlement was received after the requisition validity date. 
    D - Deleted - The settlement was received for a deleted requisition.
VPA System 
Optional Field Name 1   Alphanumeric 50 Optional Field Name 1 sent in the web service request. Web service request 
Optional Field Value 1  Alphanumeric 100 Optional Field Value 1 sent in the web service request. Web service request 
Optional Field Name 50  Alphanumeric 50  You can enter up to 50 optional field names. These cannot exceed 50 characters. Web service request 
Optional Field Value 50  Alphanumeric 100  You can enter up to 50 optional field values. These cannot exceed 100 characters. Web service request 

Request Virtual Account: Endpoint File for Multiple Accounts

The Request Virtual Account API allows you to request more than one account with the same card parameters within one request.  When you request multiple accounts, your account information is sent through a file instead of through an immediate response. The following table lists the specification for the Request Virtual Account: Endpoint File for Multiple Accounts.

Note:  If you are requesting pseudo accounts, the PAN will not be passed in the file, only the pseudo account number will be provided. 


FILE HEADER FIELD
FIELD SPECIFICATION (TYPE)  FIELD SPECIFICATION (LENGTH /FORMAT)  FIELD DESCRIPTION 
Client ID  Alphanumeric  16  This is the client identifier. 
Bank ID  Alphanumeric  15  The bank identifier as defined in Visa Payable Automation. 
Buyer ID  Alphanumeric  25  The buyer identifier as defined in Visa Payable Automation.
Client Message ID  Alphanumeric  This is the client message identifier for the account.  
Account  Numeric  16  This is the full 16-digit account number.  
Account Expiry Date  Date  Year/Month  Account expiry month and year.  
Currency Code  Alpha  The currency code set up for the account. This is the billing currency. 
Requested Date  Date  Buyer Date Format  This is the date the Request Virtual Account request was made.  
Validity Start Date  Date  Buyer Date Format  This is the date from which the account will be valid.  
Validity End Date  Date  Buyer Date Format  This is the date after which the account will no longer be valid.  

B2B Virtual Account Payment Method for Pseudo Accounts

Visa Pseudo Accounts (referred to as VIP Pseudo Accounts) offer stronger account protection than using traditional processor based accounts. Issuers and their buyers can use pseudo accounts from the Visa Token Vault rather than the primary account number (PAN) to process a payment. In this model the issuer funding account (PAN) is mapped to a Visa token range for future payment use.  With Visa Pseudo Accounts (VIP Pseudo Accounts), you can implement a recycled Single Use Account (SUA) model with extended hold periods prior to reuse, or you can lodge a Pseudo Account with a supplier.  

Note: The processor must be certified for commercial tokenization before an issuer or third party can implement the Pseudo Account program. 

For Visa Pseudo Accounts:

  • You must have Visa Payment Controls enabled because authorization controls are required for all Pseudo Accounts. 
  • SUA Pseudo Accounts are automatically replenished.
  • Lodged Pseudo Accounts are not subject to a 24 hour hold period prior to use.
  • The Pseudo Account expiration date is equal to the funding account expiration date. 

Note: Previously, the Pseudo Account expiration date was equal to the funding account expiration date plus 3 years. This change is implemented to ensure that other Visa services support pseudo accounts. Payments inflight at the time of the change are not affected. 

API Specifics for VIP Pseudo Accounts
API NAME AVAILABLE WITH PSEUDO ACCOUNTS? DIFFERENCES WITH PSEUDO ACCOUNTS
ACCOUNT MANAGEMENT APIs

Virtual Card Requisition

No

This API is not supported for Pseudo Accounts.

Manage Payment Controls

Yes

None. This API is used to manage auth controls.

  • At least one spending rule is required.
  • When the end date is reached, the system removes all controls and puts a one cent rule on the account. 
  • To remove all rules immediately, use action code X. This will remove all rules immediately and put the one cent rule on the account. 

List Payment Control

Yes

None. This API will only show the Exact Match Rule on the account. 

Get Account Status

No

This API is not needed for Pseudo Accounts because Pseudo Accounts are returned soon after they are requested. 

Get Payment Controls Yes The overrides for Visa Processor PANs and Pseudo Accounts are slightly different from the overrides for TSYS VPP VANs.  See the Get Payment Controls Response section of the Rules and Overrides Page

Get Security Code (CVV2)

Yes

None.

Request Virtual Account

Yes

None.  A spending rule is required for Pseudo Accounts. 

If there are no available accounts in the proxy pool, the system automatically orders a new Pseudo Account(s) and will return it in the response. 

Add Funding Account Yes

With processor integration enabled, the credit limit and expiration date are not required because VPA retrieves that information directly from the processor. If processor integration is not enabled, all key information is required in the API, but that information must match the information at the processor or there might be issues during transaction authorization. 

Only applicable to Visa Pseudo Accounts and TSYS VANs. (Funding Accounts do not apply to Processor PANs)

Update Funding Account Yes

For buyers with processor interaction enabled, only the default flag can be edited. Other edits must be made directly at the processor and VPA pulls the latest information from the processor.

For buyers without processor interaction, the default flag, credit limit, and expiration date can be updated using the Update Funding Account API. This will apply changes to the account in VPA, but changes must also be made at the processor to ensure both systems are in sync. 

Only applicable to Visa Pseudo Accounts and TSYS VANs. (Funding Accounts do not apply to Processor PANs)

Get Funding Account Details Yes

If processor integration is enabled, this can be used to retrieve the available limit and current balance on the funding account from the processor.

Only applicable to Visa Pseudo Accounts and TSYS VANs. (Funding Accounts do not apply to Processor PANs). 

SINGLE USE ACCOUNT POOL MAINTENANCE APIs
Create Proxy Pool Yes

Pseudo Accounts will automatically begin loading into the pool within 15 minutes of the proxy pool being created. 

Must provide the full 16 digit funding account number. Because the funding account information is not masked within the API, the API consumer must be PCI Compliant to use this API. 

Delete Proxy Pool Yes Note that proxy pools cannot be deleted if accounts have been added.  Due to the fact that account are ordered within 15 minutes of the pool being created, there is a small window of time when ths is possible.
Get Proxy Pool  Yes Must provide the full 16 digit funding account number.  Because the funding account information is not masked within the API, the API consumer must be PCI Compliant to use this API.
Update Proxy Pool Yes If accounts have already been loaded into the pool, the account parameters cannot be changed, only proxy features such as reorder count and minimum available accounts.  

Manage Proxy

Yes

The Manage Proxy API supports the Close Account action code for VIP-enabled Pseudo Accounts. 

Note: Pseudo Accounts will automatically request new tokens. This API should not be used to request accounts.

SUA Get Account Status

No

This API is not needed for pseudo accounts because they automatically request new tokens. 

PAYMENT APIs

Process Payment

Yes

The Process Payment API has these differences for Pseudo Accounts:

  • Account number field (picking logic)
    • If the accountNumber field is blank, the system looks for a lodged Pseudo Account.
    • If there is no lodged Pseudo Account, the system looks for an available account in the proxy pool. 
    • If there are no available accounts in the proxy pool, the system orders a new account from the token vault and processes the payment.
    • You can enter the proxy number in the accountNumber field to specify a proxy pool for payment. 
  • Card parameter fields (accountType, accountLimit, and expirationDate) should be left blank.
    Note: There is no adjustable credit limit on Pseudo Accounts.
  • Options:
    • Lodged: The system generates a Pseudo Account(s) using the specified funding account tied to the proxy pool to lodge the pseudo account(s) with the supplier. This lodged pseudo account can be used to make  and process future payments.
    • SUA: The system generates SUA accounts in a proxy pool using the specified funding account. When a payment comes in, it is paid from the existing proxy pool of accounts. 

Resend Payment

Yes

The system automatically sets the end date for the spend velocity rule using the end date (payment expiration date) passed in the Resend Payment request.

Get Payment Detail URL

 Yes

None.

Get Payment Details

Yes

None.

Cancel Payment

Yes

None.

SUPPLIER APIs
Create Supplier Yes

The issuer must be enabled for VIP pseudo accounts. You can create a supplier and lodge a Pseudo Account using the actionType field: 1 to request a lodged Pseudo Account. 

VPC is required for payments made with Pseudo Accounts. It is recommended to keep the paymentControlRequired field blank.  The system will automatically set the controls on the back end.  If a value is entered in this field, it must be set to Y for the request to process successfully. 

Update Supplier

Yes

Auth Controls must be enabled because they are required for Pseudo Accounts. 

Disable Supplier

Yes

If a supplier is disabled, the system will cancel the outstanding payments for the supplier. It will also close all pseudo accounts lodged to the disabled supplier.

Get Supplier Details

Yes

None.

Manage Supplier Account

Yes

VPC must be enabled.

Use the actionType field to request a new lodged Pseudo Account or remove an existing Pseudo Account: 

  • actionType 1— Request new account
  • actionType 4—Remove account
 BUYER MANAGEMENT APIs 
Create Buyer  Yes  See Buyer Setup Details page for indepth information about what is required, e.g. authControlsEnabled field must be true as Payment Controls are requried for Pseudo Accounts.
Update Buyer  Yes  See Buyer Setup Details page for indepth information about what is allowed to be updated, e.g. authControlsEnabled field must be true as Payment Controls are requried for Pseudo Accounts..  
Get Buyer Details  Yes  None.  
Create Template  Yes  See Buyer Setup Details page for indepth information about what is required, e.g. authControlsEnabled field must be true as Payment Controls are requried for Pseudo Accounts. 
Update Template Yes  See Buyer Setup Details page for indepth information about what is allowed to be updated, e.g. authControlsEnabled field must be true as Payment Controls are requried for Pseudo Accounts.. 
Get Template Yes  None.  

 

B2B Virtual Account Payment Method Error Codes

For an exhaustive list of error codes pertaining to the APIs on this page, see the B2B Virtual Account Payment Method Error Codes page. The codes are organized by API