Card Check - V1

With /card-check you can effortlessly integrate with different networks to receive the current account information. This stateless API fetches real-time card updates without requiring card enrollment to the VGS Account Updater. It operates without persisting any state.

Prerequisites

You will need a valid bearer_token to issue Enrollment API calls. Please see the Authentication guide for how to create one.

Limitations:

  • American Express and Discover do not support real-time Account Updater lookups.

    • Amex: Updates are retrieved approximately every 30 minutes.

    • Discover: Updates are retrieved once daily.

  • Updates for Amex and Discover are handled through batch-based file processing and delivered via webhooks.

Check a card for updates in VGS Account Updater

post
/card-check

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
/card-check
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"
  }
}

Example request:

curl
curl --X POST https://calm.<ENVIRONMENT>.verygoodsecurity.app/card-check \
-x https://<CREDENTIALS>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 -k \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${VGS_ACCESS_TOKEN}"
-d '{
      "name": "John Doe",
      "number": 5573491171027312,
      "exp_month": 7,
      "exp_year": 24
    }'

Example response:

Response (application/json)
{
  "data": {
    "name": "John Doe",
    "number": "5574491271028432",
    "exp_month": 7,
    "exp_year": 24,
    "event": "au_card.updated"
  }
}

Note: An error response can contain multiple validation messages for the same field/element. Example of multiple validations in the response:

Error response example
{
  "errors": [
    {
      "detail": "[number] size must be between 13 and 19",
      "error_code": "validation-failed"
    },
    {
      "detail": "[number] with invalid card number format",
      "error_code": "validation-failed"
    }
  ],
  "trace_id": "2d137f00cc53f5a9265f3b40402f7892"
}

Request Body Fields

The table below contains more details on the request body fields, which are required, and which are optional.

Field
Field Type
Description

name

Required

Name of the user on the card

number

Required

VGS alias representing the PAN

exp_month

Required

Expiration month on the card

exp_year

Required

Expiration year on the card

merchant

Conditional Required (pass this value if you are submitting the card on behalf of a merchant or if you have multiple merchants registered for a single VGS vault)

"merchant" element in the request payload

sub_merchant_name

Conditional Required (pass this value if you are submitting the card on behalf of a merchant)

Merchant Name registered on the card

vgs_merchant_id

Conditional Required (required only if multiple merchants are registered per VGS vault for Account Updater)

VGS generated ID per merchant registered for VGS Vault. This ID is returned as a part of the merchant registration process for Account Updater

Billing note: You will be billed if any of the following events occur when this API is invoked: Updated, Closed, Expired, or CardHolder Advice. Additionally, there will be no webhook response for future updates.

PreviousQuickstart - V1NextAPI Reference - V1