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

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"
      }
}

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.
 

* 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 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:
 

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"
    }
}

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

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.

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.

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.