API Reference

Enroll a new card in VGS Account Updater

post

Asynchronously enrolls a card to the card lifecycle management system for future update notifications. VGS Account Updater will perform both card availability and eligibility checks to check that this specific card is eligible for management.

Authorizations
Body
all ofOptional
and
Responses
202

Enroll card API response.

application/json
post
POST /cards HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "name": "John Doe",
  "number": "5573495XTjZP21V7312",
  "exp_month": 7,
  "exp_year": 24
}
{
  "data": {
    "name": "John Doe",
    "number": "5573495XTjZP21V7312",
    "exp_month": 7,
    "exp_year": 24,
    "billing_address": {
      "name": "John Doe",
      "company": "John Doe Company",
      "address1": "555 Example St",
      "address2": "M13 9PL",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "postal_code": "12301",
      "phone": "+14842634673"
    },
    "capabilities": [
      "ACCOUNT_UPDATER"
    ],
    "id": "CRDuVQCsenqj6dbHFQq9gen2E",
    "created_at": "2019-05-15T12:30:45Z",
    "updated_at": "2019-05-15T12:30:45Z",
    "state": "enrolled",
    "event": "au_card.enrolled"
  }
}

Check a card for updates in VGS Account Updater

post

Stateless api to fetch card updates without persisting any state VGS Account Updater will perform both card availability and eligibility checks to check that this specific card is eligible for management.

Authorizations
Body

Payment card object.

namestring · max: 255Required

Card owner's full name.

Example: John Doe
numberstring · min: 13 · max: 19Required

Customer's card number.

Example: 5573491171027312Pattern: ^(\d{6}.{0,9}[a-zA-Z].{0,9}\d{4}?)|((?:4[0-9]{12}(?:[0-9]{3})?)|5[1-5][0-9]{14}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})$
exp_monthinteger · min: 1 · max: 12Required

Card's expiration month.

Example: 7
exp_yearinteger · max: 99Required

Card's expiration year.

Example: 24
cvvstringOptional

Card's cvv

Example: 123Pattern: ^\d{3,4}$
Responses
202

Card check API response.

application/json
post
POST /card-check HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "name": "John Doe",
  "number": "5573495XTjZP21V7312",
  "exp_month": 7,
  "exp_year": 24
}
{
  "data": {
    "name": "John Doe",
    "number": 5573491171027312,
    "exp_month": 7,
    "exp_year": 24,
    "cvv": 123,
    "merchant": {
      "vgs_merchant_id": "MCq7GWCbtVXaNt8b4k2xraTw",
      "sub_merchant_name": "John",
      "sub_merchant_mid": 345643355
    },
    "failure_code": "account-updater-not-supported",
    "event": "au_card.valid"
  }
}

Get information on a specific enrolled card

get

Returns information of enrolled card with the most up-to-date card information available from issuing banks and all VGS Account Updater capabilities.

Authorizations
Path parameters
card_idstringRequired

ID of the card to fetch

Example: CRDuVQCsenqj6dbHFQq9gen2EPattern: ^CRD.*$
Responses
200

Enroll card API response.

application/json
get
GET /cards/{card_id} HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": {
    "name": "John Doe",
    "number": "5573495XTjZP21V7312",
    "exp_month": 7,
    "exp_year": 24,
    "billing_address": {
      "name": "John Doe",
      "company": "John Doe Company",
      "address1": "555 Example St",
      "address2": "M13 9PL",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "postal_code": "12301",
      "phone": "+14842634673"
    },
    "capabilities": [
      "ACCOUNT_UPDATER"
    ],
    "id": "CRDuVQCsenqj6dbHFQq9gen2E",
    "created_at": "2019-05-15T12:30:45Z",
    "updated_at": "2019-05-15T12:30:45Z",
    "state": "enrolled",
    "event": "au_card.enrolled"
  }
}

Mock Responses and Test Cards

For testing purposes, in the sandbox environment, the result of the card enrollment request will depend on the final digits of the card number used in the request. Any Mastercard card number can be used for testing purposes. You can send mock card numbers in Sandbox following the rules below to test card enrollment and webhook notifications.

The response will be available only after a card is enrolled (state changes to enrolled). During enrolling state, the response is not yet determined and submitted initial card data is returned.

For Mastercard card enrollment testing in Sandbox, please use the below cards.

Request
Expiry Date
Event in Response

51002600099240

Any Future Date

Account update response

51002600089241

Any Future Date

Account not found response from a non-participating BIN

51002600079242

Any Future Date

No change response, (the card is still valid)

51002600059244

Any Future Date

Account closed response

51002600049245

Any Future Date

Account expiry date update response

51002600029247

Any Future Date

Account not found response from a participating BIN (Unknown)

51002600039246 51002600019248 51002600009249

Any Future Date

An example error response

To receive webhook notifications in the sandbox for Mastercard, please ensure that you use the following test cards during the enrollment process. For detailed instructions on enrolling a card into the VGS Account Updater, refer to the enrollment process documentation. Specifically, you will need to use VGS's /cards API to enroll a card into the VGS Account Updater.

Mastercard Card Number
Expiration Date
Notification Event-Triggered

5100260000079200

Any Future Date

Valid

5100260000069201

Any Future Date

Updated

5100260000059202

Any Future Date

Expired

5100260000049203

Any Future Date

Closed

5100260000039204

Any Future Date

Non_participating

5100260000029205

Any Future Date

Unknown

For Visa testing in Sandbox, please use the below cards.

Card Number
Expiry Date
Event in Response

4327390068355738

22/10

Account update event

4680056031099387

26/08

Account expired event

4403933787254356

26/09

Account closed event

4000220720915104

25/01

Contact cardholder advice event

4207670264522669

26/10

Account valid/Enrolled event

4549612182636736

23/03

Account non-participating event

To receive webhook notifications in the sandbox for Visa, please make sure to use the following test cards during the enrollment process. Refer to the same enrollment process documentation and use the /cards API for enrolling a card into the VGS Account Updater.

Visa Card Number
Expiration Date
Notification Event-Triggered

4000210000069200

Any Future Date

Updated

4000210000059201

Any Future Date

Expired

4000210000049202

Any Future Date

Closed

4000210000039203

Any Future Date

Contact_cardholder_advice

4000210000029204

Any Future Date

Valid

4000210000019205

Any Future Date

Non_participating

4000210000009206

Any Future Date

Unknown

4000210000099207

Any Future Date

Opt-out

Note: When using VGS mock test cards for testing purposes, the system does not save the enrollment details in the database. These mock cards are only used to simulate events and generate responses. Therefore, if you attempt to perform a GET request using the cardID generated during such an enrollment, the request will return a 404 error, indicating that the record does not exist.

Please refer to VGS States and Network Events section for additional details regarding the events.

PreviousCard CheckNextNetwork Tokens

Last updated