# Account Validation API source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/account-validation-apis/account-validation-api/index.md Alert: If you are an Originating Institution contracted with MTS EU or MTS UK, please proceed to [Account Validation API specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/account-validation-apis/psd2-eu-account-validation-apis/index.md) and [Account Validation API specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/account-validation-apis/psd2-uk-account-validation-apis/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). ## Environment Domains {#environment-domains} * Sandbox/MTF * Production ```Sandbox/MTF https://sandbox.api.mastercard.com/send/partners/{partner_id}/crossborder/accounts/validations ``` ```Production https://api.mastercard.com/send/partners/{partner_id}/crossborder/accounts/validations ``` ## API Specification {#api-specification} [**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/bank_account_validation_swagger_V2.yaml) ### Account Validation API {#account-validation-api}
The Account Validation API is a feature within Account Validation Services which allows Customers to validate Recipient account information before submitting payment to Cross-Border Services.
Customers deciding to code to this API will receive successful or rejection responses based on Receiving Account data provided for a specific corridor. This API functionality has been expanded to provide additional services including: * IBAN Validation Service -- Customers can validate account format and structure of an IBAN value provided for payload instruction. * Card Eligibility Service -- Customers can validate debit or credit card account number format and structure. In addition, customers can receive payload feedback if an account can support cross-border transactions. * Account Status Verification -- Customers can verify the following elements of an account used for bank deposit services: * Account Number * Account Owner Name * Account Status
Please note, while Cross-Border Services provide account validation and verification services to help customers verify recipient account information; this does not guarantee payment transactions will be accepted or processed at the recipient's financial institution. The financial institution hosting the Recipient's account can reject or return funds to the sending institution for various reasons outside of Mastercard control. API Reference: `GET /{partner_id}/crossborder/accounts/validations` ##### Account Validation Push Notification {#account-validation-push-notification} Customers deciding to code for Account Status Verification and Card Eligibility Service functionalities will receive a push notification once Account Validation API processing finishes if an IN_PROGRESS status was initially received. API Reference: `GET /webhooks`

## 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. The different statuses for the Account Validation API are as follows: | Status | Description | |-------------|--------------------------------------------------------------------------------------| | IN_PROGRESS | The Request has been received successfully and is under progress. | | SUCCESS | The Request has been processed successfully with final response. | | FAILURE | The Request has failed due to errors like API syntax mismatch or Field length error. | ## Payload Encryption {#payload-encryption} All payload request sent to and from Cross-Border Services are encrypted. 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} Alert: For the Validation Services 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. Please note that the Sandbox Testing is unavailable for Req Type = "ASV" #### *Account Validation API* {#_account-validation-api_} | Status | Test Case | Request Payload | |---------|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | Valid | Account (IBAN) is successfully verified. | { "accountUri": { "type": "IBAN", "value": "FR070331234567890123456" } } | | Valid | Valid PAN eligible for cross border | { "requestType":"CES", "accountUri": { "type": "PAN", "value": "4000340000000515" } } | | Valid | Valid PAN not eligible for cross border | { "requestType":"CES", "accountUri": { "type": "PAN", "value": "2000000000000014" } } | | Invalid | Account (IBAN) not verified because data provided is insufficient | Send the request where AccountUri.value is null { "accountUri": { "type": "IBAN", "value": "" } } | | Invalid | Account (IBAN) not verified because check digit in IBAN is invalid | Send the below request where AccountUri.value should end with 'ER00102' { "accountUri": { "type": "IBAN", "value": "GB83NWBK60161ER00102" } } | | Invalid | Account (IBAN) is not verified because country is not supported for this service | Send the below request where AccountUri.value should end with 'ER00113' { "accountUri": { "type": "IBAN", "value": "BJ66BJ061010010014439ER00113" } } | ## Sample Request {#sample-request} ### 1. IBAN Validation Service {#1-iban-validation-service} * JSON ```JSON { "accountUri": { "type": "IBAN", "value": "FR070331234567890123456" } } ``` ### 2. Card Eligibility Service {#2--card-eligibility-service} * JSON ```JSON { "requestType": "CES", "accountUri": { "type": "PAN", "value": "4000340000000515" } } ``` ### 3. Account Status Verification {#3-account-status-verification} ```json { "requestType": "ASV", "accountUri": { "type": "BAN", "value": "98000987651232" }, "accountDetails": { "accountHolder": { "name": { "firstName": "John", "middleName": "Adam", "lastName": "Smith" } }, "bic": { "value": "123456789", "type": "ABA" } } } ``` ## Sample Response {#sample-response} ### 1. Successful IBAN Account Validation Response: {#1-successful-iban-account-validation-response} * JSON ```JSON { "status": "SUCCESS", "message": "Valid IBAN Structure", "accountMatch": { "accounts": { "account": [ { "type": "IBAN", "value": "FR070331234567890123456" }, { "type": "BAN", "value": "30007999990424173200040" } ] }, "bank": { "bic": { "type": "SWIFT BIC", "value": "NATXFRPP" }, "name": "Natixis", "branchName": "", "branchCode": "3000799999", "address": { "line1": "30 Av Pierre Mendes-France", "city": "Paris", "postalCode": "75013", "country": "FRA" } } } } ``` ### 2. Successful Card Eligibility Service response: {#2-successful-card-eligibility-service-response} * JSON ```JSON { "status": "SUCCESS", "refId": "e5c6e10f-7d7d-4f69-8f7a-80be8ead68c3", "message": "Valid PAN", "accountMatch": { "accounts": { "account": [ { "type": "PAN", "value": "4000340000000515" } ] }, "bank": { "name": "Cassa di Risparmio di Bolzano SpA", "address": { "country": "ITA" } } }, "receivingEligibility": { "crossBorder": { "eligible": "Y", "fasterFunds": "Y" }, "paymentSystem": "MASTERCARD", "product": "Credit", "status": "ELIGIBLE" } } ``` ### 3. Account Status Verification Service response: {#3-account-status-verification-service-response} API Status: In Progress ```json { "requestType": "ASV", "accountUri": { "type": "BAN", "value": "98000987651232" }, "accountDetails": { "accountHolder": { "name": { "firstName": "John", "middleName": "Adam", "lastName": "Smith" } }, "bic": { "value": "123456789", "type": "ABA" } } } ``` ### 4. Account Status Verification Service response: {#4-account-status-verification-service-response} API Status: Success ```json { "requestType": "ASV", "accountUri": { "type": "BAN", "value": "98000987651232" }, "accountDetails": { "accountHolder": { "name": { "firstName": "John", "middleName": "Adam", "lastName": "Smith" } }, "bic": { "value": "123456789", "type": "ABA" } } } ``` ### 5. Rejected account validation response for missing mandatory fields. {#5-rejected-account-validation-response-for-missing-mandatory-fields} * JSON ```JSON { "Errors": { "Error": [ { "RequestId": "1710", "Source": "accountUri.value", "ReasonCode": "MISSING_REQUIRED_INPUT", "Description": "Missing Required Input", "Recoverable": "false", "Details": { "Detail": [ { "Name": "ErrorDetailCode", "Value": "092000" } ] } } ] } } ``` ### 6. Rejected account validation response for invalid check digit. {#6-rejected-account-validation-response-for-invalid-check-digit} * JSON ```JSON { "Errors": { "Error": [ { "RequestId": "1711", "Source": "", "ReasonCode": "INVALID_CHECK_DIGIT", "Description": "Invalid check digit", "Recoverable": "false", "Details": { "Detail": [ { "Name": "ErrorDetailCode", "Value": "130308" } ] } } ] } } ``` ## Error Codes {#error-codes} Please refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md). For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).