# Account Validation

APIs for performing synchronous account validation checks, such as CVC, AVS, and cardholder name verification.

## Perform account validation checks

> Performs one or more validation checks for a given card, such as CVC, AVS, and cardholder name, in a synchronous (blocking) request. The presence of validation data in the request body implicitly specifies which checks are performed.<br>

```json
{"openapi":"3.1.0","info":{"title":"VGS Card Management Platform (CMP) API","version":"doc version 2.2.9 | API version 1.0.0"},"tags":[{"name":"Account Validation","description":"Performs one or more validation checks for a given card, such as CVC, AVS, and cardholder name, in a synchronous (blocking) request. The presence of validation data in the request body implicitly specifies which checks are performed."}],"servers":[{"url":"https://sandbox.vgsapi.com","description":"Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.\n"},{"url":"https://vgsapi.com","description":"Live environment server used for production workloads.\n"}],"security":[{"bearerAuth":["account-validations:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"auth-header":{"in":"header","name":"Authorization","description":"Bearer token for authentication.","schema":{"type":"string"},"required":true},"content-type":{"in":"header","name":"Content-Type","description":"Content type of a request to CMP","schema":{"type":"string","enum":["application/vnd.api+json"]},"required":true}},"schemas":{"AccountValidationRequest":{"type":"object","description":"The request body to initiate account validations. A card verification is always performed; the presence of `cvc`, `cardholder_address`, or `cardholder_name` additionally requests the corresponding optional check (CVC, AVS, name match).","required":["data"],"properties":{"data":{"type":"object","required":["attributes"],"properties":{"type":{"type":"string","description":"The resource type.","enum":["account-validations"]},"attributes":{"type":"object","description":"Validation inputs. A card verification auth is always performed; including `cvc`, `cardholder_address`, or `cardholder_name` additionally requests that optional check.","required":["merchant"],"properties":{"cvc":{"type":"string","description":"The 3-4 digit Card Verification Code (CVC). If present, CVC validation is performed.","minLength":3,"maxLength":4},"cardholder_address":{"type":"object","description":"Cardholder billing address. If present, address validation (AVS) is performed. `postal_code` is required; `street` is optional.","required":["postal_code"],"properties":{"street":{"type":"string","description":"Street address line."},"postal_code":{"type":"string","description":"Postal/ZIP code.","minLength":1}}},"cardholder_name":{"type":"object","description":"Cardholder name. If present, name validation is performed.","properties":{"first_name":{"type":"string","description":"Cardholder first name."},"middle_name":{"type":"string","description":"Cardholder middle name or initial."},"last_name":{"type":"string","description":"Cardholder last name."}}},"merchant":{"type":"object","description":"Merchant associated with the validation.","required":["merchant_name","address"],"properties":{"merchant_name":{"type":"string","description":"Merchant name."},"address":{"type":"object","description":"Merchant address.","required":["city","state","country","postal_code"],"properties":{"city":{"type":"string","description":"City name."},"state":{"type":"string","description":"State or region code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","minLength":2,"maxLength":2},"postal_code":{"type":"string","description":"Postal/ZIP code."}}}}}}}}}}},"AccountValidationResponse":{"type":"object","description":"The response body for a successful synchronous validation.","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"A unique identifier for this validation batch."},"type":{"type":"string","description":"The resource type.","enum":["account-validation-results"]},"attributes":{"type":"object","required":["attempted_at","card_verification_status"],"properties":{"transaction_identifier":{"type":"string","description":"Network-issued transaction identifier for the card verification batch. Absent when the network did not return one."},"attempted_at":{"type":"string","format":"date-time","description":"Timestamp when the validation was performed."},"card_verification_status":{"type":"string","enum":["verified","not_verified"],"description":"Outcome of the card verification, derived from the network response code. `verified` when the network confirmed the account; `not_verified` otherwise (and the default when the network response is missing or not in the recognized set)."},"validation_results":{"type":"array","description":"Results for each optional validation performed (CVC, address, name). `null` when no optional validations are requested. Order is not guaranteed.","items":{"$ref":"#/components/schemas/ValidationResult"}}}},"relationships":{"type":"object","description":"Links to related resources.","properties":{"card":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","enum":["cards"]},"id":{"type":"string","description":"The card ID for which validations were performed."}}}}}}},"links":{"type":"object","description":"Links related to this resource.","properties":{"self":{"type":"string","format":"uri","description":"Link to this validation result."}}}}},"meta":{"$ref":"#/components/schemas/MetadataResponse"}}},"ValidationResult":{"type":"object","description":"The result of an optional validation check (CVC, address, or cardholder name).","required":["type","status"],"properties":{"type":{"type":"string","enum":["cvc","address","name"],"description":"Which validation this result is for."},"status":{"type":"string","enum":["match","no_match","partial_match","not_supported","system_unavailable","invalid_data","non_participating"],"description":"Normalized outcome of the validation check, derived from the network response code. The legal subset depends on `type`: CVC uses `match` / `no_match` / `system_unavailable` / `invalid_data` / `non_participating`; name uses `match` / `no_match` / `partial_match`; address uses `match` / `no_match` / `partial_match` / `not_supported`. Default is `no_match`."},"detail":{"type":"object","description":"Per-component breakdown of the validation outcome. Only present when `type` is `address`; absent for `cvc` and `name`.","properties":{"street_address":{"type":"string","enum":["match","no_match"],"description":"Match status for the street address component."},"postal_code":{"type":"string","enum":["match","no_match"],"description":"Match status for the postal code component."}}}}},"MetadataResponse":{"type":"object","title":"MetadataResponse","properties":{"observability":{"$ref":"#/components/schemas/Observability"}}},"Observability":{"type":"object","title":"Observability","properties":{"trace_id":{"type":"string"},"client_id":{"type":"string"},"vault_id":{"type":"string"},"account_id":{"type":"string"},"fingerprint":{"type":"string"}}},"ErrorResponse":{"properties":{"errors":{"items":{"properties":{"path":{"type":"string","title":"Path"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"error_code":{"type":"string","title":"Error Code"},"fingerprint":{"type":"string","title":"string"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors","required":["summary","detail","error_code"]},"meta":{"anyOf":[{"type":"object"}],"title":"Meta"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}]},"type":"object"}],"title":"Links"},"included":{"anyOf":[{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"attributes":{"anyOf":[{"properties":{},"additionalProperties":true,"type":"object","title":"LubeAttributes","description":"Members of the LubeAttributes object (\"attributes\") represent information about the resource object in which it's defined.\n\n\nThe keys for Attributes MUST NOT be:\n\n\n    relationships\n    links\n    id\n    type\n"},{"type":"null"}]},"relationships":{"anyOf":[{"additionalProperties":{"properties":{"links":{"anyOf":[{"properties":{"self":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"relationship link"},"related":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"related resource link"}},"type":"object","title":"LubeRelationLink"},{"type":"null"}]},"data":{"anyOf":[{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","title":"LubeRel","description":"JSON:API Relationship"},"type":"object"},{"type":"null"}],"title":"Relationships"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","required":["id","type"],"title":"LubeResource","description":"A single resource. The only JSON:API required field is type"},"type":"array"}],"title":"Included"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorResponse"},"JsonApiVersion":{"properties":{"version":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Version","default":1.1},"ext":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Ext"}]},"profile":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Profile"}]},"meta":{"type":"object","title":"Meta"}},"title":"JsonApi"}}},"paths":{"/cards/{card_id}/validations":{"post":{"tags":["Account Validation"],"summary":"Perform account validation checks","description":"Performs one or more validation checks for a given card, such as CVC, AVS, and cardholder name, in a synchronous (blocking) request. The presence of validation data in the request body implicitly specifies which checks are performed.\n","operationId":"perform_account_validation","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card ID"}},{"$ref":"#/components/parameters/auth-header"},{"$ref":"#/components/parameters/content-type"}],"requestBody":{"description":"Account validation request payload.","required":true,"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AccountValidationRequest"}}}},"responses":{"200":{"description":"SUCCESS: The validation was performed and results are in the response body.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AccountValidationResponse"}}}},"400":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was invalid."},"401":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No credentials were provided, or the provided credentials were expired."},"403":{"description":"Forbidden. The client does not have permission to perform this action, or the vault context could not be determined from the request.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found."},"422":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The server was unable to process the request because it contains invalid data."},"500":{"description":"Internal Server Error","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable. The downstream network is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/account-validation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.