# Code and Formats source: https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md ## Status Values {#status-values} When an account is validated, a success response message (200 status code) for an open and valid account will include status values, for example: * Mastercard * Visa ```Mastercard "cvcValidationResults": { "status": "MATCHED", "responseCode": "M", "responseCodeDescription": "CVC2/CSC match" }, "nameValidationResults": { "status": "PARTIAL_MATCHED" } ``` ```Visa "cvcValidationResults": { "status": "MATCHED", "responseCode": "M", "responseCodeDescription": "CVV2 match" }, "nameValidationResults": { "status": "PARTIAL_MATCHED", "firstNameStatus": "NOT_MATCHED", "middleNameStatus": "NOT_MATCHED", "lastNameStatus": "MATCHED" } ``` Your systems will use these `status` values to determine app functionality, such as whether to trust the account and/or proceed with a transfer. ### Invalid accounts and other problems {#invalid-accounts-and-other-problems} If there is a problem with the account, such as closed account, invalid account, or stolen card, the issuer will decline the validation request and the `networkResponseCode` and `networkResponseCodeDescription` fields will indicate the reason, for example: * Invalid account * Stolen card ```Invalid account "networkResponseCode": "78", "networkResponseCodeDescription": "Invalid/nonexistent account specified (general)", "nameValidationResults": { "status": "NOT_VERIFIED" } ``` ```Stolen card "networkResponseCode": "43", "networkResponseCodeDescription": "Stolen card", "nameValidationResults": { "status": "NOT_VERIFIED" } ``` These values are the Network Response Codes (ISO Codes) from the network, which are passed to Mastercard in Data Element (DE) 39 of the issuer's network response message. The codes depend on the issuer and network and may differ from the examples shown above. For more information about network response codes, refer to the *DE 39 (Response Code)* section in either of these documents, which are available in the [Technical Resource Center](https://trc-techresource.mastercard.com/) on Mastercard Connect: * [*Mastercard Network Processing Dual Message Authorization System Guide*](https://trc-techresource.mastercard.com/r/bundle/m_DMAS_en-us/page/d/en-US) * [*Mastercard Network Processing Single Message System Guide*](https://trc-techresource.mastercard.com/r/bundle/m_SMS_Guide_en-us/page/d/en-US) ### CVC/CVV matching values {#cvccvv-matching-values} The `cvcValidationResults` object contains the CVC/CVV validation results, and it is only present when the CVC/CVV was supplied in the API request. The `status` value can be: | Value | Meaning | |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MATCHED | The provided CVC matches the CVC on file. | | NOT_MATCHED | The provided CVC does not match the CVC on file. | | NOT_VERIFIED | The provided CVC was not verified. This value could be returned when: * The verification information is not available. * The issuer has declined the validation request because there is a problem with the account, see [Invalid accounts and other problems](https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md#invalid-accounts-and-other-problems). | The other values (`responseCode`, and `responseCodeDescription`) are from the card issuer or address validation system, and they are provided for completeness. However, we do not list those values because they have already been translated into the `status` value and are subject to change. ### Name matching values {#name-matching-values} The `nameValidationResults` object contains the name validation results. The `status` value can be: | Value | Meaning | Additional fields present for Visa network? | |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------| | MATCHED | The provided name matches the name on file. | Yes | | PARTIAL_MATCHED | Some of the names provided matched but not all. | Yes | | NOT_MATCHED | The provided name does not match the name on file. | Yes | | NOT_VERIFIED | The provided name was not verified. This value could be returned when: * The verification information is not available. * The issuer has declined the validation request because there is a problem with the account, see [Invalid accounts and other problems](https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md#invalid-accounts-and-other-problems). | | | NOT_SUPPORTED | Only applies for cards processed via the Visa network. Name match not supported. | | ##### Additional fields for Visa network {#additional-fields-for-visa-network} For cards processed via the Visa network, additional `firstNameStatus`, `middleNameStatus`, `lastNameStatus` fields may be present, providing more granular matching information. `middleNameStatus` is not present if the middle name was not supplied in the API request (as `middleName`). The additional values can be: | Additional name value | Meaning | |-----------------------|----------------------------------------------------| | MATCHED | The provided name matches the name on file. | | PARTIAL_MATCHED | Some of the names provided matched but not all. | | NOT_MATCHED | The provided name does not match the name on file. | ##### Example {#example} This example shows a partial name match response. | | Name supplied in API request | Name on file at issuer | |-------------|------------------------------|------------------------| | First name | Beyoncé | Beyoncé | | Middle name | Sasha | Giselle | | Last name | Knowles | Knowles-Carter | * Mastercard * Visa ```Mastercard "nameValidationResults": { "status": "PARTIAL_MATCHED" } ``` ```Visa "nameValidationResults": { "status": "PARTIAL_MATCHED", "firstNameStatus": "MATCHED", "middleNameStatus": "NOT_MATCHED", "lastNameStatus": "PARTIAL_MATCHED" } ``` ## Error Codes {#error-codes} If your API request is unsuccessful, you should receive a service error response or a gateway error response, which have the following structure. The `Error` array may contain multiple error items. * JSON ```JSON { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` The `Recoverable` value (true or false) indicates whether your API request might be successful if you re-send the API request with the **same** parameters and data. For example, an unsuccessful API request caused by a server error might be successful when re-sent. ### Service error codes {#service-error-codes} Service error response messages (4xx status code) have `Source` as "Account Validation Service". The following table shows the `ReasonCode`, `Description`, and `Details` values that can be returned. Other values might also exist or be introduced periodically. Do not code closely to the `Details` values because they may change. | Reason Code | Description | Details | How to Resolve | |------------------------|-----------------------------------------------------------------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **HTTP Code 400:** | | | | | ENCRYPTION_ERROR | Encryption header is set to false | null | Your partner configuration is enabled for encryption, but the `X-Encrypted` header value is 'false' or omitted. Set the header to 'true' and provide an encrypted payload. | | ENCRYPTION_ERROR | Encrypted payload received | null | The `X-Encrypted` header value is 'false' or omitted, but you provided an encrypted payload. Depending on your partner configuration, either set the value to 'true' for the encrypted payload or provide an unencrypted payload. | | ENCRYPTION_ERROR | Encrypted payload is required | null | The `X-Encrypted` header value is 'true', but you provided an unencrypted payload. Depending on your partner configuration, either set the value to 'false' for the unencrypted payload or provide an encrypted payload. | | INVALID_INPUT_VALUE | Invalid value | \ | Correct the value for the field identified by `Details`. | | INVALID_INPUT_VALUE | Either acquiringCredentials or originatingInstitutionPartnerID should be present and not both | originatingInstitutionPartnerID | Provide `originatingInstitutionPartnerId` or `acquiringCredentials`, but not both. | | INVALID_INPUT_VALUE | Multiple Originating Institution Partner Ids found | originatingInstitutionPartnerID | Your partner configuration is associated with multiple Originating Institutions (OIs). Provide either `originatingInstitutionPartnerId` or `acquiringCredentials`, but not both. | | INVALID_INPUT_VALUE | Only Single or Dual Message is allowed | acquiringCredentials | Too many acquiring credentials. Provide `singleMessage` or `dualMessage`, but not both. | | INVALID_INPUT_VALUE | No Acquiring Credentials found | acquiringCredentials | The acquiring credentials provided in the request do not match the partner configuration. | | INVALID_INPUT_LENGTH | Invalid length | \ | Correct the value for the field identified by `Details`. | | INVALID_INPUT_FORMAT | Value contains invalid character(s) | \ | Correct the value for the field identified by `Details`. | | MISSING_REQUIRED_INPUT | Value is required | \ | Provide the field identified by `Details`. | | RESOURCE_ERROR | Account is not eligible for the transaction | accountDetails.account.number | You are not onboarded for a particular network (Mastercard or Visa) or account type, so you cannot check this account. For example, you may be configured for debit cards but are trying to check a credit card. | | RESOURCE_ERROR | Account not eligible | accountDetails.account.number | Account not eligible. The account may not exist or may not be enabled. Provide a valid account number. | | RESOURCE_ERROR | Transfer Acceptor missing in partner data | transferAcceptor | Your partner configuration is likely not associated with a Transfer Acceptor (TA), so you need to provide the details in the `transferAcceptor` object. | | RESOURCE_ERROR | Multiple transfer acceptors found | transferAcceptor | Your partner configuration is associated with multiple Transfer Acceptors (TAs), so you need to identify the TAID. Provide a valid `transferAcceptor.id` value. | | RESOURCE_ERROR | Multiple profiles found | transferAcceptor | Your partner configuration is associated with multiple Transfer Acceptors (TAs), so you need to identify the TAID. Provide a valid `transferAcceptor.id` value. | | RESOURCE_ERROR | Partner not eligible for the transaction | null | `Partner-Id` header value is invalid. Provide the correct value. | | RESOURCE_ERROR | Partner not eligible for the transaction | originatingInstitutionPartnerID | `originatingInstitutionPartnerId` is invalid. Provide a valid value or `acquiringCredentials`, but not both. | | RESOURCE_ERROR | Partner not eligible for the transaction | transferAcceptor.address.country | Country not eligible. Your partner configuration is not enabled for the specified country. Provide a valid country. | | RESOURCE_ERROR | Partner not eligible for the transaction | pointOFServiceInteraction | `pointOfServiceInteraction` does not match the onboarded configuration. Correct the value. | | RESOURCE_ERROR | Partner not eligible for the transaction | Partner-Id | Partner not active. The specified partner is not configured to use this service. | | **HTTP Code 401:** | | | | | UNAUTHORIZED_ACCESS | Unauthorized Access | Partner-Id | Partner not onboarded. Provide the correct `Partner-Id` header value. Also see the guidance below this table. | | UNAUTHORIZED_ACCESS | Unauthorized Access | OpenAPIClientId | Client user not associated with partner. Ensure you have provided the correct `Partner-Id` header value. Also see the guidance below this table. | | **HTTP Code 404:** | | | | | CRYPTO_KEY_NOT_FOUND | Encryption/Decryption key not available for openApiClientId , productName and keyid | null | You provided an encrypted payload that uses encryption keys not associated with your Mastercard Developers project or partner configuration. Check you are using the correct keys and credentials for the API environment. | | **HTTP Code 409:** | | | | | DUPLICATE_VALUE | Duplicate value | referenceId | Your request has the same `referenceId` value as a previous request. Resubmit with a unique value. | A 401 'Unauthorized Access' error can occur when Mastercard has not completed setup for the API environment or you are using the wrong credentials or keys: * MTF: Use the sandbox credentials and ensure you have asked your Mastercard Implementation Manager or Mastercard representative to configure MTF for your sandbox keys. * Production: Use the production credentials and ensure your Mastercard Developers production access request has been approved (as reflected in your project page 'Summary' panel) --- if it has not, notify your Mastercard Implementation Manager or Mastercard representative about your production request. Allow 5-7 business days for Mastercard to complete setup for the API environment. Mastercard will notify you when you can start making API calls to that environment. ### Gateway error codes {#gateway-error-codes} In addition to service error codes, error codes can also be returned by Mastercard's gateway, which is used to verify your request's signature, and route it to the correct location. You can find a list of the errors returned by our Gateway, as well as resolutions to each, on the following page [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/errors-troubleshooting/gateway-error-codes/). ## Accounts {#accounts} The `account` object identifies the account to validate: * JSON ```JSON "account": { "type": "PAN", "number": 5102589999999913, "expiry": "2050-10", "cvc": 123 } ``` The service can validate Mastercard and Visa card accounts (in regions where connectivity is established). You can specify a card account number (PAN) or tokenized PAN; both are `type` = 'PAN': * PAN = Numeric, length 11-19. Expiration date is optional but including it can help the issuer's validation. * Tokenized PAN = Numeric, length 16. Expiration date is required. If you provide a Visa token, you must also provide the Visa-provided Merchant Verification Value (MVV) in the `transferAcceptor.merchantVerificationValue` field. Otherwise, you will get an error message indicating a missing field, for example: * JSON ```JSON "accountDetails": { "account": { "type": "PAN", "number": 5432231452673894, "expiry": "2050-10", "cvc": 123 }, ... }, "transferAcceptor": { "merchantVerificationValue": "9000899911" ... }, ... ``` ## Names {#names} The `name` object identifies the account holder's name to validate: * JSON ```JSON "name": { "firstName": "Jane", "middleName": "Michelle", "lastName": "Candy-Smith" } ``` If your app collects the full name using one field, it needs to split the name value into the separate `name` fields. The middle name is optional. When validating Mastercard accounts, the `middleName` value is truncated to one character when sent to the Mastercard Network. For example, 'Michelle' becomes 'M'. If the first name is not collected, provide the value '#NOFIRSTNAME' for `firstName`. If the last name is not collected, provide the value '#NOLASTNAME' for `lastName`. ### Business names {#business-names} If your app collects the business name using one field, we recommend providing the name in the `firstName` and `lastName` fields as shown in this table: | Business name | First name | Last name | |-------------------|------------|---------------| | XYZ | XYZ | XYZ | | XYZ International | XYZ | International | | XYZ DBA MA | XYZ | DBA MA | For example, the business name 'James Vinyl Importers' would be: * JSON ```JSON "name": { "firstName": "James", "lastName": "Vinyl Importers" } ``` ## Country and Subdivision Codes {#country-and-subdivision-codes} Countries are specified using a 3-character [ISO 3166-1 alpha-3 country code](https://www.iso.org/iso-3166-country-codes.html). For example, the United States of America is `USA`. For a list of codes, refer to [Country Codes](https://developer.mastercard.com/mastercard-send/documentation/implementation/country-codes/). Country subdivisions (states or provinces) are specified as an ISO 3166-2 alphanumeric 2 or 3 character country subdivision code. For example, Missouri is `MO`. ## Currency Codes {#currency-codes} Currencies are specified using a 3-character [ISO 4217 alpha-3 currency code](https://www.iso.org/iso-4217-currency-codes.html). For example, US Dollars is USD. For a list of codes, refer to [Currency Codes](https://developer.mastercard.com/mastercard-send/documentation/implementation/currency-codes/). For amounts, the decimal point is implied based on the relevant currency exponent. For example, a US Dollar $10 amount is a value of `1000`. ## Date and Time Formats {#date-and-time-formats} The local date and time of the transaction is specified in [ISO 8601 extended format](https://www.iso.org/iso-8601-date-and-time-format.html): YYYY-MM-DDThh:mm:ss. For example, the 17th June 2021 at 6pm, 5 minutes and 2 seconds is `2021-06-17T18:05:02`.