NAV
curl

← Home

Virtual Cards

Introduction

Disclaimer: This documentation is currently in Beta and is subject to change.

This is the official reference documentation for the SVB Virtual Cards APIs. Please see the authentication documentation for access information.

SVB currently provides a simple and powerful set of APIs allowing you to integrate virtual card numbers (VCNs) into your business applications. All APIs use HTTPS and JSON to provide a RESTful interface.



Virtual Cards

The Virtualcard object

Virtual card objects encapsulate the details, authorizations, and clearing information in addition to the card number for an individual VCN.

Attributes

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": "840",
      "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"
}
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

Authorization Objects

Authorization data appears in the authorizations key of virtual card responses. Authorizations are tracked throughout the day.

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,
Reversal advice, Unspecified (Offline Settlements), Purchase Return, Forced Post 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
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.

Create a Virtual Card

Example request

curl "https://api.svb.com/v1/virtualcards" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "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"
  }
}

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

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

Example request

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

Example response

{
  "data": {
    "available_balance": 11345,
    "authorizations": [{
      "billing_amount": 1000,
      "billing_currency": "USD",
      "date": "2015-11-07",
      "issuer_response": "Approved or completed successfully",
      "mcc": "1750",
      "mcc_description": "CARPENTRY CONTRACTORS",
      "merchant_amount": 1000,
      "merchant_currency": "USD",
      "merchant_id": "527636600321718",
      "merchant_name": "MERCHANT NAME",
      "transaction_type": "Authorization"
    }],
    "card_number": null,
    "clearings": [{
      "billing_amount": 1000,
      "billing_currency": "USD",
      "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": "840",
      "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"
  }
}

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.

card_number returns null when show_card_number is not set to true

Endpoint

GET /v1/virtualcards/:id

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"

Cancel a Virtual Card

Example request

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

Cancel a virtual card you’ve previously created.

Example response

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

Update a Virtual Card

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

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.

List all Virtual Cards

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

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 the page[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 metadata portion of the virtual card.

To filter, use the the filter[metadata.key]=value parameter. The metadata. 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 certain purchase_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[metadata.string].

Send an email about a Virtual Card

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

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.

Administration tools

There is a separate admin user with a different secret key than the normal user. The admin user can read and set a config object that contains the master parameters for an account.

Currently, the only configuration parameter is max_card_amount.

The Virtualcard Configuration object

Attributes

Example configuration object

{
    "max_card_amount": 1000000,
    "type": "config"
}
Name Description Type
max_card_amount The largest card value in integer cents. integer
No card can be created with a total_card_amount bigger than this value.

Retrieve the Virtualcard Configuration object

Example request

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

Retrieves the virtual card configuration object.

Example response

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

Endpoint

GET /v1/admin/virtualcard

Arguments

None.

Set the Virtualcard Configuration object

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

Sets the virtual card configuration object.

Example response

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

Endpoint

PATCH /v1/admin/virtualcard

Arguments

Name Description Type
max_card_amount The largest card value in integer cents. integer

Real Cards

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

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


Suppliers

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

List all Suppliers

Retrieves a list of suppliers.

Endpoint

GET /v1/suppliers

Arguments

None.