# Address Validation API (Compliant with Payment Services Directive for UK customers) source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-address-validation-api/index.md 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. ## API {#api} [**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/address_validation_service_uk_swagger.yaml) For further information on URL/ Input Parameter restrictions, please take a look at [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md). 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. ## Endpoints {#endpoints} * Sandbox URL: * MTF URL: * Production URL: ## 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 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} 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: {#successful-response} * 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" } } ``` #### 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" } } } } } ```