# Quick Start Guide source: https://developer.mastercard.com/locations/documentation/quick-start-guide/index.md ## Overview {#overview} The ATM Locations API grants users access to Mastercard's extensive ATM data. This tutorial guides you through the process of on-boarding and being able to consume this data. Tip: ###### Postman Collections Quick Start {#postman-collections-quick-start} If you are already ready to start making calls you can head over to our [Postman Collections page](https://developer.mastercard.com/locations/documentation/developer-tools/postman-collection/index.md) to leverage sandbox and production environments without having to write code. > > #### You can follow this guide to learn: {#you-can-follow-this-guide-to-learn} > > * How to create a project for the service. > * How Mastercard approaches authentication. > * How to generate your own API client. > * How to make calls to the Sandbox or Production environment ### Checklist {#checklist} | # | Step | Description | |---|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Access | Create a Mastercard Developers account using your enterprise email id or log in using your existing credentials | | 2 | Project | Create a Mastercard Developers Project \& Get Access to ATM Locations API in sandbox environment | | 3 | First Call | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a credentials | | 4 | Validation | Test the functionality of ATM Locations API in sandbox environment to validate using mocked data, positive flows, and negative flows | | 5 | Production | After Sandbox validation is complete, use the [Onboarding Checklist](https://developer.mastercard.com/locations/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. | ## Step 1: Get Access to Mastercard Developers Platform {#step-1-get-access-to-mastercard-developers-platform} If you haven't done so already, you must first create an account with Mastercard Developers. 1. Go to [Mastercard Developers](https://developer.mastercard.com/account/sign-up) and [log in](https://developer.mastercard.com/account/log-in) or create your account using enterprise email id. 2. To activate your account, open the link sent to your email address and sign in. ## Step 2: Create a Project and Generate Sandbox Credentials {#step-2-create-a-project-and-generate-sandbox-credentials} Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox provides mocked data so that you can validate your integration before requesting Production access. 1. To start, log in to your Mastercard Developers account and go to the [My Projects](https://developer.mastercard.com/dashboard) page. 2. Click **Create new project** from the upper right. ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/my-projects.png) 3. Enter a project name. 4. Indicate whether you are creating the project on behalf of a client. 5. n the *Select at least one API* field, choose **Locations** and click **Proceed** . ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/select-project.png) **Project Credentials** 6. On the Project credentials page, enter a Key alias and Keystore password for your project. Select Proceed. If you have a custom CSR file to use, select Skip this step instead. You'll upload your CSR on your project dashboard after your project is created. ![Oauth](https://static.developer.mastercard.com/content/locations/uploads/quickstart/create-new-project.png) **Additional Credentials** 7. Download your project key zip file containing the .p12 file required for OAuth authentication in Sandbox. 8. Click Open Project ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/create-project-image.avif) **Save the values you will need** 9. In the navigation panel on the left, you also have access to areas where you can get your Sandbox and Production credentials and upload a CSR file for your project. You can also manage your project settings and add other team members to your project ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/sandbox-credentials.png) 10. After you complete this flow, your project page opens. On the project Summary page, you can see the status of your Sandbox and Production access requests: Ready or Not Requested. You can also choose to Request Production access from this page. ### Import sandbox keys {#import-sandbox-keys} Open the zip file you downloaded in the previous steps. Import the Sandbox keys (the .p12 file) according to your specific development environment using the Keystore Password for sandbox, which you downloaded as well. On your project page under CREDENTIALS \> Sandbox, you can find the consumer key that applies to your environment. The consumer key is a 97 character string separated by an exclamation mark. The format is \!\. The Mastercard API Client ID is the first 48 characters of this key (\), which uniquely identifies the API calling user. ## Step 3: Generate Your Own API Client {#step-3-generate-your-own-api-client} 1. Navigate to the API documentation page. 2. Download the API specification (OpenAPI or Swagger). 3. Generate and configure an API client for this API. 4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries). For a detailed step-by-step guide, see [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/). ## Step 4: Make your first Sandbox Request {#step-4-make-your-first-sandbox-request} Once you have Sandbox credentials, make a simple request to confirm that your project is set up correctly. This first-call example uses ATMS Search endpoint, so you can verify access, OAuth signing, and the Sandbox base URL before moving on. For more information about this endpoint, see the [API Reference](https://developer.mastercard.com/locations/documentation/api-reference/index.md). ### Endpoint {#endpoint} API Reference: `POST /searches` **Parameters** ```javascript limit=5 distance=10 distance_unit=MILE ``` **POST Payload** ```json { "longitude" : "-74.013443", "latitude" : "40.712947" } ``` **Expected Response:** A successful call returns a JSON array containing the first 25 records of ATM location records. You should see a response similar to: ```json { "count": 5, "limit": 5, "offset": 0, "total": 12, "atms": [ { "accessFees": "DOMESTIC_AND_INTERNATIONAL", "addressLine1": "7 WORLD TRADE CTR", "atmTerminalId": "AC006309", "availability": "UNKNOWN", "camera": "NO", "countryCode": "USA", "countryName": "UNITED STATES", "countrySubdivisionCode": "NY", "countrySubdivisionName": "NEW YORK", "city": "NEW YORK", "distance": 0.08774582730276924, "distanceUnit": "MILE", "geocodingResult": "S8HPNTSCZA", "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE", "hasSharedDeposit": "NO", "isSurchargeFreeAlliance": "NO", "latitude": "40.713289", "locationName": "CITIBANK", "locationType": "FINANCIAL_INSTITUTION", "longitude": "-74.01183", "owner": "CITIBANK", "postalCode": "10007", "sponsor": "FISERV SOLUTIONS, LLC", "supportsEmv": "SUPPORTS_EMV", "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA", "sponsorICA": "88024", "routeTransactionNumber": "842548238" }, { "accessFees": "UNKNOWN", "addressLine1": "225 LIBERTY ST STE 1", "atmTerminalId": "RA000943", "availability": "UNKNOWN", "camera": "NO", "countryCode": "USA", "countryName": "UNITED STATES", "countrySubdivisionCode": "NY", "countrySubdivisionName": "NEW YORK", "city": "NEW YORK", "distance": 0.08956877019103475, "distanceUnit": "MILE", "geocodingResult": "S8HPNTSCZA", "handicapAccessible": "UNKNOWN", "hasSharedDeposit": "NO", "isSurchargeFreeAlliance": "YES", "latitude": "40.712415", "locationName": "RITE AID", "locationType": "RETAIL_STORE", "longitude": "-74.015002", "owner": "ALLPOINT", "postalCode": "10281", "sponsor": "ALLPOINT NETWORK", "supportsEmv": "SUPPORTS_EMV", "surchargeFreeAllianceNetwork": "ALLPOINT_PREPAID", "sponsorICA": "2000579", "routeTransactionNumber": "840491031" }, { "accessFees": "DOMESTIC_AND_INTERNATIONAL", "addressLine1": "200 VESEY ST 8TH FL", "atmTerminalId": "T309B776", "availability": "BUSINESS_HOURS", "camera": "NO", "countryCode": "USA", "countryName": "UNITED STATES", "countrySubdivisionCode": "NY", "countrySubdivisionName": "NEW YORK", "city": "NEW YORK", "distance": 0.09309857355313111, "distanceUnit": "MILE", "geocodingResult": "S8HPNTSCZA", "handicapAccessible": "IS_HANDICAP_ACCESSIBLE", "hasSharedDeposit": "NO", "isSurchargeFreeAlliance": "NO", "latitude": "40.71393", "locationName": "CITY NATIONAL BANK", "locationType": "FINANCIAL_INSTITUTION", "longitude": "-74.014658", "owner": "0309-CITY NATIONAL BANK", "postalCode": "10281", "sponsor": "FIDELITY INFORMATION SERVICES, INC.", "supportsEmv": "SUPPORTS_EMV", "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA", "sponsorICA": "88109", "routeTransactionNumber": "124312535" }, { "accessFees": "DOMESTIC", "addressLine1": "185 GREENWICH ST UNIT LL5107", "atmTerminalId": "NY2132", "availability": "BUSINESS_HOURS", "camera": "NO", "countryCode": "USA", "countryName": "UNITED STATES", "countrySubdivisionCode": "NY", "countrySubdivisionName": "NEW YORK", "city": "NEW YORK", "distance": 0.09650006934863571, "distanceUnit": "MILE", "geocodingResult": "S8HPNTSCZA", "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE", "hasSharedDeposit": "NO", "isSurchargeFreeAlliance": "NO", "latitude": "40.713359", "locationName": "ONE WORLD TRADE CENTER", "locationType": "FINANCIAL_INSTITUTION", "longitude": "-74.011683", "owner": "JPMORGAN CHASE", "postalCode": "10007", "sponsor": "JPMORGAN CHASE BANK, N.A.", "supportsEmv": "SUPPORTS_EMV", "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA", "sponsorICA": "5883", "ownerICA": "5883", "routeTransactionNumber": "840605018" }, { "accessFees": "DOMESTIC", "addressLine1": "185 GREENWICH ST", "atmTerminalId": "NY2505", "availability": "ALWAYS_AVAILABLE", "camera": "NO", "countryCode": "USA", "countryName": "UNITED STATES", "countrySubdivisionCode": "NY", "countrySubdivisionName": "NEW YORK", "city": "NEW YORK", "distance": 0.09650006934863571, "distanceUnit": "MILE", "geocodingResult": "S8HPNTSCZA", "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE", "hasSharedDeposit": "NO", "isSurchargeFreeAlliance": "NO", "latitude": "40.713359", "locationName": "WORLD TRADE CENTER - REMOTE ATMS", "locationType": "OTHER", "longitude": "-74.011683", "owner": "JPMORGAN CHASE", "postalCode": "10007", "sponsor": "JPMORGAN CHASE BANK, N.A.", "supportsEmv": "SUPPORTS_EMV", "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA", "sponsorICA": "5883", "ownerICA": "5883", "routeTransactionNumber": "840605018" } ] } ``` If you receive a similar JSON array, your credentials and authentication are working correctly. You have now successfully called the ATM Locations API. ### Test in Sandbox {#test-in-sandbox} After completing your first successful API call, you're now ready to test the full functionality of the ATM Locations APIs in sandbox. * You can add additional data fields to your first API call to improve match accuracy. * You can check out our [API Reference](https://developer.mastercard.com/locations/documentation/api-reference/index.md) to review full request and response definitions. ### Common Errors During Integration {#common-errors-during-integration} The following issues are commonly encountered when making your first ATM Locations API calls. | Error | Likely Cause | Recommended Action | |------------------------|--------------------------------------------------|-------------------------------------------------------| | 401 Unauthorized | OAuth signature, Consumer Key, or keystore issue | Review API Basics authentication setup | | 403 Forbidden | Project lacks required access | Verify Locations API has been enabled for the project | | MISSING_REQUIRED_INPUT | Required field missing | Validate all mandatory request parameters | ## Step 5: Move to Production {#step-5-move-to-production} ### Production Prerequisites {#production-prerequisites} Before you can request Production access, you need to complete a few steps located in the Production access prerequisites section on your project Summary page. ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/prod-prereq.png) 1. First you need to verify your company. This ensures your company is registered to do business with Mastercard. You can follow steps in our [Company Verification guide](https://developer.mastercard.com/platform/documentation/account-management/company-verification/#3-complete-verification) to complete this step. 2. You also need to provide your "commercial countries" to indicate where you are doing business for this API integration (i.e. where are your end-customers located) ### GO LIVE {#go-live} 1. Within your project, select "Request Production Access". ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/request-prod-access.png) 2. Enter your Production key alis and keystore password. ![Project](https://static.developer.mastercard.com/content/locations/uploads/quickstart/request-prod-cred.png) 3. Confirm and download your production keys. Note: Production Credentials are generated instantaneously, but they still must be approved for Production environment access before you can go live. After your Production access request has been reviewed by Mastercard's team, you will receive an email from [apisupport@mastercard.com](mailto:apisupport@mastercard.com) confirming your access has been approved or denied. ## Next Steps {#next-steps} * API Reference: Review the full [API specification](https://developer.mastercard.com/locations/documentation/api-reference/index.md). * Codes \& Formats: Know more about the [Error Codes](https://developer.mastercard.com/locations/documentation/code-and-formats/index.md) \& steps to fix the errors * Use Cases: See [Use Cases](https://developer.mastercard.com/locations/documentation/use-cases/index.md) to learn about the different ways clients use these API to create value for their organization.