Table of Contents
Overview and Key Features
A virtual card is a unique & digitally generated 16-digit credit card number. Virtual card cardholders greater control on how and when their account is being used by utilizing a Virtual Card Number with personalized transaction controls and alerts.
The VCN API can be used to:
- Create Virtual Card Numbers
- Set controls on how much can be spent per virtual card
- Retrieve a list of all virtual cars created
- Cancel a virtual card from being used from future purchases with a merchant
- Make updates to controls for a virtual card
- Retrieve a list of all authorizations and clearings
Authorized users at your company can also log in to SVB's SmartData card portal to view the VCNs that your company has created, view transaction activity, update your virtual card program, and even create VCNs.
While you can create and update VCNs via this web interface, we recommend doing so primarily through the API. VCNs created on the website are not viewable through the API, and any updates made on the website to VCNs that were created on the API will not be reflected in the API.
For more information on Virtual Cards, including the SmartData card portal, please visit SVB Learning Central.
Postman Collection with examples
Key Features
- API allows for instant issuance of a VCN, eliminating the wait time for a real card
- Virtual card controls allow for usage within limits per user
- Currency Control
- Velocity Control
- Aging-Velocity Control
- Reconcile transactions
- Fraud mitigation is enabled as it avoids sending real card details to online merchants
Example Use Case
Instead of using a single card for all customer orders, a company can embed virtual card capabilities into their platform so that whenever they place an order, their platform automatically calls SVB’s API in real time to support their customer purchases. This also allows them to know which transactions relate to which customer, allowing for better reconciliation, efficiency in their customer experience workflow and reduced risk and exposure to fraud.
Dependencies and restrictions
- Real card program required
- Supplier ID required during onboarding
- Template required during onboarding
- Direct channel integration, does not require SVB Go company ID/user ID
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.