Learning Central

Client Services

North America

clientsupport@svb.com
1.800.774.7390 
5:00 AM – 5:30 PM PT M-F

United Kingdom

ukclientservice@svb.com
0800.023.1441 | +44.207.367.7881
8:00 AM – 1:30 AM GMT

SVB PPP Care Team

SVBPPPCare@svb.com
1.833.450.5444
5:00 AM – 5:30 PM PT M-F


Contact the SVB PPP Care Team
for all PPP application questions or
view instructions here.


Bill Pay Classic

1.866.321.6563
4:30 AM PT - 11:00 PM PT M-F

Card Services

Cards Issued in the U.S.

cardservices@svb.com
1.866.553.3481
001.408.654.1039 (international)

Cards Issued in the UK
Support, lost, or stolen

0800.023.1062
+44.0.207.367.7852 (international)

Elite Cards

1.866.940.5920 | 408.654.7720

Lost or Stolen Cards

1.844.274.0771
001.408.654.1039 (international)

FX Trade Desk

North America

1.888.313.4029
IntFXT@svb.com
5:00 AM PT – 4:00 PM PT

United Kingdom

+1.44.0.207.367.7880
ukfxtraders@svb.com
8:00 AM BST – 5:OO PM BST

SVB Asset Management

1.866.719.9117
samoperations@svb.com

SVB Cash Sweep

1.800.774.7390 
clientservice@svb.com

More Support Contacts

Virtual Cards

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.

 

The Virtual Card Object with Realtime Authorizations

Virtual Card Object with Realtime Authorizations encapsulate the details, real-time authorizations, and clearing information in addition to the card number for an individual VCN.

Attributes 

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 (see below) array
card_number The card number. string
clearings Clearing data on this card as a list of clearing objects (see below) array
currency The currency code the VCN is issued in string
cvc A short 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. 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 Will be 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

 

Example virtualcard object

{
    "available_balance": 9897,
    "authorizations": [{
      "acquirer_ica": "001285",
      "approval_code": "050201",
      "billing_amount": 2450,
      "billing_currency": "USD",
      "issuer_response": "Approved",
      "mcc": "1750",
      "mcc_description": "EATING PLACES, RESTAURANTS",
      "merchant_amount": 2450,
      "merchant_currency": "USD",
      "merchant_id": "4445028900333",
      "merchant_name": "GOOD EATS",
      "transaction_date_time": "2018-10-31T00:13:32.000Z",
      "transaction_type": "Authorization Advice",
      "vcn_response":"Valid"
    }],
    "card_number": "5563382306181964",
    "clearings": [{
"acquirer_ica": "001285",
"approval_code": "050201",
"authorization_date": "2018-10-31T00:00:00.000Z", "billing_amount": 2450, "billing_currency": "USD",
"clearing_type": "Debit", "exchange_rate": "1.000000", "mcc": "1750", "mcc_description": "EATING PLACES, RESTAURANTS", "merchant_amount": 2450, "merchant_currency": "USD", "merchant_id": "4445028900333", "merchant_name": "GOOD EATS", "settlement_date": "2015-11-09T00:00:00.000" }], "currency": "USD", "cvc": "878", "emails": null, "expiry": "2017-10", "id": "87256", "last4": "1964", "mastercard_data": { "Reference": "123" }, "metadata": { "purchase_number": "801b" }, "per_transaction_max": 1000, "per_transaction_min": 0, "rcn_id": 87282, "rcn_alias": "Account 1", "status": "Approved", "supplier_id": 1826,
"template_id": 12345, "total_card_amount": "12345", "transactions_max": 10, "valid_ending_on": "2015-12-25", "valid_starting_on": "2015-10-07" }


Authorization Objects

Authorization data appears in the authorizations key of virtual card responses. The authorization data fields below will return in the response when the show_realtime_auths argument is set to true.  In this case the authorization data is refreshed in near realtime.   

NAME DESCRIPTION TYPE
acquirer_ica ID representing an acquiring bank.  string
approval_code Short code issued to the merchant when a transaction is approved (but null when declined). string
billing_amount Amount billed in integer cents. integer
billing_currency Currency of amount to be billed (e.g. “USD”). string
issuer_response String description of issuer response.  Examples: "Approved", "Decline - Do not honor", "Decline - Insufficient funds/over credit limit", "Decline - Expired Card", "System error". string
mcc Merchant category code (e.g. “1750”). string
mcc_description Human-readable merchant category (e.g. “CARPENTRY CONTRACTORS”). string
merchant_amount Amount merchant authorized in integral cents. integer
merchant_currency Currency of amount authorized (e.g. “USD”). string
merchant_id Unique ID representing merchant. string
merchant_name Human-readable merchant name string
transaction_date_time Date and time of the authorization of the transaction - set by the system automatically. string
transaction_type Type of transaction submitted, most commonly "Authorization Advice" string
vcn_response Indicates if the transaction is valid, or the reason for the decline.  To be used alongside issuer_response.   string


Clearing Objects

Clearing information appears in the clearings key of virtual card responses. Clearings appear when transactions are settled, generally several days after a transaction is authorized.

Billing amount in the clearing object is the amount in your card’s billing currency (USD) of the transaction. Settlement amount in the clearing object is the amount in your card’s billing currency (USD) of the transaction plus any fees assessed on top of the transaction (e.g. a foreign transcation fee). For USD transactions, the merchant amount and billing amount should be the same.

The settlement date is the same as the transaction date and they both reflect the date as to which MasterCard processes the record from clearing.

NAME DESCRIPTION TYPE
acquirer_ica ID representing an acquiring bank.  string
approval_code Short code issued to the merchant when a transaction is approved (but null when declined). string
authorization_date Date the transaction is authorized. string
billing_amount Amount billed in integer cents. integer
billing_currency Currency of amount billed (e.g. “USD”). string
clearing_type Indicates if the transaction is a debit (purchase) or a credit (return or reversal transaction). string
exchange_rate Exchange rate used for the transaction. string
mcc Merchant category code (e.g. “1750”). string
mcc_description Human-readable merchant category (e.g. “CARPENTRY CONTRACTORS”). string
merchant_amount Amount merchant authorized in integral cents. integer
merchant_currency Currency of amount authorized (e.g. “USD”). string
merchant_id Unique ID representing merchant. string
merchant_name Human-readable merchant name string
settlement_date Date of settlement in YYYY-MM-DD format. string



Create a Virtual Card

Creates a new virtual card.

Endpoint

POST /v1/virtualcards

Arguments

Parameters inside the data object (see example):

NAME DESCRIPTION TYPE DEFAULT
emails A list of up to 5 email addresses that will be sent virtual card details. array null
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 {}
per_transaction_max The maximum transaction value that can be made on this card in integer cents. integer null
per_transaction_min The minimum transaction value that can be made on this card in integer cents. integer null
rcn_id The ID of a real card to use integer null
rcn_alias The alias name of a real card to use (must match rcn_id) string null
supplier_id The ID of the supplier integer null
template_id The id of the template which can be pulled from the /v1/templates list.

Note: In the templates call, the id is returned as a string, but this POST will also accept an int.
string null
total_card_amount The maximum value of the card in integer cents. integer required
transactions_max The maximum number of times this card may be used. integer 1000
valid_ending_on Latest GMT date when this VCN can be used. In YYYY-MM-DD format. string required
valid_starting_on Earliest GMT date when this VCN can be used. In YYYY-MM-DD format. string yesterday
valid_for

Any integer between 1 and 24 which represents the number of months from current month to calculate the expiration date of the virtual card.  

Integer 24

 

 

Top level parameters:

NAME DESCRIPTION TYPE DEFAULT
show_card_number If true, show the card number. If false, null will be returned instead. boolean true


 

Important: There is a distinction between the mastercard_data and metadata fields: 

metadata is a map of client-provided string data that enables clients to fetch and filter virtual cards based additional fields. These fields are never sent to MasterCard, but they exist to ease integration with the SVB API. This field can contain up to 8000 characters. 

mastercard_data fields are sent to MasterCard as “Custom Data Fields”, and they must be defined as part of the VCN template in the SmartData UI prior to use. These values have a max length of 80 characters. This set of data is then accessible via SmartData or CDF feeds.

 

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": 12345,
            "emails": [
              "email1@example.com",
              "email2@example.com"
            ],
            "transactions_max": 10,
            "valid_ending_on": "2015-12-25",
            "mastercard_data": {
              "Reference": "123"
            },
            "metadata": {
              "purchase_number": "801b"
            },
            "rcn_id": 87282,
            "rcn_alias": "Account 1",
            "supplier_id": 1826
          },
          "show_card_number": true
        }'

Example response

{
  "data": {
    "available_balance": 12345,
    "authorizations": [],
    "card_number": "5563382306181964",
    "clearings": [],
    "currency": "USD",
    "cvc": "878",
    "emails": [
      "email1@example.com",
      "email2@example.com"
    ],
    "expiry": "2017-10",
    "id": "87256",
    "last4": "1964",
    "mastercard_data": {
      "Reference": "123"
    },
    "metadata": {
      "purchase_number": "801b"
    },
    "notified": true,
    "per_transaction_max": null,
    "per_transaction_min": 0,
    "rcn_id": 87282,
    "rcn_alias": "Account 1",
    "status": "Approved",
    "supplier_id": 1826,
    "total_card_amount": 12345,
    "transactions_max": 10,
    "url": "/v1/virtualcards/87256",
    "valid_ending_on": "2015-12-25",
    "valid_starting_on": "2015-10-07"
  }
}

Optional Top level parameters:

Velocity Control parameters:

Optional parameter which refreshes the availability of funds on the VCN on a periodic basis, at midnight UTC time zone / 5:00 pm Pacific.  By default, all VCNs use the “Continuous” value for this field if no value is provided (meaning there is no refresh).

NAME

DESCRIPTION

TYPE

DEFAULT

recurring

One of these values (case sensitive):

Daily, Weekly, Quarterly, Monthly, Yearly, Continuous

string

Continuous

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



Error Messages on Create 

CODE ERROR MESSAGE DESCRIPTION
400

Invalid value passed for 'total_card_amount'.

Value must be positive integral cents

Only positive integers (not decimals) are permitted for monetary amounts.
400

Invalid value passed for 'valid_ending_on' (20160524).

Value must be in 'YYYY-MM-DD' format.

Date fields expect strings to be formatted as YYYY-MM-DD.
400 'total_card_amount' must be greater than 0. The VCN card limit needs to be greater than 0 to be valid.
400 'per_transaction_max' must be greater than 0. The limit per-transaction needs to be greater than 0.
400

'per_transaction_min' cannot be greater

than 'per_transaction_max'.

If the minimum is greater than the maximum amount, the VCN will be unusable.
400

'per_transaction_max' cannot be greater

than 'total_card_amount'.

Similarly, a card’s transaction max should not exceed the total card limit.
400

'total_card_amount' cannot be greater

than configured card max.

A company’s max single card amount (configured by an admin user via max_card_amount) cannot be exceeded.
400 EUR is not a supported currency Currently, the API only supports “USD” amounts.
400 Missing 'valid_ending_on'. The valid_ending_on field cannot be null or empty.
400 'valid_ending_on' ("2015-05-04") can not be in the past. A card must expire in the future.
400

'valid_ending_on' ("2016-06-01")

must occur after 'valid_starting_on' ("2016-06-02").

A card cannot expire before it’s valid start date.
400 'transactions_max' must be greater than or equal to 0. A card must be limited to a positive number of transactions.
400

Missing required virtualcard fields:

'total_card_amount', 'valid_ending_on'

A field required to create a VCN was not found in the request.
400

One of the required Custom Data Fields

was missing from the request

mastercard_data did not include a custom field as required by the MasterCard purchase template.
400

Unsupported custom field name 'Alpha80'

passed for 'mastercard_data

A custom fields passed to MasterCard was not defined in the MasterCard purchase template.
400 'emails' must contain 5 or fewer email addresses. Up to 5 string email addresses may be provided when creating a new VCN.
400

Invalid value passed for 'mastercard_data'.

All keys and values must be strings.

Currently, the API requires the JSON object to contain both string keys and values.
400

The Alias entered was not found

for the specified company

The rcn_alias did not match any real cards available to the company.
400 The RCN Data is invalid Both rcn_alias or rcn_id of the real card should match and be valid.
400

There was a problem getting the template detail for the 
template ID submitted

A valid template id retrieved from the Templates list call must be used

Retrieve a Virtual Card

Retrieves a virtual card that has been previously created. Use the unique ID returned from the previous request to identify which virtual cards to retrieve. 

Note the following:

  • card_number returns null when show_card_number is not set to true.
  • Authorizations data is only available on a realtime basis if show_realtime_auths is set to true (it defaults to false).  
  • There are minor variations in the response data fields between realtime authoriation data and non-realtime data.  See the sections on the Virtual Card Object with Non-Realtime Auth Data and Virtual Card Object with Realtime Auth Data.  
  • To print a virtual card number along with real-time authorizations, pass both the parameters like this: GET /v1/virtualcards/:id?show_realtime_auths=true&show_card_number=true

    Important:
    The non-realtime authorization object will be deprecated in an upcoming 2018 release.  Once deprecated, the show_realtime_auths flag will no longer be required and will always be interpreted as true.

  • If you want to receive ONLY the card information, i.e. all attributes except authorizations or clearings, use the "prefer" header with the value "return-minimal".  

Endpoint

  • GET /v1/virtualcards/:id (will include authorizations data but not from a realtime data source)
  • GET /v1/virtualcards/:id?show_realtime_auths=true (will include the latest authorizations data in near realtime)
  • GET /v1/virtualcards/:id/clearings (will include only the "clearings" field)
  • GET /v1/virtualcards/:id/authorizations (will only include the "authorizations" field)

Arguments


NAME DESCRIPTION TYPE DEFAULT
id The ID of the VCN to be retrieved. string required
show_card_number If true, show the card number. query parameter that is "true" or "false" "false"  
show_realtime_auths If true, use the realtime authorizations data source. query parameter that is "true" or "false" "false"  

 

Example request

curl "https://api.svb.com/v1/virtualcards/87256" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response with authorizations data from a realtime data source.  

{
  "data": {
    "available_balance": 11345,
    "authorizations": [{
      "acquirer_id": "002347",
"approval_code": "042203",
"billing_amount": 1000, "billing_currency": "USD", "issuer_response": "Approved", "mcc": "1750", "mcc_description": "CARPENTRY CONTRACTORS", "merchant_amount": 1000, "merchant_currency": "USD", "merchant_id": "527636600321718", "merchant_name": "ABC CONTRACTING",
"transaction_date_time": "2018-11-08T00:02:32.000Z", "transaction_type": "Authorization Advice",
"vcn_response": "Valid" }], "card_number": null, "clearings": [{ "acquirer_id": "002347",
"approval_code": "042203",
"authorization_date": "2018-11-08T00:00:00.000Z",
"billing_amount": 1000, "billing_currency": "USD", "clearing_type": "debit", "exchange_rate": "1.000000", "mcc": "1750", "mcc_description": "CARPENTRY CONTRACTORS", "merchant_amount": 1000, "merchant_currency": "USD", "merchant_id": "527636600321718", "merchant_name": "ABC CONTRACTING", "settlement_date": "2018-11-09T00:00:00.000Z" }], "currency": "USD", "cvc": "288", "emails": null, "expiry": "2017-10", "id": "87282", "last4": "6319", "mastercard_data": { "Reference": "123" }, "metadata": { "purchase_number": "801b" }, "notified": false, "per_transaction_min": null, "per_transaction_max": 12345, "rcn_id": 87282, "rcn_alias": "Account 1", "status": "Approved", "supplier_id": 1826, "total_card_amount": 12345, "transactions_max": 10, "url": "/v1/virtualcards/87282", "valid_ending_on": "2015-12-25", "valid_starting_on": "2015-10-07" } }
 

Example response with return-minimal header  

{
  "data": {
    "available_balance": 11345,
    "card_number": null,
    "currency": "USD",
    "cvc": "288",
    "emails": null,
    "expiry": "2017-10",
    "id": "87282",
    "last4": "6319",
    "mastercard_data": {
      "Reference": "123"
    },
    "metadata": {
      "purchase_number": "801b"
    },
    "notified": false,
    "per_transaction_min": null,
    "per_transaction_max": 12345,
    "rcn_id": 87282,
    "rcn_alias": "Account 1",
    "status": "Approved",
    "supplier_id": 1826,
    "total_card_amount": 12345,
    "transactions_max": 10,
    "url": "/v1/virtualcards/87282",
    "valid_ending_on": "2015-12-25",
    "valid_starting_on": "2015-10-07"
  }
} 

Example response with only authorizations  

{
    "data": {
        "authorizations": [
            {
                "acquirer_ica""001113",
                "approval_code""020936",
                "billing_amount"145,
                "billing_currency""XAU",
                "issuer_response""Decline - Invalid amount",
                "mcc""2060",
                "mcc_description""MUSIC TECHNOLOGY",
                "merchant_amount"145,
                "merchant_currency""XAU",
                "merchant_id""242661000000002",
                "merchant_name""Test Company 4",
                "transaction_date_time""2020-08-02T06:00:11.000Z",
                "transaction_type""Authorization Advice Response",
                "vcn_response""Valid"
            },
            {
                "acquirer_ica""001113",
                "approval_code""020936",
                "billing_amount"145,
                "billing_currency""XAU",
                "issuer_response""Decline - Invalid amount",
                "mcc""2060",
                "mcc_description""WEARABLE TECHNOLOGY",
                "merchant_amount"145,
                "merchant_currency""XAU",
                "merchant_id""242661000000002",
                "merchant_name""Test Company 3",
                "transaction_date_time""2020-08-02T06:00:11.000Z",
                "transaction_type""Authorization Advice",
                "vcn_response""Valid"
            }

        ],
        "links": {
            "first""/v1/virtualcards/3088364/authorizations?&page[limit]=100",
            "next"null
        }
    }
}

Example response with only clearings  

{
    "data": {
        "clearings": [
            {
                "acquirer_ica""10099",
                "approval_code""008806",
                "authorization_date""2018-11-08T00:00:00.000Z",
                "billing_amount"31600,
                "billing_currency""USD",
                "clearing_type""Debit",
                "exchange_rate""1.000000",
                "mcc""7922",
                "mcc_description""THEATRICAL PRODUCERS(EXCL MOTION PIX),TICKET AGNCY",
                "merchant_amount"31600,
                "merchant_currency""USD",
                "merchant_id""313023853887",
                "merchant_name""BROADWAY INBOUND",
                "settlement_date""2018-11-09T00:00:00.000Z"
            },
            {
                "acquirer_ica""10099",
                "approval_code""008532",
                "authorization_date""2018-11-08T00:00:00.000Z",
                "billing_amount"21800,
                "billing_currency""USD",
                "clearing_type""Debit",
                "exchange_rate""1.000000",
                "mcc""7922",
                "mcc_description""THEATRICAL PRODUCERS(EXCL MOTION PIX),TICKET AGNCY",
                "merchant_amount"21800,
                "merchant_currency""USD",
                "merchant_id""313023853887",
                "merchant_name""BROADWAY INBOUND",
                "settlement_date""2018-11-09T00:00:00.000Z"
            }
       ]
   }
}

Example response with authorizations from a non-realtime data source.  (To be deprecated.)

{
  "data": {
    "available_balance": 11345,
    "authorizations": [{
      "acquirer_ica": "003286",
      "approval_code": "030202",
      "billing_amount": 1000,
      "billing_currency": "USD",
      "date": "2015-11-07",
      "issuer_response": "Approved",
      "mcc": "1750",
      "mcc_description": "CARPENTRY CONTRACTORS",
      "merchant_amount": 1000,
      "merchant_currency": "USD",
      "merchant_id": "527636600321718",
      "merchant_name": "B & B TOWING",
      "transaction_date_time": "2018-05-01T00:13:32.000Z",
      "transaction_type": "Authorization Advice",
      "vcn_response": "Valid"
    }],
    "card_number": null,
    "clearings": [{
      "billing_amount": 1000,
      "billing_currency": "USD",
      "clearing_type": "debit",
      "exchange_rate": "1",
      "date": "2015-11-09",
      "mcc": "1750",
      "mcc_description": "CARPENTRY CONTRACTORS",
      "merchant_amount": 1000,
      "merchant_currency": "USD",
      "merchant_id": "527636600321718",
      "merchant_name": "MERCHANT NAME",
      "settlement_amount": 1000,
      "settlement_currency": "USD",
      "settlement_date": "2015-11-09" 
    }],
    "currency": "USD",
    "cvc": "288",
    "emails": null,
    "expiry": "2017-10",
    "id": "87282",
    "last4": "6319",
    "mastercard_data": {
      "Reference": "123"
    },
    "metadata": {
      "purchase_number": "801b"
    },
    "notified": false,
    "per_transaction_min": null,
    "per_transaction_max": 12345,
    "rcn_id": 87282,
    "rcn_alias": "Account 1",
    "status": "Approved",
    "supplier_id": 1826,
    "total_card_amount": 12345,
    "transactions_max": 10,
    "url": "/v1/virtualcards/87282",
    "valid_ending_on": "2015-12-25",
    "valid_starting_on": "2015-10-07"
  }
}

Authorization Specific Filtering and Paging

For the card retrieval of authorizations only: GET /v1/virtualcards/:id/authorizations

Conventional paging is available
Filtering is also available for the following fields:

Field Name Extra Notes
billing_amount  
issuer_response  
vcn_response  
acquirer_ica  
mcc  
transaction_type  
merchant_id  
transaction_date_time Note that for "start" and "end" you can provide in either date or in datetime format.  If you only a date is provided, it is automatically converted to a datetime value where the time value is defaulted to 00:00:00.000Z of that day.  If you want a single day, however, you can set "start" and "end" to the same day.
billing_currency  
mcc_description allows partial match and is not case-sensitive
merchant_amount  
merchant_name allows partial match and is not case-sensitive
approval_code  

Error Messages related to Authorization Filters

CODE SAMPLE ERROR MESSAGE DESCRIPTION
400

invalid filter value '213X' for filter 'billing_amount': must contain only digits 0-9

Billing Amount are the values of the lowest common denominator, which in this case is cents
400

invalid filter key 'mcce': not a valid filter for this endpoint

Only the listed filters that can be used will be tried. 
400

invalid filter value '21$X$' for filter 'mcc': must contain only digits 0-9

MCC codes are a 4 digit value
400

invalid filter value '21$X$' for filter 'merchant_id' should only contain alphanumeric characters

Merchant_id must be alphanumeric
400

invalid filter value '213X' for filter 'merchant_amount': must contain only digits 0-9

Merchant Amount must be in cents
400

invalid filter value 'QDSF!2%@' for filter 'acquirer_ica' should only contain alphanumeric characters

Acquirer_ica must be an alphanumeric character
400

invalid filter value 'Approved!' for filter 'issuer_response': should only contain alphanumeric characters

Issuer_response is a set enum as listed in the vcn realtime authorization event type in the VCN Webhooks section below 
400

invalid filter value '211$!3X' for filter 'approval_code' should only contain alphanumeric characters

Approval_code must be an alphanumeric character
400

invalid filter value '234' for filter 'billing_currency': should only contain alpha characters

Billing_currency will be USD
400

invalid filter value '2asd341$!' for filter 'merchant_currency': should only contain alpha characters

Merchant_currency will be USD
400

End date cannot be before start date

For both transaction_date_time the start has to be before or the same as the end


Clearings Specific 
Filtering and Paging

For the card retrieval of authorizations only: GET /v1/virtualcards/:id/clearings

Conventional paging is available
Filtering is also available for the following fields:

Field Name Extra Notes
acquirer_ica  
approval_code  
authorization_date Note that for "start" and "end" you can provide in either date or in datetime format.  If you only a date is provided, it is automatically converted to a datetime value where the time value is defaulted to 00:00:00.000Z of that day.  If you want a single day, however, you can set "start" and "end" to the same day.
billing_amount  
clearing_type This filter is case-sensitive
exchange_rate  
mcc  
mcc_description Allows partial match and is not case-sensitive
merchant_amount  
merchant_currency This filter is case-sensitive
merchant_id  
merchant_name Allows partial match and is not case-sensitive
settlement_date Note that for "start" and "end" you can provide in either date or in datetime format.  If you only a date is provided, it is automatically converted to a datetime value where the time value is defaulted to 00:00:00.000Z of that day.  If you want a single day, however, you can set "start" and "end" to the same day.
billing_currency This filter is case-sensitive



 

Cancel a Virtual Card

Cancel a virtual card you’ve previously created.

Cancelling a virtual card prevents that card from being used for future purchases with a merchant. Cancelling a virtual card does not stop any in-progress transactions in which a merchant has an authorization from clearing and settling. A cancelled VCN will also continue to accept return/refund transactions.

This endpoint doesn’t return a body, but instead returns a HTTP Status Code 204 (No Content).

Endpoint

DELETE /v1/virtualcards/:id

Arguments

NAME DESCRIPTION TYPE DEFAULT
id The ID of the VCN to be deleted. string required

 

Example request

curl "https://api.svb.com/v1/virtualcards/87256" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -X DELETE

Example response

 

 

Update a Virtual Card

Updates a virtual card that has been previously created and returns the updated Virtual Card.

Use the unique ID returned from the previous request to identify which virtual cards to update. Takes the same parameters as the Create endpoint.

Endpoint

PATCH /v1/virtualcards/:id

 

URL Parameters

NAME DESCRIPTION TYPE DEFAULT
id The ID of the VCN to be updated. string required
show_card_number If true, show the card number. query parameter that is "true" or "false" "false"

 

 

PATCH Parameters

All fields are optional when updating a virtual card. For values that are not passed, the original virtual card value will be preserved.

NAME DESCRIPTION TYPE
emails A list of up to 5 email addresses that will be sent virtual card details. array
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
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
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
valid_for

Any integer between 1 and 24 which represents the number of months from current month to calculate the expiration date of the virtual card.  

Revalidation: Upon update, all existing fields will be re-validated and you should collect updated values, most critically, the CVC code which is calculated using the expiration date.

CVC change: The month is relative to the call month. The CVC is tied to the card # and month of expiration.  If you do not want the CVC to change, you need to ensure that the valid_for is calculated so that the expiration remains the same.

Continuous Extension: You can continuously update the expiration even beyond the RCN expiration date.  However, it is the expectation that this will be caught on the company side to ensure that the underlying RCN is not expired. 
 


Error Messages on Update

Same as  Creating a VCN errors but also including:

CODE ERROR MESSAGE DESCRIPTION
400

The template id is not editable

Once a template id is attached to a VCN you cannot remove or edit it.  The proper action to take is to delete the VCN and create a new one.




Example request

curl \
  "https://api.svb.com/v1/virtualcards/87256" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{
        "data": {
          "total_card_amount": 23456,
          "transactions_max": 5
        }
      }'

Example response

{
  "data": {
    "available_balance": 23456,
    "authorizations": [],
    "card_number": null,
    "clearings": [],
    "currency": "USD",
    "cvc": "288",
    "emails": [
      "email1@example.com",
      "email2@example.com"
    ],
    "expiry": "2017-10",
    "id": "87282",
    "last4": "6319",
    "mastercard_data": {
      "Reference": "123"
    },
    "metadata": {
      "purchase_number": "801b"
    },
    "notified": true,
    "per_transaction_min": null,
    "per_transaction_max": 12345,
    "rcn_id": 87282,
    "rcn_alias": "Account 1",
    "status": "Approved",
    "supplier_id": 1826,
    "total_card_amount": 12345,
    "transactions_max": 5,
    "url": "/v1/virtualcards/87282",
    "valid_ending_on": "2015-12-25",
    "valid_starting_on": "2015-10-07"
  }
} 

List all Virtual Cards

Retrieves a list of virtual cards you’ve previously created in creation order. This call returns a single page of data.

  • Paging is available for this endpoint
  • Filtering is available for this endpoint
    • The results can be filtered by matching fields in the metadata portion of the virtual card.
    • To filter, use the the filter[metadata.key]=value parameter. Themetadata. portion is a required literal string, key is the name of the sub field in metadata, and value is the string to match.
    • For example, to find all virtual cards with a certainpurchase_number use the endpoint
      /v1/virtualcards?filter[metadata.purchase_number]=801b
    • See the Virtualcard Object description for more information on the metadata field.

 

Result object

NAME SUB-FIELD DESCRIPTION TYPE
data   An array of references to Virtual Cards array of objects
  id The id of a Virtual Card string
  type Always "virtualcard" string
  url A url to a Virtual Card string
links   Navigation links for pagination object
  first A url to the first page of data string
  next A url to the next page of data string

 

Endpoint

GET /v1/virtualcards

 

Arguments

NAME DESCRIPTION TYPE
page[cursor] The id of the first element to return on this page. Defaults to the most recent id. string
page[limit] How many Virtual Card references to return. Defaults to 10000. Max 10000. integer
filter[metadata.key] Filter the result by matching the value of key in the metadata object. string

 

Note that these arguments are all optional.

 


Error Messages on Retrieval

CODE ERROR MESSAGE DESCRIPTION
400 Badly formatted filter Filters should be passed as an array, e.g. filter[metadata.keyname]
400

filter key 'badfilter':

Must be a string starting with 'metadata.'

Currently, the API only supports filtering on metadata keys.
400

filter key '123':

Must be a string value

Filters should use the format filter[

 

 

Example request

curl "https://api.svb.com/v1/virtualcards" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "87282",
      "type": "virtualcard",
      "url": "/v1/virtualcards/87282"
    },
    {
      "id": "87284",
      "type": "virtualcard",
      "url": "/v1/virtualcards/87284"
    }
  ],
  "links": {
    "first": "/v1/virtualcards",
    "next": "/v1/virtualcards?page[cursor]=87285"
  }
} 

Send an email about a Virtual Card

Send a single email with the virtual card details. May be called multiple times to send multiple emails.

Result object

We return a tracking UUID. The UUID is used as an internal debugging tool. If you do neeed help debugging, please contact SVB for assistance.

NAME DESCRIPTION TYPE
id Tracking UUID string

 

Since it can take many seconds to send the email, we return an HTTP Status Code 202 (Accepted) and send the email asynchronously.

 

Endpoint

POST /v1/virtualcards/:id/email

 

Arguments

URL Parameters:

NAME DESCRIPTION TYPE
id The ID of the VCN to be sent. Required string

 

 

POST Parameters:

NAME DESCRIPTION TYPE
email The email address that will be sent the virtual card details. Required string

 


Error Messages while Sending Email

CODE ERROR MESSAGE DESCRIPTION
400 Missing required field 'email' A field required to trigger an email was not found in the request.
400 Invalid email address: 'address' A value was passed for an email that does not appear to be a valid email address.

 

 

Example request

curl \
  "https://api.svb.com/v1/virtualcards/87256/email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
        "data": {
          "email": "email@example.com"
        }
      }'

Example response

{
  "id": "cf8f0a50-f258-11e5-8bd4-66ed8567d523"
} 

VCN Webhooks

VCN Webhook event types and payloads are listed here.

Events

The following events can be tracked using webhooks.

TYPE DESCRIPTION
virtualcard.created Triggered when a new virtual card is created.
virtualcard.realtime.auths Triggered when a virtual card authorization is received.
virtualcard.clearings Triggered when a virtual card clearing is received.

 

Example virtualcard.created webhook payload:

{
  "data": {
    "date": "2017-08-21T16:34:26.330Z",
    "event-id": 101,
    "payload": {
      "id": 123,
      "available_balance": 123445,
      "currency": "USD",
      "per_transaction_max": 123445,
      "per_transaction_min": 0,
      "rcn_id": 123456,
      "rcn_alias": "Test Account 1",
      "recurring": null,
      "status": "Approved",
      "transactions_max": 1,
      "total_card_amount": 123445,
      "valid_starting_on": "2017-08-27",
      "valid_ending_on": "2017-08-29"
    },
    "previous": null,
    "type": "virtualcard.created"
  }
}

VCN Realtime Authorization Event Type

When a VCN transaction is authorized, that event can be tracked using webhooks.

 

Sample response for the "virtualcard.realtime.auths" event type:

{
      "acquirer_ica": "001285",
      "approval_code": "050201",
      "billing_amount": 2450,
      "billing_currency": "USD",
"card_number": 556338######4001, "issuer_response": "Approved", "mcc": "1750", "mcc_description": "EATING PLACES, RESTAURANTS", "merchant_amount": 2450, "merchant_currency": "USD", "merchant_id": "4445028900333", "merchant_name": "GOOD EATS", "transaction_date_time": "2018-10-31T00:13:32.000Z", "transaction_type": "Authorization Advice",
"vcn_id": 15656669,
"vcn_response": "Valid"
}

Possible Values for issuer_response

Possible Values for vcn_response

Approved

Valid

Refer to card issuer

Decline - VCN’s expiration date does not match merchant input

Decline - Invalid merchant

Decline - VCN is expired

Capture Card

Decline - VCN’s CVC does not match merchant input

Decline - Do not honor

Decline - valid_starting_on or valid_ending_on

Approved - Honor with ID

Decline - per_transaction_min or per_transaction_max

Partial Approval

Decline - total_card_amount

Decline - Invalid transaction

Decline - transactions_max

Decline - Invalid amount

Decline - Merchant ID Control

Decline - Invalid card number

Decline - VCN-RCN Mapping Error

Decline - Invalid user

Decline - MCC Control

Decline - Format error

Decline - VCN Status

Capture - Lost card

Decline - Geographic Restriction

Capture - Stolen card

Decline - Transaction Type Restriction

Decline - Insufficient funds/over credit limit

Decline - Time/Date Restriction

Decline - Expired card

Decline - Unable to Process

Decline - Invalid pin

 

Decline - Transaction not permitted to issuer/cardholder

 

Decline - Transaction not permitted to acquirer/terminal

 

Decline - Exceeds withdrawal amount limit

 

Decline - Restricted card

 

Decline - Security violation

 

Decline - Exceeds withdrawal count limit

 

Call Issuer - Contact card issuer

 

Decline - PIN not changed

 

Decline - Allowable number of PIN tries exceeded

 

Decline - Invalid/nonexistent 'To Account' specified

 

Decline - Invalid/nonexistent 'From Account' specified

 

Decline - Invalid/nonexistent account specified

 

Decline - Domestic Debit Transaction Not Allowed

 

Decline - Invalid Authorization Life Cycle

 

Not declined - Valid for all zero amount transactions.

 

Decline - PIN Validation not possible

 

Approved - Purchase Amount Only, No Cash Back Allowed

 

Decline - Cryptographic failure

 

Decline - Unacceptable PIN— Transaction Declined—Retry

 

Decline - Authorization System or issuer system inoperative

 

Decline - Unable to route transaction

 

Decline - Duplicate transmission detected

 

System error

 

VCN Clearings Event Type

When a VCN transaction is cleared, that event can be tracked using webhooks.

 

Sample response for the "virtualcard.clearings" event type:

{
      "acquirer_ica": "001285",
      "approval_code": "050201",
"authorization_date": "2018-10-31", "billing_amount": 2450, "billing_currency": "USD",
"card_number": 556338######4001, "clearing_type": "Debit",
"exchange_rate": "1.000000", "mcc": "1750", "mcc_description": "EATING PLACES, RESTAURANTS", "merchant_amount": 2450, "merchant_currency": "USD", "merchant_id": "4445028900333", "merchant_name": "GOOD EATS", "settlement_date": "2018-11-01T00:00:00.000Z", "vcn_id": 15656669
}

Administrative Settings

The Virtualcard Configuration object allows you to control adminstrative settings for your virtual cards. Currently, there is only one attritube for this object - the max_card_amount.


The Virtualcard Configuration object

Attributes

NAME DESCRIPTION TYPE
max_card_amount No card can be created with a total_card_amount bigger than this value. integer

 

The max_card_amount sets a Maximum Card Threshold for client cards. Any attempts to create a virtual card through the API with a total_card_amount greater than the max_card_amount will fail. This threshold applies to all of your cards and is an additional control you can set to complement your existing company card program credit limit or individual virtual card controls.

Starting Nov 13, 2018 the default max_card_amount for new clients is $10 million. For clients that enrolled prior to Nov 13, 2018, the default remains $10,000. You can change the default to another amount. Once the max_card_amount is reset, the new default limit will apply to all new attempts to create virtual cards.

 

Example configuration object

{
    "max_card_amount": 1000000,
    "type": "config"
}

 


Retrieve the Virtualcard Configuration object

Retrieves the virtual card configuration object.

Endpoint

GET /v1/admin/virtualcard

Arguments

None.

 

Example request

curl "https://api.svb.com/v1/admin/virtualcard" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": {
    "max_card_amount": 1000000,
    "type": "config"
  }
}


Set the Virtualcard Configuration object

Endpoint

PATCH /v1/admin/virtualcard

Arguments

NAME DESCRIPTION TYPE
max_card_amount The largest card value in integer cents. integer

 

 

Example request

curl "https://api.svb.com/v1/admin/virtualcard" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X PATCH \
    -d '{
          "data": {
            "max_card_amount": 500000
          }
        }'

Example response

{
  "data": {
    "max_card_amount": 500000,
    "type": "config"
  }
}

Real Cards

Every virtual card maps to a single real credit card (i.e. a traditional plastic credit card). Your account may have one or more real credit cards associated with it.

  • If only one card is configured, new virtual cards will map by default to that single card.
  • If multiple real cards are configured, it is best to specify the rcn_id and rcn_alias of one of the objects returned via this endpoint when creating a new virtual card.

 

List all Real Cards

Retrieves a list of available real cards.

Endpoint

GET /v1/realcards

Arguments

None.

 

 

Example request

curl "https://api.svb.com/v1/realcards" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "87282",
      "alias": "Account 1"
    },
    {
      "id": "87284",
      "alias": "Account 2"
    }
  ]
}

Suppliers

List all Suppliers

Retrieves a list of suppliers.

Endpoint

GET /v1/suppliers

Arguments

None.

 

 

Example request

curl "https://api.svb.com/v1/suppliers" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "1826",
      "name": "Supplier 1"
    },
    {
      "id": "2016",
      "name": "Supplier 2"
    },
    {
      "id": "5021",
      "name": "Supplier 3"
    }
  ]
}

Templates

List all Templates

Retrieves a list of templates.

Endpoint

GET /v1/templates

Arguments

None.

 

 

Example request

curl "https://api.svb.com/v1/templates" \
    -H "Authorization: Bearer YOUR_API_KEY"
    

Example response

{
  "data": [
    {
      "description": "API Template for Company1",
      "id": "12345",
      "name": "API"
    },
  ]
}

The Virtual Card Object with Non-Realtime Authorizations (to be deprecated)

Virtual Card Object with Non-Realtime Authorizations encapsulates the details, authorizations, and clearing information in addition to the card number for an individual VCN. 

Important: Non-realtime authorizations will be deprecated as part of an upcoming 2018 release.

 

Attributes 

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 (see below) array
card_number The card number. string
clearings Clearing data on this card as a list of clearing objects (see below) array
currency The currency code the VCN is issued in string
cvc A short 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. 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 Will be Approved for valid cards. string
supplier_id Identifies the supplier integer
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

 

Example virtualcard object

{
    "available_balance": 9897,
    "authorizations": [{
      "billing_amount": 2448,
      "billing_currency": "USD",
      "date": "2015-11-07",
      "issuer_response": "Approved or completed successfully",
      "mcc": "1750",
      "mcc_description": "CARPENTRY CONTRACTORS",
      "merchant_amount": 2448,
      "merchant_currency": "USD",
      "merchant_id": "527636600321718",
      "merchant_name": "MERCHANT NAME",
      "transaction_type": "First Presentment"
    }],
    "card_number": "5563382306181964",
    "clearings": [{
      "billing_amount": 2448,
      "billing_currency": "USD",
      "exchange_rate": "1",
      "date": "2015-11-09",
      "mcc": "1750",
      "mcc_description": "CARPENTRY CONTRACTORS",
      "merchant_amount": 2448,
      "merchant_currency": "USD",
      "merchant_id": "527636600321718",
      "merchant_name": "MERCHANT NAME",
      "settlement_amount": 2448,
      "settlement_currency": "USD",
      "settlement_date": "2015-11-09"
    }],
    "currency": "USD",
    "cvc": "878",
    "emails": null,
    "expiry": "2017-10",
    "id": "87256",
    "last4": "1964",
    "mastercard_data": {
      "Reference": "123"
    },
    "metadata": {
        "purchase_number": "801b"
    },
    "per_transaction_max": 1000,
    "per_transaction_min": 0,
    "rcn_id": 87282,
    "rcn_alias": "Account 1",
    "status": "Approved",
    "supplier_id": 1826,
    "total_card_amount": 12345,
    "transactions_max": 10,
    "valid_ending_on": "2015-12-25",
    "valid_starting_on": "2015-10-07"
}


Non-Realtime Authorization Objects

Authorization data appears in the authorizations key of virtual card responses. The authorization data fields below will return in the response when the show_realtime_auths argument is set to false.  In this case the authorization data is refreshed a few times per day but is not realtime.  For realtime authorization data fields, see the Virtual Card Object with Realtime Authorization Data.

NAME DESCRIPTION TYPE
billing_amount Amount billed in integer cents. integer
billing_currency Currency of amount to be billed (e.g. “USD”). string
date Date of authorization in YYYY-MM-DD format. string
issuer_response String description of issuer response. string
mcc Merchant category code (e.g. “1750”). string
mcc_description Human-readable merchant category (e.g. “CARPENTRY CONTRACTORS”). string
merchant_amount Amount merchant authorized in integral cents. integer
merchant_currency Currency of amount authorized (e.g. “USD”). string
merchant_id Unique ID representing merchant. string
merchant_name Human-readable merchant name string
transaction_type One of these transaction types: Authorization, Advice, First Presentment, Reversal, string


Clearing Objects

Clearing information appears in the clearings key of virtual card responses. Clearings appear when transactions are settled, generally several days after a transaction is authorized.

Billing amount in the clearing object is the amount in your card’s billing currency (USD) of the transaction. Settlement amount in the clearing object is the amount in your card’s billing currency (USD) of the transaction plus any fees assessed on top of the transaction (e.g. a foreign transaction fee). For USD transactions, the merchant amount and billing amount should be the same.

The settlement date is the same as the transaction date and they both reflect the date as to which MasterCard processes the record from clearing.

NAME DESCRIPTION TYPE
billing_amount Amount billed in integer cents. integer
billing_currency Currency of amount billed (e.g. “USD”). string
clearing_type Indicates if the transaction is a debit (purchase) or a credit (return or reversal transaction). string
date Date of transaction in YYYY-MM-DD format. string
exchange_rate Exchange rate used for the transaction. string
mcc Merchant category code (e.g. “1750”). string
mcc_description Human-readable merchant category (e.g. “CARPENTRY CONTRACTORS”). string
merchant_amount Amount merchant authorized in integral cents. integer
merchant_currency Currency of amount authorized (e.g. “USD”). string
merchant_id Unique ID representing merchant. string
merchant_name Human-readable merchant name string
settlement_amount Amount settled in integral cents. integer
settlement_currency Currency of amount settled (e.g. “USD”). string
settlement_date Date of settlement in YYYY-MM-DD format. string

As shown below, each virtualcard document is contained in the "data"member.