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.

Required scopes

This endpoint requires the following scopes:

• : Grants write access to cards

Authorizations

OAuth2clientCredentialsRequired

Token URL:

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

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/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.