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.

Virtual Card Object

Virtual card object contains all the information regarding a virtual card. 

NAME DESCRIPTION TYPE
 available_balance  The total value remaining on this card in integer cents.  integer
 authorizations  Authorizations data on this card as a list of authorization objects.  array
 card_number  Virtual card number.  string
 clearings  Clearing data on this card as a list of clearing objects.  array
 currency  Currency code the VCN is issued in  string
 cvc  Card verification code  string
 emails  A list of up to 5 email addresses that will be sent the virtual card details upon   creation.  array
 expiry  Card expiration date. In YYYY-MM format. Always two years after the VCN is created.

Note: Expiration takes place on the last day of the month, at 11:59:59 UTC midnight

 string
 id  Uniquely identifies each Virtual Card object.  string
 last4  The last 4 digits of the card number.  string
 mastercard_data   A json object of custom field names/value pairs, defined in MasterCard purchase   template  object
 metadata  A json object (up to 8K) of any optional user data.  object
 notified  True if an email was triggered to the addresses in emails, otherwise false.  boolean
 per_transaction_max  The maximum transaction value that can be made on this card in integer cents.  integer
 per_transaction_min  The minimum transaction value that can be made on this card in integer cents.  integer 
 rcn_id  Identifies the real card.   integer
 rcn_alias  The name of the real card.  string
 status

 Card status can either be "Approved" or "Canceled".

 Card status will be set   to Approved for valid cards.

 string
 supplier_id  Identifies the supplier.  integer
 template_id  A valid template_id which identifies the allowed or denied merchant category   codes that can be used with the VCN.  string
 total_card_amount  The maximum value of the card in integer cents.  integer
 transactions_max  The maximum number of times this card may be used.  integer
 valid_ending_on  Latest GMT date when this VCN can be used. In YYYY-MM-DD format.  string
 valid_starting_on  Earliest GMT date when this VCN can be used. In YYYY-MM-DD format.  string

 

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
curl "https://api.svb.com/v1/virtualcards" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
            "data": {
            "emails": [
            "email1@example.com",
            "email2@example.com"
             ],
            "mastercard_data": {
                   "Purchase Type": "Created by SVB API"
             },
            "metadata": {
            "purchase_number": "801b"
            },
            "per_transaction_max": 100000,
            "per_transaction_min": 1,
            "total_card_amount": 200000,
            "transactions_max": 10,
            "currency": "EUR",
            "valid_starting_on": "2020-12-25",
            "valid_ending_on": "2022-12-25",
            "recurring": "Continuous",
            "valid_for": 24
             },
            "show_card_number": true
        }'

Example Response

{
    "data": {
       "authorizations": [],
       "available_balance": 200000,
       "card_number": "5563380560023776",
       "clearings": [],
       "currency": "EUR",
       "cvc": "640",
       "emails": [
             "email1@example.com",
             "email2@example.com"
        ],
       "expiry": "2023-03",
       "id": "5112674",
       "last4": "3776",
       "mastercard_data": {
             "Purchase Type": "Created by SVB API"
        },
       "metadata": {
       "purchase_number": "801b"
       },
       "notified": true,
       "per_transaction_max": 100000,
       "per_transaction_min": 1,
       "rcn_alias": "Test Account 1",
       "rcn_id": 126507,
       "recurring": "Continuous",
       "status": "Approved",
       "supplier_id": 1734,
       "template_id": 113703,
       "total_card_amount": 200000,
       "transactions_max": 10,
       "type": "virtualcard",
       "url": "/v1/virtualcards/5112674",
       "valid_ending_on": "2022-12-25",
       "valid_starting_on": "2020-12-25"
      }
}

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 creationrecurring API request parameter can be specified with one of the below values to set the appropriate velocity control.
 

VELOCITY WINDOW
Continuous (default)
Daily
Weekly
Quarterly
Monthly
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

curl "https://api.svb.com/v1/virtualcards" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d ' {
            "data": {
                          "total_card_amount": 5,
                          "transactions_max": 6,
                          "valid_ending_on": "2020-01-05",
                          "recurring": "Daily"
                          }
        }'

 

Example Response

{
    "data": {
        "authorizations": [],
        "available_balance": 5,
        "card_number": "5563386070411111",
        "clearings": [],
        "currency": "USD",
        "cvc": "331",
        "emails": null,
        "expiry": "2021-09",
        "id": "1330344",
        "last4": "0111",
        "mastercard_data": {
            "Purchase Type": "Created by SVB API v0.16.700-ge9da98e"
        },
        "metadata": null,
        "notified": false,
        "per_transaction_max": 5,
        "per_transaction_min": 0,
        "rcn_alias": "Test Account 1",
        "rcn_id": 126507,
        "recurring": "Daily",
        "status": "Approved",
        "supplier_id": 1734,
        "total_card_amount": 5,
        "transactions_max": 6,
        "type": "virtualcard",
        "url": "/v1/virtualcards/1330344",
        "valid_ending_on": "2020-01-05",
        "valid_starting_on": "2019-09-23"
    }
 }

Aging Velocity - 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
 

Example of Aging Velocity - Authorization Hold Period Control
Example of Aging Velocity - Authorization Hold Period Control

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

{
  "data": {
      "total_card_amount": 19000,
      "valid_ending_on": "2021-12-25",
      "mastercard_data": {
           "Purchase Type": "Created by SVB API v0.16.1507-g7ee2570"
        },
       "metadata": {
       "purchase_number": "801b"
        },
       "template_id":24366,
       "authorization_hold_days": 1,
       "aging_velocity_time_zone": "PST"
       },
      "show_card_number": true
}

 

Example Response

{
    "data": {
        "aging_velocity_time_zone": "PST",
        "authorization_hold_days": 1,
        "authorizations": [],
        "available_balance": 19000,
        "card_number": "5563000000000000",
        "clearings": [],
        "currency": "USD",
        "cvc": "238",
        "emails": null,
        "expiry": "2023-05",
        "id": "5396300",
        "last4": "3309",
        "mastercard_data": {
            "Purchase Type": "Created by SVB API v0.16.1507-g7ee2570"
        },
        "metadata": {
            "purchase_number": "801b"
        },
        "notified": false,
        "per_transaction_max": 19000,
        "per_transaction_min": 0,
        "rcn_alias": "Test Account 1",
        "rcn_id": 126507,
        "recurring": null,
        "status": "Approved",
        "supplier_id": 1734,
        "template_id": 24366,
        "total_card_amount": 19000,
        "transactions_max": null,
        "type": "virtualcard",
        "url": "/v1/virtualcards/5396300",
        "valid_ending_on": "2021-12-25",
        "valid_starting_on": "2021-05-18"
    }
}

API Template Creation

Create a template endpoint can be used to create a purchase template through the SVB API. This endpoint can be used to create a template with specified list of MCCs and restrict a VCN to work with a predetermined set of MCCs.

This endpoint receives the request and responds with an acknowledgement but template creation is completed offline. Client is notified via a webhook when the new template is ready for use. 

Endpoint

POST /v1/content/virtualcard-templates

Arguments

NAME DESCRIPTION TYPE

name

required

 Name for the template to be created

string

mcc_list

required

 List of MCC codes

array

mcc_rule

required

 Specifies if the MCC codes provided should be allowed or rejected.

 Available values: "ALLOW" or "DENY"

string

description

required

 Description of the new purchase template

string

required_control

required

 Specifies the type of the template to be used. Available values:

 "VELOCITY" or "AGING_VELOCITY"

string

 

Example request

 

curl --request POST 'https://api.svb.com/v1/content/virtualcard-templates' \
--header 'Authorization: Bearer test_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw'{
      "description": "sample API template",
      "mcc_list": ["5599"],
      "mcc_rule": "ALLOW",
      "name": "API template 1",
      "required_control": "VELOCITY"
}'

 

Example response

{
    "copy_from_template": "Original Template 1",   
    "customer_number": "4299",
    "description": "sample API template",
    "links": [
   {
  "href": "/v1/content/virtualcard-templates?filter[transaction_key]=1451111-11c4-11ec-11e1-0a580a111111",

   "method": "GET",
   "rel": "self"
    }    ],

    "mcc_list": ["5599"],
    "mcc_rule": "ALLOW",
    "name": "API template 1",
    "required_control": "VELOCITY",
    "status": "PENDING",
    "transaction_key": "1451111-11c4-11ec-11e1-0a580a111111"

}

Note: href response parameter can be used to query for transaction status and request details.

Retrieving status and details of requested template

/v1/content/virtualcard-templates endpoint can be queried with the transaction_key to retrieve template creation status.

Initially the status will be "PENDING" and once the template creation completes, status will change to "ACTIVE". 

Example response

{
    "data": [
        {
            "company_id": 111222,
            "copy_from_template": "API Template",
            "created_at": "2022-01-06T23:32:13.566Z",
            "deleted_at": null,
            "description": "PurchaseTemplateE2ETest3",
            "environment": "live",
            "id": 1000,
            "identity": null,
            "links": [
                {
                    "href": "/v1/content/virtualcard-templates?filter[transaction_key]=827f59e0-8a00-11ec-9c7b-0a580a1e0a27",
                    "method": "GET",
                    "rel": "self"
                }
            ],
            "mcc_list": [
                "3412"
            ],
            "mcc_rule": "ALLOW",
            "name": "Bot_E2E_Test3_0106",
            "required_control": "VELOCITY",
            "status": "PENDING",
            "transaction_key": "123d59e0-8a00-44ec-9c7b-0a580a1e0a27",
            "updated_at": "2022-01-06T23:32:13.566Z"
        }
    ],
    "links": {
        "first": "/v1/content/virtualcard-templates?page[limit]=100&filter[transaction_key]=827f59e0-8a00-11ec-9c7b-0a580a1e0a27",
        "next": null
    }
}

Clients can also subscribe to the webhook event for template creation (id 11) and receive an update when the template creation completes. More information can be found on VCN Webhooks section.

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.

Recon

 

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 to SVB Online Banking portal statement.