# Code and Formats source: https://developer.mastercard.com/mastercard-send-avs/documentation/code-and-formats/index.md ## Status Values {#status-values} When an account is checked successfully, the response message (200 status code) will include status values (`address_status`, `postal_code`, and `cvc_status`), for example: * JSON * XML ```JSON ... "address_status": "MATCHED", "postal_code_status": "NOT_MATCHED", "cvc_status": "NOT_VERIFIED", ... ``` ```XML ... MATCHED NOT_MATCHED NOT_VERIFIED ... ``` The status values will be MATCHED, NOT_MATCHED, or NOT_VERIFIED, depending on the values returned by the card issuer. NOT_VERIFIED could be returned when the item (e.g. CVC/CVV) was not supplied in the API request or verification information is not available. Your systems will need to use these status values to determine whether to proceed with a transfer. The other values (`avs_response_code`, `avs_response_desc`, `cvc_resp_code`, and `cvc_resp_desc`) are from the card issuer or address verification system, and they are provided for completeness. However, we do not list those values because they have already been translated into the status values and they are subject to change. ## Error Codes {#error-codes} If your API request is unsuccessful, you should receive a service error response or a gateway error response. ### Service Error Codes {#service-error-codes} Service error response messages (4xx status code) have the following structure (example values shown). The `Error` array may contain multiple error items. * JSON * XML ```JSON { "Errors": { "Error": [ { "RequestId": "rqst_73HB-5RO5-0OGS-53SG", "Source": "account_uri", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "Invalid Account URI", "Recoverable": "false", "Details": { "Detail": [ { "Name": "ErrorDetailCode", "Value": "082000" } ] } } ] } } ``` ```XML rqst_73HB-5RO5-0OGS-53SG account_uri INVALID_INPUT_VALUE Invalid Account URI false
ErrorDetailCode 082000
``` | Field | Description | |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | RequestId | A service-specific request identifier. Example: rqst_73HB-5RO5-0OGS-53SG | | Source | The unique identifier that attempts to define the field in error, when available. If an error is not associated with a specific field, 'System' is returned. If an error is produced because of required data, the field missing data is presented. Examples: amount, account_uri | | ReasonCode | The general cause of the error; see the table below. Examples: INVALID_INPUT_FORMAT, INVALID_INPUT_LENGTH, INVALID_INPUT_VALUE | | Description | A textual description of the error; see the table below. This is optional and will only be displayed if more information is available than is stored in the data identifier and reason code. Examples: Invalid Account URI, Destination Currency ISO code must be within 3 characters length | | Recoverable | A true/false indicator stating 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 (5xx response code) might be successful when re-sent. Valid values: true, false | | Details | Each Open API service has an option to add extra service-specific error information in the Details section. The details are optional and might not be present for every error message. If present, the details are returned in the form of individual detail items, each containing a Name and Value pair: * The Name element will explain what data you will find in the Value element. Example: ErrorDetailCode * The Value element will hold the actual data. Valid values shown in the table below. Example: 082000 | The following table shows the `ErrorDetailCode`, `ReasonCode` and `Description` values that can be returned. Other values might also exist or be introduced periodically. | Error Detail Code | Reason Code | Reason Description | How to Resolve | |-------------------|------------------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 050007 | AUTHORIZATION_FAILED | Unauthorized access | Check you are using the correct key, Consumer Key (which identifies the key), and Partner Reference ID (for the `partnerId` part of the endpoint URL) for the API environment. If you recently created your key, you must ask Mastercard to set up the environment for your key and Consumer Key. | | 062000 | INVALID_INPUT_FORMAT | Value contains invalid character | Correct the value in the field shown by `Source`. For the `account_uri` field, it could be that part of the URI is the wrong length or missing; see [Account URIs](https://developer.mastercard.com/mastercard-send-avs/documentation/code-and-formats/index.md#account-uris). | | 072000 | INVALID_INPUT_LENGTH | Invalid length | Correct the length of the value in the field shown by `Source`. | | 082000 | INVALID_INPUT_VALUE | Invalid value | Correct the value in the field shown by `Source`. For the `account_uri` field, it could be that the card account is invalid or part of the URI is incorrect, for example wrong CVC or expiration date (e.g. not a future date). | | 092000 | MISSING_REQUIRED_INPUT | Value is required | Provide the field shown by `Source`. If you provided a Visa token, it could be that the `merchant_verification_value` field is missing (it is required for Visa tokens). | | 110510 | RESOURCE_ERROR | Invalid Request | Check that your API request is correctly formatted and that the headers match the format (JSON or XML). | | 110511 | RESOURCE_ERROR | Operation not allowed | Check that you are making the correct type of API request: POST. | | 110515 | RESOURCE_ERROR | Multiple resources found | If this error occurs for a field where you have used a Consumer Mapping ID, it likely means that Mastercard Send has found multiple Consumer Mapping account records relating to that ID. See the Consumer Mapping service documentation for guidance on setting defaults. | | 110516 | RESOURCE_ERROR | Country not supported for merchant | Your implementation is not configured to support this country. | | 130001 | DECLINE | Card declined | This card account cannot be used. | | 130002 | DECLINE | Fraud detected | This card account cannot be used. | | 130003 | DECLINE | Card expired | This card account cannot be used. | ### Gateway Error Codes {#gateway-error-codes} Error codes can also be returned by Mastercard's gateway, which is used to verify your request's signature and route the request to the correct location. Gateway error response messages (4xx/5xx status code) have the following structure: * JSON * XML ```JSON { "Errors": { "Error": [ { "Source": "Gateway", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": null } ] } } ``` ```XML Gateway Unique code Description of the error true/false
null
 ``` For a list of the errors returned by our gateway, as well as resolutions to each, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/errors-troubleshooting/gateway-error-codes/). ## Account URIs {#account-uris} This table provides guidance for specifying an Account URI. | Scheme | Scheme Specific Data | |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | pan | Specifies a card account number (PAN) or tokenized PAN. If you provide a Visa token, see also [Merchant Verification Value (MVV)](https://developer.mastercard.com/mastercard-send-avs/documentation/code-and-formats/index.md#merchant-verification-value-mvv). Data format: {PAN/tokenized PAN}\[;exp=YYYY-MM\]\[;cvc=NNNN\] Where: * PAN = numeric, length 11-19 * Tokenized PAN = numeric, length 16 * The square brackets indicate optional elements: expiration date \[;exp=YYYY-MM\] and Card Verification Code (CVC) \[;cvc=NNNN\] * For PANs, expiration date is optional but including it can improve approval rates * For tokenized PANs, expiration date is required
PAN examples: * pan:5102589999999913 * pan:5102589999999913;exp=2077-08 * pan:5102589999999913;cvc=123 * pan:5102589999999913;exp=2077-08;cvc=123
Tokenized PAN examples: * pan:5432231452673894;exp=2077-08 * pan:5432231452673894;exp=2077-08;cvc=123 | | acct-token | **For use with the Lightbox service.** Specifies a Lightbox token, which is a temporary system identifier generated by the Lightbox secure card capture service and returned as part of the capture response. This token has a lifespan of 30 minutes and should not be used as a permanent account identifier. **NOTE:** The Account Verification Service cannot check the CVC because it cannot be stored on file and so it is not part of the tokenized information. Data format: 1-NN character alphanumeric Example: acct-token:suZz18lhAFvx9LQa6U2VMxs0BJLAD_TXVzYvaqTsjcG_AImuzmvNXQ | | sds-acct-id | **For use with the Consumer Mapping service.** Specifies the system-generated Account ID of an Account record in the Consumer Mapping service. The ID was returned by the service when the Account was registered/created. The ID can be used as an alias to initiate a payment from/to that account. Data format: alphanumeric special \[a-zA-Z0-9_-\], maximum length 32 Example: sds-acct-id:acct_MSIL0iiUEU1V_ISouEU4eVNi_4e | | sds-acct-ref | **For use with the Consumer Mapping service.** Specifies the partner-provided Account Reference of an Account record in the Consumer Mapping service. The reference was provided to the service when the Account was registered/created. The reference can be used as an alias to initiate a payment from/to that account. Data format: alphanumeric special \[a-zA-Z0-9\*,-._\~\], length 6-40 Example: sds-acct-ref:acc_334631673134562097381451433476935676 | | acct-ref | **For use with the Account Mapping service or legacy v1 Consumer Mapping service.** Specifies the partner-provided account reference identifier of an Account record in either the Account Mapping service or the Consumer Mapping service. The ID was provided to the service when the Account was registered/created. Data format: 1-NN character alphanumeric Example: acct-ref:user1234acct1 | | id | **For use with the legacy v1 Consumer Mapping service.** Specifies the system-generated Account ID of an Account record in the Consumer Mapping service. The ID was returned by the service when the Account was registered/created. Data format: NN character alphanumeric Example: id:o56b7x2jlq6u1avloma1 | ## Merchant Verification Value (MVV) {#merchant-verification-value-mvv} If you submit an AVS request for a Visa token, you must provide the Visa-provided Merchant Verification Value (MVV) in the `merchant_verification_value` field. Otherwise, you will get an error message indicating a missing field. ## ISO Country and Subdivision Codes {#iso-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`.