Quickstart - V1

This guide describes how to get started with the Card Attributes Service API. It is designed for an integration developer as the first step in learning how to integrate with the API, but should be simple enough for anyone to follow.

Using the API

For this quickstart you will need the following.

• Admin access to the VGS Dashboard and a VGS sandbox or live vault.

• Access to a terminal command line.

Once you are ready for full integration, the full Open API specification for this API is located here in our API Reference store.

Create and store your API credentials

This API authenticates using the OAuth2.0 client credentials flow, which requires a client id and secret to obtain an access token. You can create credentials in your VGS dashboard or via the VGS CLI, following these instructions.

1

Create a service account

To create a service account for your organization, go to the Service Accounts section of the VGS Dashboard > Organization settings page and click the "Create New" button. Assign a name for this credential and select scopes.

Scopes indicate the services you wish to be accessed by these credentials. If they are available, assign one of the two following scopes: card-attributes:basic for basic level access to the attributes or card-attributes:advanced for advanced access. Advanced has more capabilities than basic; the differences are outlined below.

If you do not have access to these scopes, you can create a service account without adding these scopes; you will still have access to the basic version of the API, but will be limited to 15 times a day.

2

Save your Client ID and Secret

Important! Be sure to save your Client ID and Secret!! You will not see the client secret again after it is presented to you on the screen.

3

Store credentials as environment variables

Store your credentials in environment variables on your device by going into a terminal and entering these commands. Replace <client id> and <secret> with your actual Client Id and Secret.

Set VGS credentials (bash)

export VGS_CLIENT_ID=<client id>
export VGS_CLIENT_SECRET=<secret>

Try out the API

Now that you have stored the environment variables on your device, the following cURL command will retrieve an access token and use that token to call the VGS Card Attributes API.

1

Retrieve an access token and call the Attributes endpoint

cURL example

curl https://card-enrichment-api.live.verygoodvault.com/attributes -H "Authorization: Bearer $( curl --request POST \
  --url 'https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=${VGS_CLIENT_ID}  \
  --data client_secret=${VGS_CLIENT_SECRET} | jq -r .access_token)" \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "411111"
}' -v

Response Body

The command will return a JSON object similar to the one below.

Sample response

{
  "bin": "411111",
  "brand": "VISA",
  "issuing_organization": "CONOTOXIA SP. Z O.O",
  "card_type": "DEBIT",
  "card_category": "CLASSIC",
  "issuing_country_name": "POLAND",
  "issuing_country_code": "616",
  "maximum_pan_length": 16,
  "card_commercial_type": "PERSONAL",
  "regulation_status": "UNREGULATED",
  "version": "v20241206",
  "prepaid_type": "NONRELOADABLE"
}

Additional Test data

Replace the 411111 in the above REST API with the samples below.

• 223009 : Mastercard

• 340002 : American Express

Attribute Summary

Attribute	Definition	Access Level Required
bin	bin number	Basic
brand	The card brand facilitates payment transactions. Eg: Visa, Mastercard, Discover	Basic
issuing_organization	The bank that issued the card to the customer. Eg: Chase, Bofa, USBank	Basic
card_type	The type of card that is issued by the issuing bank. Eg: Credit , Debit	Basic
card_category	Category of Card. Eg: BUSINESS , PREPAID	Basic
issuing_country_name	ISO country name that is associated with an ISO code. Eg: USA, United Kingdom	Basic
issuing_country_code	Issuing country ISO number: Eg 840 for USA	Basic
maximum_pan_length	maximum PAN length	Basic
card_commercial_type	Defines if the BIN is PERSONAL or COMMERCIAL	Basic
regulation_status	Defines if the BIN is regulated or non-regulated	Basic
version	Date at which the returned data was last updated	Basic
prepaid_type	Indicates if the card is a prepaid debit card	Advanced
cobadged_brands	Lists the network co-badges of the card, if applicable	Advanced

With the Advanced scope assigned, all basic attributes are returned as well as advanced attributes.