# Address Validation API source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/address-validation-api/index.md Alert: If you are an Originating Institution contracted with MTS EU or MTS UK, please proceed to [Address Validation API Specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-address-validation-api/index.md) and [Address Validation API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-address-validation-api/index.md) respectively to ensure compliance with the relevant jurisdiction based Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2). The Address Validation Service is an optional service which customers can use to confirm the validity of an address before sending a transaction to Mastercard Cross-Border Services. Address validations with successful responses will return country specific address structure to be used for transactions. List of supported countries will be maintained and activated for Mastercard Cross-Border Services. Mastercard Cross-Border Services will activate the usable countries. If the country is not in the usable list, any requests for that country will be rejected. The first country activated is United States. ## Environment Domains {#environment-domains} * Sandbox * Production ```Sandbox https://sandbox.api.mastercard.com/send/address-validation-service/addresses/validations ``` ```Production https://api.mastercard.com/send/address-validation-service/addresses/validations ``` ## API {#api} [**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/address_validation_service_swagger.yaml) API Reference: `GET /send/address-validation-service/addresses/validations` * **Formats supported** : JSON * **HTTP Version**: 1.0/ 1.1 * **Required HTTP header parameters** : content-type : Format of the inbound content being submitted. example: application/json accept: Format of the inbound content being submitted. example: application/json X-Mc-Correlation-Id : A unique correlation ID for tracking the request. Partner-Ref-Id : A unique reference ID of the business partner. ## API Convention {#api-convention} Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines. ## Payload Encryption {#payload-encryption} All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by Mastercard. For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md) ## Sandbox Testing {#sandbox-testing} You can make API calls to the Sandbox server from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required OAuth 1.0a Authorization Header. Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID. Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID. For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to originating institutions; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Originating Institution. ### Sandbox Test cases {#sandbox-test-cases} Alert: For the Address Validation Service all requests initiated in the Sandbox/MTF url must use the test cases specified in the following table. Please limit your testing requirements only to test cases available below. The Sandbox server returns simulated, static responses. You can use the following test cases to produce specific responses. | Status | Verification | Test Case | Request Payload | |---------|--------------------|-----------------------------------------------|------------------------------------------------------------------| | Valid | Verified | Valid address | "Address": "4 CLARK STREET, EVERETT, MA, 02149","Country": "US" | | Valid | Partially Verified | Valid address, but partially verifiable | "Address": "420 MONTGOMERY ST. SF CA","Country": "US" | | Invalid | Unverified | Invalid address because it cannot be verified | "Address": "420 MAIN","Country": "US" | | Invalid | Ambiguous | Invalid address because it is ambiguous | "Address": "7151 45TH SEATTLE WA","Country": "US" | | Valid | Verified | Valid address | "Address": "4 CLARK STREET, EVERETT, MA, 02149","Country": "USA" | | Valid | Partially Verified | Valid address, but partially verifiable | "Address": "420 MONTGOMERY ST. SF CA","Country": "USA" | | Invalid | Unverified | Invalid address because it cannot be verified | "Address": "420 MAIN","Country": "USA" | | Invalid | Ambiguous | Invalid address because it is ambiguous | "Address": "7151 45TH SEATTLE WA","Country": "USA" | ## Sample Request {#sample-request} * JSON ```JSON { "country": "USA", "address": "4 CLARK STREET, EVERETT" } ``` ## Sample Response {#sample-response} ### Successful Response: Below are samples for some of the successful responses. {#successful-response-below-are-samples-for-some-of-the-successful-responses} #### a) Valid Address sample {#a-valid-address-sample} * JSON ```JSON { "status": "VALID", "verification": "VERIFIED", "addressMatch": { "address": "4 Clark St,Everett MA 02149-2015", "line1": "4 Clark St", "line2": "Everett MA 02149-2015", "line3": "", "country": "USA", "countrySubdivision": "MA", "city": "Everett", "streetName": "Clark St", "buildingNumber": 4, "postalCode": "02149-2015" } } ``` #### b) Partially verifiable Address sample {#b-partially-verifiable-address-sample} * JSON ```JSON { "status": "VALID", "verification": "PARTIALLY VERIFIED", "addressMatch": { "address": "420 Montgomery St,Santa Fe CA", "line1": "420 Montgomery St", "line2": "Santa Fe CA", "country": "USA", "countrySubdivision": "CA", "city": "Santa Fe", "streetName": "Montgomery St", "buildingNumber": "420" } } ``` #### c) Invalid Address sample {#c-invalid-address-sample} Invalid Address cannot be used for Payment Transactions. * JSON ```JSON { "status": "INVALID", "verification": "UNVERIFIED", "addressMatch": { "address": "420 MAIN" } } ``` #### d) Ambiguous Address sample {#d-ambiguous-address-sample} Ambiguous Address cannot be used for Payment Transactions. * JSON ```JSON { "status": "INVALID", "verification": "AMBIGUOUS", "addressMatch": { "address": "7151 45TH SEATTLE WA" } } ``` ### Rejected Response for invalid input value: {#rejected-response-for-invalid-input-value} * JSON ```JSON { "Errors": { "Error": { "RequestId": "5", "Source": "country", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "Invalid input value", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "082000" } } } } } ``` ### Rejected Response for Unauthorized access: {#rejected-response-for-unauthorized-access} * JSON ```JSON { "Errors": { "Error": { "RequestId": "6", "Source": "Partner-Ref-Id", "ReasonCode": "AUTHORIZATION_FAILED", "Description": "Unauthorized Access.", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "050007" } } } } } ``` ### Rejected Response for unprocessable Entity: {#rejected-response-for-unprocessable-entity} * JSON ```JSON { "Errors": { "Error": { "RequestId": null, "Source": "test", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "Invalid Input Value", "Recoverable": "false", "Details": { "Detail": { "Name": "ErrorDetailCode", "Value": "082000" } } } } } ```