Learning Central

Client Services

North America

clientsupport@svb.com
1.800.774.7390 | 408.654.4636
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

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 | 408.654.4636
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
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, "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
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

 

 

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 is an advanced field that requires deeper integration with MasterCard. These fields are sent to MasterCard as “Custom Data Fields”, and they must be defined as part of the VCN template prior to use. These values have a max length of 80 characters. The mastercard_data field should only be used by experts, and even then only be used for backward compatibility with existing syste.

 

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.

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.

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)

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

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


Error Messages on Update

Same as  Creating a VCN errors.

 

 

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

SVB uses a cursor approach to retrieve each page of data. Use thepage[cursor] parameter to give the id of the first element on the page and page[limit] to control how many elements are returned.

Filtering

The results can be filtered by matching fields in the metadataportion 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"
}

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 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
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.