B2B Virtual Account Payment Method

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 using TSYS Virtual Account Numbers (VANs). These APIs can also be used for requesting accounts with authorization controls and using the accounts for processing the payment yourself.

You can use VANs to handle payments for buyers associated with Visa and Mastercard issuers as this feature offers 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. 

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.   

These API 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. Use this format for all parameters within the rule. 
  • When sending a startDate and endDate for the overall payment requisition, send these parameters in Eastern Time Zone. 
  • When setting the Spend Velocity Rule (SPV), also send the rule startDate and endDate in Eastern Time Zone.
    
• Get Payment Controls 
  
  • View the current authorization controls on an account, at any given time
  • View the status of the Spend Velocity rule, for example, $ amount and # of authorizations already processed, and what is remaining to be authorized. 
• Add Funding Account
  • Add a Funding Account to an existing buyer's profile. 
  • For issuers 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 for the issuer, 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. 
  • Funding account can be the parent account for multiple pools under a single buyer, but the funding account cannot be used across buyers. 
  • After adding a funding account, you can create an account pool using the Proxy Pool APIs
• Update Funding Account
  • 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. 
• Get 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, this can be used to retrieve the available limit and current balance on the funding account from the processor.

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.    

SUA Get Account Status API - This endpoint is not applicable for VANs. Proxy pools set up for VANs are replenished automatically based on the configured settings.

Create Proxy Pool API - You can use this endpoint to create a proxy pool.  Accounts are requisitioned from the TSYS vault within 15 minutes of the pool being created.  The full 16 digit funding account must be provided (or the default funding account will be used, if applicable).  

Update Proxy Pool API - You can use this endpoint to update the proxy pool settings. Note that if accounts have already been loaded into the pool, only proxy features such as minimum available accounts and reorder count can be updated.

Delete Proxy Pool API - You can use this endpoint to delete a proxy pool, but only if no accounts have yet been loaded into the pool. Due to the fact that accounts are loaded within 15 minutes of being loaded, this likely is not applicable.

Get Proxy Pool API - You can use this endpoint to view the current parameters and status of an existing proxy pool, including the number of available accounts that can be used for a payment and total number of accounts in the pool.  

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 secure link in any outstanding payment notification emails is disabled.
3. The authorization rules set on the account are removed.
4. The VAN status is changed to canceled and the VAN expiration date is set to the current date.
5. 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 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.
• Get Payment Controls - This endpoint is supported for buyers using VANs. It allows you to view the current authorization controls on an account, including the status of the Spend Velocity rule (e.g. $ amount and # of authorizations already processed and what is remaining to be authorized).  For more information about the control details provided in the response, refer to two sections on the B2B Virtual Account Payment Method Codes page.  First, navigate to the Rules and Overides section for VPP VANs to view the override codes for all rules.  Second, the Get Payment Controls section will provide additional fields/overrides for VPP VANs that are included in to the Get Payment Controls API  on top of the override codes in the first table.
• 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.

Each time you make a payment and a VAN is selected, the VAN will receive a new expiration date. The VAN expiration month will be the payment instruction or requisition expiration month. The VAN expiration year is configured during implementation. The configured years will be added to the current year to determine the VAN expiration year. This is applicable to both payment instructions and payment requisitions.

For example, if the payment expiration date is set to October 1, 2019, and the VAN expiration year is configured for 3 years, the VAN expiration date will be set to 10/22. This will eliminate the risk of declined transactions because of an expired VAN. This also ensures that each payment has a unique CVV2 value.

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

Create Buyer API - You can use this API to create a new individual buyer in VPA. Refer to the Buyer Setup Details page for in depth details on the information required.   The vanconfig section is required and will include the buyer's TSYS Processor information, such as ADM Option and FCS Bank ID.  

Update Buyer API - You can use this API to update an individual buyer in VPA. Refer to the Buyer Setup Details page for in depth details on what information is allowed to be updated. 

Get Buyer Details API - You can use this API to view all parameters of an individual buyer in VPA. Refer to the Buyer Setup Details page for in depth details on what information is required. 

Create Template API - You can use this API to create a new template (up to 20 per issuer) that can be used to create new buyers in VPA.  A template is used when configurations are consistent from buyer to buyer so can be established upfront.  Once created, the Create Buyer API is used to create the individual buyer, significantly minimizing the fields required for setting up individual buyers.  Refer to the Buyer Setup Details page for in depth details on what information is required. 

Update Template API - You can use this API to upate dthe parameters of a template.  There is a "sync buyer" option to only make the changes for future buyers associated with the template, or to update any existing buyers using that template. Refer to the Buyer Setup Details page for in depth details on what information is allowed to be updated. 

Get Template API - You can use this API to view all parameters of a template.