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.
Table of Contents
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 specified as a non-USD value in the request body.
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
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
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
Example Response
VCN Reconciliation
There are two main reconciliation use cases for SVB VCN API clients:
- Mapping an authorization event to the clearing event
- Mapping a clearing event to SVB Online Banking statement
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.
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.