# API Reference
source: https://developer.mastercard.com/account-validation/documentation/api-reference/index.md

For each validation request (transaction), generate a unique Reference ID (6-40 characters, alphanumeric and \* , - . _ \~ allowed) and provide it as the `referenceId` in the POST request. If the request is successful, the API response includes a unique system-generated ID (`id`).

## Environment Domains {#environment-domains}

In January 2026, we introduced the following new RNTZ (Regional Network Transit Zone) domains for this API. New customers should use these domains. Existing customers are encouraged to migrate soon.
* Sandbox
* MTF
* Production

```Sandbox
https://sandbox.api.move.mastercard.com/common
```

```MTF
https://mtf.api.move.mastercard.com/common
```

```Production
https://api.move.mastercard.com/common
```

* Sandbox
* MTF
* Production

```Sandbox
https://sandbox.api.mastercard.com/common
```

```MTF
https://mtf.api.mastercard.com/common
```

```Production
https://api.mastercard.com/common
```

To form the full endpoint URL, combine the appropriate domain portion (shown above) with the path portion shown by the OpenAPI specification (see below).
Note: The non-RNTZ domains will remain active for this API at this time. Any plans to decommission them will be communicated in the API release notes and here. Some parts of this documentation may still show the non-RNTZ domains and will be updated soon.

## APIs {#apis}

The APIs support JSON requests and responses. We recommend you log the Correlation ID (correlation-id) response header value for tracking purposes. When seeking support, providing the relevant Correlation ID may help resolve your inquiry more quickly.

In the expandable sections below, **Request URI** shows the example API path based on the selected server (domain). To select another server, click the server name above the example path.

The `Partner-Id` header value makes the request unique to a registered partner:

* Sandbox API: Use any ID of valid length (32-40 characters), e.g. `ptnr_1lzs0zD6uWo7k-OdUXjLW_pFgX2`
* MTF and Production APIs: Use the Partner Reference ID you receive when you register to use these APIs

The API specification shows unencrypted request body payloads.

Payload encryption is optional. To use it for MTF and Production, you must request enablement when Mastercard onboards your configuration preferences, and you must provide the `X-Encrypted` = 'true' header with your encrypted request payloads, see [API Basics](https://developer.mastercard.com/account-validation/documentation/api-basics/index.md). When API requests are encrypted, success (200) responses also have encrypted payloads. The Sandbox API does not support payload encryption.

For guidance on the API specification's **Execute** button, see [Sandbox Testing](https://developer.mastercard.com/account-validation/documentation/api-reference/index.md#sandbox-testing).
Tip: Guidance for the API sections below:
The expandable API sections below are rendered from the API specification, which you can download using **Download spec**.

Each API call type is a section. Expand it to see the request parameters and example JSON body payload and/or example response for that call. There may be multiple examples, which may not show all possible fields. If so, select **All fields** to see the possible fields:

![Example selections](https://static.developer.mastercard.com/content/account-validation/documentation/images/example-selection-av.png)

To see the field descriptions, click **Model** and expand the object/array blocks to show their contents.

**Request URI** shows the call's endpoint path based on the selected environment (for example, Sandbox URL).

You can edit the example payload. Switching to the Model view will reset the payload to the default example.
The API specification identifies the required (mandatory) API fields as per Mastercard API validation and systems. In the expandable sections below, these fields are indicated as follows:

* REQUIRED indicates a required parameter, for example:

![Required parameter](https://static.developer.mastercard.com/content/account-validation/documentation/images/required-param-av.png)

* In the **Model** section, a red asterisk \* indicates a required object/array and **required: yes** indicates a required item, for example:

![Required item](https://static.developer.mastercard.com/content/account-validation/documentation/images/required-item-av.png)

If an item is marked as required but its parent object/array is not, you only need to provide that item if you provide the parent.

The required indicator relates to general API validation. Some conditional fields might be required depending on the payment type, region, and so on. Some of the other optional fields might also be required as per program or network rules.

API Specification: `https://static.developer.mastercard.com/content/account-validation/swagger/account-validation-api-swagger.yaml`

## Sandbox Testing {#sandbox-testing}

To try this API quickly, use the **Execute** button (in the expandable section above) to send requests directly from your browser to the Sandbox, without needing to create a Mastercard Developers project and keys. This functionality will send the shown Request parameters and Body payload, which you can alter, and the response will appear in a **Server Response** tab.

You can also make API calls to the Sandbox server from an API tool or your application code or the [tutorials](https://developer.mastercard.com/account-validation/documentation/tutorials-and-guides/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required OAuth 1.0a Authorization Header.

The Sandbox server returns simulated responses. For testing guidance, see [Testing](https://developer.mastercard.com/account-validation/documentation/testing/index.md).

## Sample Requests and Responses {#sample-requests-and-responses}

These are examples of unencrypted payloads for successful messages. For information on status values and error messages, see [Code and Formats](https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md).
**Sandbox URL:** https://sandbox.api.move.mastercard.com/common/account-validations  
**MTF URL:** https://mtf.api.move.mastercard.com/common/account-validations  
**Production URL:** https://api.move.mastercard.com/common/account-validations

### Mastercard card {#mastercard-card}

* JSON

```JSON
{
  "referenceId": "avs_0000001",
  "accountDetails": {
    "account": {
      "type": "PAN",
      "number": "5102589999999913",
      "expiry": "2050-10",
      "cvc": "123"
    },
    "name": {
      "firstName": "Jane",
      "middleName": "Michelle",
      "lastName": "Candy-Smith"
    }
  },
  "currency": "USD",
  "transactionLocalDateTime": "2021-06-17T18:05:02",
  "acquiringCredentials": {
    "country": "USA",
    "singleMessage": {
      "processorId": "9000001957",
      "acquiringIdentificationCode": "123456780"
    }
  }
}
```

### Mastercard card, mononym {#mastercard-card-mononym}

* JSON

```JSON
{
  "referenceId": "avs_0000001",
  "accountDetails": {
    "account": {
      "type": "PAN",
      "number": "5102589999999913",
      "expiry": "2050-10",
      "cvc": "123"
    },
    "name": {
      "firstName": "Seal",
      "lastName": "#NOLASTNAME"
    }
  },
  "currency": "USD",
  "transactionLocalDateTime": "2021-06-17T18:05:02",
  "acquiringCredentials": {
    "country": "USA",
    "singleMessage": {
      "processorId": "9000001957",
      "acquiringIdentificationCode": "123456780"
    }
  }
}
```

### Visa card, business name {#visa-card-business-name}

* JSON

```JSON
{
  "referenceId": "avs_0000001",
  "accountDetails": {
    "account": {
      "type": "PAN",
      "number": "4007589999999904",
      "expiry": "2050-10",
      "cvc": "123"
    },
    "name": {
      "firstName": "James",
      "lastName": "Vinyl Store"
    }
  },
  "currency": "USD",
  "transactionLocalDateTime": "2021-06-17T18:05:02",
  "acquiringCredentials": {
    "country": "USA",
    "singleMessage": {
      "processorId": "9000001957",
      "acquiringIdentificationCode": "123456780"
    }
  }
}
```

### Visa token {#visa-token}

Note that `transferAcceptor.merchantVerificationValue` is required for Visa tokens. Otherwise, you will get an error message indicating a missing field.
* JSON

```JSON
{
  "referenceId": "avs_0000001",
  "accountDetails": {
    "account": {
      "type": "PAN",
      "number": "5432231452673894",
      "expiry": "2050-10",
      "cvc": "123"
    },
    "name": {
      "firstName": "Jane",
      "lastName": "Smith"
    }
  },
  "currency": "USD",
  "transactionLocalDateTime": "2021-06-17T18:05:02",
  "transferAcceptor": {
    "address": {
      "city": "O'Fallon",
      "country": "USA",
      "postalCode": "23233",
      "state": "MO",
      "street": "2200 Mastercard Blvd"
    },
    "id": "456487898368",
    "name": "Acme Transfer Co",
    "terminalId": "1367-hgf",
    "merchantVerificationValue": "9000899911"
  },
  "acquiringCredentials": {
    "country": "USA",
    "singleMessage": {
      "processorId": "9000001957",
      "acquiringIdentificationCode": "123456780"
    }
  }
}
```

The responses for Mastercard and Visa accounts are slightly different, as shown below.

### CVC/CVV and name matched {#cvccvv-and-name-matched}

* Mastercard
* Visa

```Mastercard
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "MATCHED",
    "responseCode": "M",
    "responseCodeDescription": "CVC2/CSC match"
  },
  "nameValidationResults": {
    "status": "MATCHED"
  }
}
```

```Visa
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "MATCHED",
    "responseCode": "M",
    "responseCodeDescription": "CVV2 match"
  },
  "nameValidationResults": {
    "status": "MATCHED",
    "firstNameStatus": "MATCHED",
    "middleNameStatus": "MATCHED",
    "lastNameStatus": "MATCHED"
  }
}
```

### CVC/CVV and name not matched {#cvccvv-and-name-not-matched}

* Mastercard
* Visa

```Mastercard
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "NOT_MATCHED",
    "responseCode": "N",
    "responseCodeDescription": "CVC2/CSC no match"
  },
  "nameValidationResults": {
    "status": "NOT_MATCHED"
  }
}
```

```Visa
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "NOT_MATCHED",
    "responseCode": "N",
    "responseCodeDescription": "CVV2 does not match"
  },
  "nameValidationResults": {
    "status": "NOT_MATCHED",
    "firstNameStatus": "NOT_MATCHED",
    "middleNameStatus": "NOT_MATCHED",
    "lastNameStatus": "NOT_MATCHED"
  }
}
```

### CVC/CVV and name not verified {#cvccvv-and-name-not-verified}

* Mastercard
* Visa

```Mastercard
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "NOT_VERIFIED",
    "responseCode": "S",
    "responseCodeDescription": "CVC2/CSC is on the card, but the merchant has indicated that CVC2/CSC is not present"
  },
  "nameValidationResults": {
    "status": "NOT_VERIFIED"
  }
}
```

```Visa
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "NOT_VERIFIED",
    "responseCode": "S",
    "responseCodeDescription": "CVV2 should be on the card, but the merchant indicates that it is not"
  },
  "nameValidationResults": {
    "status": "NOT_VERIFIED"
  }
}
```

### Name partial matched {#name-partial-matched}

* Mastercard
* Visa

```Mastercard
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "MATCHED",
    "responseCode": "M",
    "responseCodeDescription": "CVC2/CSC match"
  },
  "nameValidationResults": {
    "status": "PARTIAL_MATCHED"
  }
}
```

```Visa
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "MATCHED",
    "responseCode": "M",
    "responseCodeDescription": "CVV2 match"
  },
  "nameValidationResults": {
    "status": "PARTIAL_MATCHED",
    "firstNameStatus": "NOT_MATCHED",
    "middleNameStatus": "MATCHED",
    "lastNameStatus": "MATCHED"
  }
}
```

### Name not supported {#name-not-supported}

* Visa only

```Visa only
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "00",
  "networkResponseCodeDescription": "Approved or completed successfully",
  "cvcValidationResults": {
    "status": "MATCHED",
    "responseCode": "M",
    "responseCodeDescription": "CVV2 match"
  },
  "nameValidationResults": {
    "status": "NOT_SUPPORTED"
  }
}
```

### Invalid account {#invalid-account}

Card account does not exist. The `networkResponseCode` and `networkResponseCodeDescription` values may differ from those shown below, see [Invalid accounts and other problems](https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md#invalid-accounts-and-other-problems):
* Both

```Both
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "78",
  "networkResponseCodeDescription": "Invalid/nonexistent account specified (general)",
  "nameValidationResults": {
    "status": "NOT_VERIFIED"
  }
}
```

### Declined validation {#declined-validation}

Card issuer declines validation request:
* Both

```Both
{
  "referenceId": "avs_0000001",
  "id": "34c6b3f3-54d7-4257-a638-0c010b50ea05",
  "networkResponseCode": "05",
  "networkResponseCodeDescription": "Do not honor",
  "nameValidationResults": {
    "status": "NOT_VERIFIED"
  }
}
```