Virtual Cards (VCN)
This is the official reference documentation for the SVB Virtual Cards API. Please see the authentication documentation for access information.
The Virtual Cards API follows the same conventions as SVB's other APIs. Please see the conventions documentation for more information.

SVB currently provides a simple and powerful set of APIs allowing you to integrate virtual card numbers (VCNs) into your business applications.

Introduction

In addition to real-time issuance of virtual cards, VCN API offers the following set of capabilities to allow clients customize their card program:

  • Currency Control
  • Velocity Control
  • Aging-Velocity Control

Currency Control

Currency control feature can be used to create a virtual card with the desired currency. Setting the currency on the card simplifies reconciliation of the card balance by allowing the client to view the available balance in the currency of the merchant (where the card is being used).

Note: If the currency control is set, the purchase has to be in that merchant currency or the transaction will fail.

Currency parameter in the "Create Virtual Card" request can be used to set the currency of the virtual card.

 

Example Request

Currency Control example request

currency specified as a non-USD value in the request body.

 

Example Response

Currency Control example response

currency set as "DZD", as requested in the above example request.

Velocity Control

Configuration or usage of velocity controls are optional and are not required by the card program. 

Velocity control limits how much can be spent, per VCN, on a given period of time.

 

Example

A company can create a VCN and specify a recurring limit of $1000 on a monthly basis. In such scenario, if the card balance reaches $1000 on May 19th, the cardholder will not be able to use the card again until the beginning of next month. On June 1st, available funds on the VCN will refresh and $1000 spending limit will be available to the cardholder. 

Funds refresh at midnight UTC time zone / 5:00 PM Pacific. 

 

Parameters
Velocity window is the time period in which the funds will refresh. During VCN creation, recurring API request parameter can be specified with one of the below values to set the appropriate velocity control.

 

Velocity Window
CONTINUOUS (default)
DAILY
WEEKLY
MONTHLY
QUARTERLY
YEARLY
  • Above values are case-sensitive

 

If recurring parameter is not provided during VCN creation, then the request will default to use continuous as the velocity window. Continuous velocity means that there is no periodical limit (or refresh of funds).

 

Example Request

Velocity Control example request

Example Response

Velocity Control example response

 

Aging Velocity Control - Authorization Hold Period Control

Aging velocity enables the client to control how long an authorization is held on the VCN. This control can be used to specify an exact number of days an authorization is held on the card. After specified number of days passes without the merchant performing a clearing event, the authorization will be removed from the VCN.

 

Example Scenario

Aging Velocity example scenario

A travel company configures a 1 day hold for authorizations made on their virtual card. Cardholder uses their VCN to book a hotel room, hotel authorizes the whole amount, $1000, but does not settle the amount. After 1 day, the auth drops (ages off). Hotel will then settle for each night's stay. 

In the above scenario, once the hotel authorizes and submits a clearing for the transaction, the available balance would be reduced by that amount. At the end of the stay, hotel submits clearings for $200 total, reducing VCN's available balance to $9800.

 

Parameters

There are two required parameters used to specify aging velocity:

Name Description Type Default
authorization_hold_days

 Number of authorization hold days on the virtual account before the control drops the hold. 

 Resets after midnight on the hold expiry date in the time zone specified for the control.

 For example, an authorization processed on January 1st at 11:00 a.m. CST on a VCN with the   control set in CST and a hold of two days resets at 00:00:01 CST on January 4th. 

int N/A

 aging_velocity_time_zone

 For a list of all supported time zones, deprecations, and DST, see the Time Zone Support document provided on the Mastercard Connect website. string N/A

Notes:

  • Aging velocity feature requires a purchase template that has aging velocity capability. A default template allowing all MCCs codes and aging velocity control would've already been created for your account by card implementations team. You can find this using the /templates API call.
  • Card configuration can either have velocity control or aging velocity. Therefore, any request that contains the above aging velocity parameters and any of the velocity parameters (recurring and transactions_max) will result in an error.

 

Example Request

Aging Velocity example request

 

Example Response

Aging Velocity example response

 

VCN Reconciliation

There are two main reconciliation use cases for SVB VCN API clients:

  1. Mapping an authorization event to the clearing event
  2. Mapping a clearing event to SVB Online Banking statement

 

Mapping an authorization event to the clearing event

There are two ways to receive a clearing event, through VCN API clearing webhook notification or by processing the MasterCard CDF file.
 

In v2, there is a new authorization field to help clients match their authorization record to the clearing record. "Clearing reference number" from the authorization event notification will provide a one to one match with the "banknet reference number" field from the clearing record.

Clearing reference number field is a concatenation of financial network code, banknet reference number and settlement date.

VCN Reconciliation

 

Mapping a clearing event to SVB Online Banking statement

Acquirer reference data from the CDF file (also included in the clearing webhook event) can be used to map a clearing record back to the SVB Online Banking portal statement.