B2B Virtual Account Payment Method Documentation

Ready to start coding?

Things To Know

Issuers, buyers, processors, third party payment providers or Travel agencies, can use the B2B Virtual Account Payment Method APIs. 

Note: A third party cannot implement the B2B APIs without an issuer. You can select a subset of our endpoints to code to based on your desired use case.  Once you setup an VDP account, Visa can provide you with consultative support.

With these APIs, you can automate the process of paying your suppliers. You can also request accounts with authorization controls, and use the accounts for processing the payment yourself.

Use the API explorer in the API Reference section to understand how to use APIs in the Sandbox. When you are ready to promote your project to CTE or production, you must fill in the details requested in the Project promotion form. A Visa implementation manager will setup the data required and promote your project to the requested environment. To get started, refer to the Getting Started section in the Visa Developer Center.

To make calls to the B2B Virtual Account Payment Method APIs, you need a client id. For the sandbox environment, the system will display a client id to use.  For other environments, your Visa implementation manager will complete the setup and provide the required client id.

Note: The sandbox environment is designed to provide a general view and guide of the endpoint request and response structure.  There are systematic limitations, and you cannot execute all API functionality or see the full list of accurate error codes through the API explorer in sandbox.

See the error codes page for the full list of accurate codes related to the B2B Virtual Account Payment Method. 

Availability

The following table lists the regional availability for B2B Virtual Account Payment Methods. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
B2B Virtual Account Payment Method
Product Name Availability Notes
B2B Virtual Account Payment Method Processor integration / adjustable limit functionality not available in Asia-Pacific. Multibyte characters are not supported.
Product Name Availability Notes
B2B Virtual Account Payment Method Currently excluded: Pseudo accounts, Visa Payment Controls, Request Virtual Account endpoint, and adjustable limit functionality. Reconciliation data only available for transactions flowing through VisaNet.
Product Name Availability Notes
B2B Virtual Account Payment Method
Product Name Availability Notes
B2B Virtual Account Payment Method Processor Integration /adjustable limit account functionality not available in LAC

Getting Started

The B2B Virtual Account Payment Method has APIs that allow you to use virtual accounts to automate the supplier payment process. You can use these APIs to develop flexible solutions across industries and segments. Whether it is a virtual account embedded within the procure-to-pay cycle, a virtual account used for payer-to-provider payments or a virtual account used in the travel booking process, this method will streamline the payment process.  

Consumers of the B2B Virtual Account Payment Method can choose to integrate to all of the available APIs to enable development of an end-to-end payables solution that includes: managing suppliers, accounts, and submitting payments. You can also integrate to a subset of the APIs for specific needs such as establishing authorization controls to reduce risk. 

The B2B Virtual Account Payment Method supports multiple payment options and handles both supplier-initiated and buyer-initiated payments. It also supports multiple account control options using authorization controls and credit limit adjustments. The B2B Virtual Account Payment Method also supports pseudo accounts (a type of Commercial token) in addition to processor-based PANs. Pseudo accounts allow added security for cardholders by having merchants process payments using pseudo accounts rather than a regular PAN. Pseudo accounts are generated internally at Visa rather than at the processor.

 

How Does It Work?

The B2B Virtual Account Payment Method system can be used to develop end-to-end payables solutions for automating the process of paying your suppliers. You will need to use several of the APIs described in the below section to accomplish this. This section explains high level payment processing flow for clients who are looking for an end-to-end payables solution.

Step 1: Buyer generates a payment instruction file and sends to you (third party).

Step 2: You (third party) make API calls for payment processing.

Step 3: The system sets controls on the account for Supplier Initiated Payments (SIP); it submits Straight through Processing (STP) transactions to acquirer for processing.

Step 4: The system sends confirmation of payment processing via API response.

Step 5: The system sends remittance notification and/or an optional file to the supplier.

Step 6: Supplier collects the payment using the card sent in the payment advise notification for SIP transactions; In the case of BIP (buyer initiated payments or STP) funds are deposited directly to supplier’s merchant account for STP transactions.

Step 7: The system matches the settlement with the payment.

Step 8: The system sends the reconcilliation data via API or file to you (3rd Party).

For more detailed API information, refer to the sections below.  If you wish to request a virtual account and embed the virtual account within your existing payment process, you can submit an API request and specify the authorization controls and the account validity period within the API request. Visa will then return an account number secured with authorization controls which you can then use within your existing payment process.

Why Use It?

The B2B Virtual Account Payment Method can benefit businesses with Visa Commercial card programs by allowing them to:

  • Automate their payables processes
    • Submit payment instructions to meet their payment needs
    • Automatically generate and distribute supplier payment remittances
  • Place account controls on purchases
    • Reduces risk of unauthorized card activities by allowing the supplier to collect only approved invoice amounts
  • Ease reconciliation
    • Streamlines reconciliation of the payments with the card account settlements as they clear.
    • Generates reconciliation files

APIs Included

Supplier Service

The Supplier web services allow you to create, update, delete (disable) a supplier you would like to pay.

Account Management Service

The Account Management web services are used to manage payment controls for existing card accounts and to request virtual accounts while setting controls. The end points allow you to do the following:  retrieve status of new account requests, view authorization rules, submit virtual card requisitions for an employee, and retrieve security code (CVV2) details of an existing account.

Payment Service

The Payment web services are used for processing payments (SIP and BIP) and sending the payment remittance information to the appropriate suppliers. Additional functionality includes resending payments, retrieving existing payment details, receiving the secure URL to access account, as well as canceling an existing payment(s). 

Single Use Account Pool Maintenance Service

The Single Use Account Pool Maintenace web services are used to manage a pool of Single-Use Accounts (SUAs) linked to a proxy pool.  When processing payments using a SUA proxy, the system will pick an available account from the proxy pool and sets the applicable authorization rules (sets the exact match rule and the spend velocity rule). 

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 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 for 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 codes page for Request Virtual Account and Manage Payment Controls Rules and Overrides.

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.

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 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 list of all authorization controls 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.

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.

Getting status of an bulk Account Reqest for a SUA proxy pool:

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

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

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.

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

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.  Web service request 
Account Number  Numeric  16  The account number identifies the account for the defined requisition parameters.  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. Web service request
Requisition End Date  Date  Buyer Date Format  Account validity end date. 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.   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 currencry 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.   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.) BASE II Settlement 
Settlement Date  Date  Buyer Date Format  BASE II value for posted and settled transactions.  BASE II Settlement 
Credit Debit Indicator  Alphabetic This indicates whether the transaction is C - 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 requistion 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 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.  

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.

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

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

Single Use Account Pool Maintenance APIs

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

 

 

B2B Virtual Account Payment Method for Buyers Using VANs

Overview 

Issuers, buyers, processors, third party payment providers, and Travel agencies, can use the B2B Virtual Account Payment Method APIs. By using these endpoints, you can automate the process of paying your suppliers. These APIs can also be used for requesting accounts with authorization controls and using the accounts for processing the payment yourself.

The B2B Virtual Account Payment Method also supports Virtual Account Numbers (VANs) which you can use to handle payments for buyers associated with Visa and Mastercard issuers thus, providing a single platform for both brands. The VANs are stored in a proxy pool(s) available to be used for making a payment.  The VANs are held in an inactive status in the proxy pool until it is assigned to a payment to prevent unauthorized use.   The proxy pool will be automatically replenished with VANs based on the configured settings.      

The VPA system sets the Exact Match and Spend Velocity authorization rules on VANs which are picked for making a payment.  The authorization rules are set on the VAN at the TSYS VPP system.  

Account Management

The majority of the Account Management Web Services are not applicable for buyers using VANs.  These include Virtual Card Requisition, Manage Payment Controls, List Payment Controls, and Get Account Status.   

The following Web Service Calls are supported for VANs:

  • Get Security Code—You can use this endpoint to retrieve the CVV2 number (security code) from TSYS for a specified VAN account.  The CVV2 (security code) may be required for suppliers to collect the payment through their POS system.
  • Request Virtual Account—You can use this endpoint for buyers using VANs. This endpoint allows you to:
    • Request a VAN stored in a Single Use Account (SUA) proxy pool, set the validity period of the VAN, and set authorization controls.
    • Manage an existing requisition, such as changing the validity period of the VAN, authorization controls placed on VANs, and optional field value

Implementation Notes:

  •  A minimum of one spending rule must be set on the VAN. This includes the Spend Velocity, Exact Match, and Tolerance rules.
  • When setting the Spend Velocity Rule, use 0 for the sequence number(s) rather than use increasing numeric values.
  • When sending a startDate and endDate for the overall payment requisition, send these parameters in Eastern Time. 
  • When setting the Spend Velocity Rule (SPV), also send the rule startDate and endDate in Eastern Time. 

See the Rules and Overrides table for a list of Request Virtual Account API Rules and Overrides to support buyers using VANs.

All settlements that come through will be matched with the payment requisition information.  See the Request Virtual Account Reconciliation Extract File Format Specification.   

Single Use Account Pool Maintenance

The Get Account Status endpoint is not applicable for VANs. Proxy pools set up for VANs will be replenished automatically based on the configured settings.

Manage Proxy API—You can use this endpoint only to delete a VAN. If a VAN becomes compromised, it can be deleted using this endpoint.

Deleting a VAN results in the following:

  1. All payments attached to the VAN are canceled.
  2. The authorization rules set on the account are removed.
  3. The VAN status is changed to canceled and the VAN expiration date is set to the current date.
  4. The settlement expiration date of the VAN is set to the current date plus the number of settlement days configured at the bank level. The settlement expiration date  is the last day that prior authorizations on a VAN can be settled.

Note: If the action type is not delete, this request will be rejected.

Process Payments

  • Process Payment—This endpoint is supported for buyers using VANs. There are three types of payments supported through the Process Payment API:
    • Payment Instruction– Only Single Use payments can be used for VAN enabled buyers.
      Authorization controls are mandated for Payment Instruction.  The Spend Velocity (up to payment) rule is applied to all VANs when used to make a payment.  Additionally, the Exact Match rule is also applied to improve the reconciliation process.
    • Payment Requisition- The system picks an account from the proxy pool sent in the request, and sets the Spend Velocity rule and the Exact Match rule on the VAN before it is returned in the response.
    • STP- Straight Through Processing (STP) is only supported for Visa payments.  Mastercard payments are not supported at this time for STP (Buyer Initiated Payments).
  • Resend Payment—This endpoint is supported for buyers using VANs. This endpoint can be used to resend the payment notification to the supplier as well as update the payment expiration date.
  • Get Payment Detail URL—This endpoint is supported for buyers using VANs. This endpoint can be used to return the payment remittance URL which can be used to send or resend to the supplier, enabling them to view the details of the VAN used for the payment.  
  • Get Payment Details—This endpoint is supported for buyers using VANs. This endpoint enables you to review the details on a payment instruction you have submitted.
  • Cancel Payment—This endpoint is supported for buyers using VANs.
    • This endpoint enables you to cancel payments that have not been collected by the supplier.
    • When canceling a payment using a VAN, the following will occur: (1) a cancellation notice is sent to the supplier, (2) the VAN is set to an inactive status to ensure that the payment cannot be processed.
    • If this is a multi-use pool, the VAN will follow the hold days configured for the buyer. If it is a true, single-use VAN, it will not be used again.

Supplier

  • Create Supplier—This endpoint is supported for buyers using VANs.
    • This can be used to create a new supplier.
    • An account cannot be added to the supplier for buyers enabled for VANs. If card details are provided as part of the web service call, the request will be rejected.
  • Update Supplier—This endpoint can be used to update information related to a supplier.
  • Disable Supplier—This endpoint is supported for buyers using VANs.
    • This can be used to disable a supplier and cancel any outstanding payments for that supplier.
    • The system will cancel the payment and the following will occur:  (1) a cancellation notice is sent to the supplier, (2) the VAN is set to an inactive status to ensure that the payment cannot be processed.
      • If this is a multi-use proxy pool, the VAN will follow the hold days configured for the buyer. If it is a true single-use VAN, it will not be used again.
      • For multi-use VANs, the VAN will be returned to the pool and held in a hold status for the time configured in the proxy settings.
  • Get Supplier Detail— This endpoint is supported for buyers using VANs. This endpoint is used to retrieve saved information for a supplier.
  • Manage Supplier Account—This endpoint is not supported for VAN-enabled buyers because lodged cards are not supported.  

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.