> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/card-check-v1.md).
# 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](/cmp/platform/authentication.md) for how to create one.
{% hint style="warning" %}
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.
{% endhint %}
## Check a card for updates in VGS Account Updater
> 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.
```json
{"openapi":"3.0.0","info":{"title":"VGS Account Updater and Network Tokens APIs","version":"1.0.0"},"tags":[{"name":"Account Updater","description":"Cards enrolled in VGS Account Updater."}],"servers":[{"url":"https://calm.sandbox.verygoodsecurity.app","description":"Sandbox"},{"url":"https://calm.live.verygoodsecurity.app","description":"Live"}],"security":[{"OAuth2":["cards:write"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token","scopes":{"cards:write":"Grants write access to cards","cards:read":"Grants read access to cards","network-tokens:write":"Grants access to perform operations with network tokens","network-tokens:read":"Grants read access to the network tokens","merchants:write":"Grants write access to Merchant API","merchants:read":"Grants read access to Merchant API","merchants:admin":"Grants admin access to Merchant API"}}}}},"requestBodies":{"CardCheckRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}}},"schemas":{"Card":{"type":"object","description":"Payment card object.","required":["name","number","exp_month","exp_year"],"properties":{"name":{"maxLength":255,"description":"Card owner's full name.","type":"string"},"number":{"maxLength":19,"minLength":13,"pattern":"^(\\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})$","description":"Customer's card number.","type":"string"},"exp_month":{"description":"Card's expiration month.","type":"integer","minimum":1,"maximum":12},"exp_year":{"description":"Card's expiration year.","type":"integer","minimum":0,"maximum":99},"cvv":{"description":"Card's cvv","type":"string","pattern":"^\\d{3,4}$"},"merchant":{"description":"AU merchant details.","type":"object","properties":{"vgs_merchant_id":{"maxLength":255,"description":"VGS merchant id.","type":"string"},"sub_merchant_name":{"maxLength":255,"description":"Sub merchant name. Required if you are submitting the card on behalf of a merchant.","type":"string"},"sub_merchant_mid":{"maxLength":255,"description":"Sub merchant MID. In some cases required for PayFac customers","type":"string"}}}}},"CheckCardData":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CheckedCard"}}},"CheckedCard":{"allOf":[{"$ref":"#/components/schemas/Card"},{"type":"object","properties":{"failure_code":{"type":"string","enum":["account-updater-not-supported","merchant-not-found","invalid-exp-date","invalid-payload","invalid-param","internal-server-error"],"description":"Application-specific failure code which can only occur with failed state:\n * `account-updater-not-supported` - Account Updater is not implemented for your card issuer\n * `merchant-not-found` - No merchant was registered for organization\n"},"event":{"type":"string","description":"Current state of a card being processed:\n * `au_card.valid` - Card is valid. Current Account and Expiration Date returned\n * `au_card.updated` - Card was updated. New Account and Expiration Date returned\n * `au_card.expired` - Card was expired. New Expiration Date returned\n * `au_card.closed` - Card was closed.\n * `au_card.non_participating` - BIN is not participating in AU\n * `au_card.contact_cardholder_advice` - Cardholder has opted out and the merchant needs to contact cardholder for information\n * `au_card.unknown` - BIN is participating in AU but there is no match yet\n * `au_card.enrolled` - PAN and expiration date the merchant provided is up-to-date\n * `au_card.opt_out` - Cardholder has opted out sharing credential information with the merchants\n","enum":["au_card.valid","au_card.updated","au_card.expired","au_card.closed","au_card.non_participating","au_card.contact_cardholder_advice","au_card.unknown","au_card.enrolled","au_card.opt_out"]}}}]},"CardApiErrors":{"type":"object","required":["errors","trace_id"],"properties":{"errors":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/CardApiError"},{"$ref":"#/components/schemas/GeneralError"}],"description":"List of errors that occurred while processing the request.","minItems":1}},"trace_id":{"description":"A unique identifier of the failed request.","type":"string"}}},"CardApiError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error_code":{"type":"string","enum":["card-brand-not-supported","account-updater-not-supported","card-not-found","merchant-not-found"],"description":"Application-specific error code:\n * `card-brand-not-supported` - Specified card brand is not supported, only Mastercard cards are supported\n * `account-updater-not-supported` - Account Updater is not implemented for your card issuer\n * `card-not-found` - Card is not enrolled in CALM\n * `merchant-not-found` - No merchant was registered for organization and provided capability\n"}}}]},"Error":{"type":"object","description":"An error object","properties":{"detail":{"description":"Explanation of what exactly went wrong.","type":"string"}}},"GeneralError":{"additionalProperties":false,"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error_code":{"type":"string","enum":["internal-server-error","invalid-payload","validation-failed","unsupported-media-type"],"description":"Application-specific error code:\n * `internal-server-error` - Something went wrong\n * `invalid-payload` - Invalid request payload\n * `validation-failed` - Request validation failed\n * `unsupported-media-type` - Request media type is not supported\n"}}}]}},"responses":{"CardCheckResponse":{"description":"Card check API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckCardData"}}}}}},"paths":{"/card-check":{"post":{"tags":["Account Updater"],"summary":"Check a card for updates in VGS Account Updater","description":"Stateless api to fetch card updates without persisting any state\nVGS Account Updater will perform both card availability and eligibility checks to check that this specific card is eligible for management.\n","operationId":"checkCard","requestBody":{"$ref":"#/components/requestBodies/CardCheckRequest"},"responses":{"202":{"$ref":"#/components/responses/CardCheckResponse"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardApiErrors"}}}},"404":{"description":"Vgs Merchant Not found\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralError"}}}},"422":{"description":"Unprocessable Entity. Possible error codes:\n * `card-brand-not-supported`\n * `account-updater-not-supported`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardApiErrors"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralError"}}}},"default":{"$ref":"#/components/responses/CardCheckResponse"}}}}}}
```
Example request:
{% code title="curl" %}
```bash
curl --X POST https://calm..verygoodsecurity.app/card-check \
-x https://@..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
}'
```
{% endcode %}
Example response:
{% code title="Response (application/json)" %}
```json
{
"data": {
"name": "John Doe",
"number": "5574491271028432",
"exp_month": 7,
"exp_year": 24,
"event": "au_card.updated"
}
}
```
{% endcode %}
Note: An error response can contain multiple validation messages for the same field/element. Example of multiple validations in the response:
{% code title="Error response example" %}
```json
{
"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"
}
```
{% endcode %}
### 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 |
{% hint style="info" %}
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.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/card-check-v1.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.