Card Check

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.

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

OAuth2

Body

application/json

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

400

Bad Request

application/json

404

Vgs Merchant Not found

application/json

422

Unprocessable Entity. Possible error codes:

• card-brand-not-supported
• account-updater-not-supported

application/json

500

Internal Server Error

application/json

default

Card check API response.

application/json

post

HTTPcURLJavaScriptPython

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

{
  "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 as shown below:

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

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