# 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. All users of this API service must transition to these domains.
* 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: Mastercard will end support of the non-RNTZ domains for this API service on 31 March 2027, see the [API release notes](https://static.developer.mastercard.com/content/mastercard-send/release-notes/mastercard-send-release-notes-26.2.pdf#page=4).

## 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.

The 'Required' indicator in the API specification relates to general API validation. Other fields may also be required depending on the payment type, region, program rules, or network rules.

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

## Sandbox Testing {#sandbox-testing}

You can 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"
  }
}
```