# 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 CVV, AVS, and cardholder name, in a synchronous (blocking) request. The presence of validation data in the request body implicitly specifies which checks are performed.

```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":"APIs for performing synchronous account validation checks, such as CVC, AVS, and cardholder name verification."}],"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":[{"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","configurations:read":"Grants read access to configurations","configurations:write":"Grants write access to configurations"}}}}},"schemas":{"AccountValidationRequest":{"type":"object","description":"The request body to initiate one or more account validations. The presence of each field in attributes implicitly determines which validations are performed.","required":["data"],"properties":{"data":{"type":"object","required":["attributes"],"properties":{"type":{"type":"string","enum":["account-validations"],"description":"The resource type."},"attributes":{"type":"object","description":"Validation data. The presence of each field determines which checks are performed.","properties":{"card_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.","properties":{"street":{"type":"string","description":"Street address line."},"postal_code":{"type":"string","description":"Postal/ZIP code."},"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}}},"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."}}},"card_acceptor":{"type":"object","description":"Card acceptor (merchant) information required for payment account validation.","required":["id_code","name"],"properties":{"id_code":{"type":"string","description":"Card Acceptor ID (CAID). Unique identifier for the merchant or funds transfer originator.","minLength":1,"maxLength":15},"name":{"type":"string","description":"Name of the card acceptor as known to the cardholder.","minLength":1,"maxLength":25},"terminal_id":{"type":"string","description":"Terminal identifier at the card acceptor location.","minLength":1,"maxLength":8},"address":{"type":"object","description":"Physical address of the card acceptor.","properties":{"city":{"type":"string","description":"City of the merchant.","maxLength":13},"state":{"type":"string","description":"2-character state or territory code.","minLength":2,"maxLength":2},"country":{"type":"string","description":"ISO 3166-1 alpha-2 or alpha-3 country code.","minLength":2,"maxLength":3},"postal_code":{"type":"string","description":"Postal/ZIP code of the merchant.","minLength":5,"maxLength":9}}}}},"acquirer":{"type":"object","description":"Acquirer information required for payment account validation.","required":["bin","country_code"],"properties":{"bin":{"type":"string","description":"Acquiring Bank Identification Number (BIN).","minLength":6,"maxLength":11},"country_code":{"type":"string","description":"3-digit numeric ISO country code of the acquirer.","minLength":3,"maxLength":3}}}}}}}}},"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","enum":["account-validation-results"],"description":"The resource type."},"attributes":{"type":"object","required":["created_at","validation_results"],"properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the validation was performed."},"validation_results":{"type":"object","description":"Contains the results for each validation performed. Only fields corresponding to requested validations will be present.","properties":{"cvc_result":{"$ref":"#/components/schemas/CvcAvsAniValidationResult"},"address_result":{"$ref":"#/components/schemas/CvcAvsAniValidationResult"},"name_result":{"$ref":"#/components/schemas/CvcAvsAniValidationResult"},"account_validation_result":{"$ref":"#/components/schemas/AccountValidationResult"}}}}},"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."}}}}}}}}}}},"CvcAvsAniValidationResult":{"type":"object","description":"The result of a CVC, AVS, or cardholder name validation check.","required":["status"],"properties":{"status":{"type":"string","enum":["matched","not_matched","partially_matched","not_verified","not_supported"],"description":"The normalized outcome of the validation check."},"network_response_code":{"type":"string","description":"The raw response code from the card network."},"network_response_description":{"type":"string","description":"The raw response description from the card network."}}},"AccountValidationResult":{"type":"object","description":"The result of a zero-dollar auth (account validation) check.","required":["status"],"properties":{"status":{"type":"string","enum":["approved","declined","partial_approval","not_verified","not_supported"],"description":"The normalized outcome of the zero-dollar auth check."},"network_response_code":{"type":"string","description":"The raw response code from the card network."},"network_response_description":{"type":"string","description":"The raw response description from the card network."}}},"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"},"ErrorForbiddenResponse":{"properties":{"errors":{"items":{"properties":{"status":{"type":"integer","title":"Status"},"details":{"type":"string","title":"Details"},"title":{"type":"string","title":"Title"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorForbiddenResponse"}}},"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 CVV, AVS, and cardholder name, in a synchronous (blocking) request. The presence of validation data in the request body implicitly specifies which checks are performed.","operationId":"perform_account_validation","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card ID"}}],"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":{"content":{"application/vnd.api+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ErrorForbiddenResponse"}]}}},"description":"Valid credentials were provided, but they do not permit access to this resource."},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```