ATM API Specification - v2.1.1
Version Control
Version | Date | Author | Comments |
---|---|---|---|
2.0.0 | 29 Jun 2017 | Open Banking Open Data API Team | This is the baseline version. |
2.1.0 | 21 Aug 2017 | Open Banking Open Data API Team | This release incorporates all known issues with 2.0.0 up to 18 Aug 2017. Please see the release notes for details. |
2.1.1 | 12 Oct 2017 | Open Banking Open Data API Team | For ATM, this release is identical to 2.1.0 API. Please see the 2.1.0 release notes for details. The MIG is from v2.2 (as recommended by PMG) |
Overview
This specification includes all relevant artefacts for the Open Data ATM API Specification.
This endpoint can contain multiple brands owned by a particular banking group. Each brand can provide multiple ATMs.
An ATM consists of:-
- A unique Identification
- ATMServices - a pre-defined set of standard code names defining services available from an ATM e.g. PinUnblock
- OtherATMServices - allows a bank to add it's own non-standard/proprietary codes, code names & descriptions
- Accessibility - a pre-defined set of standard code names defining accessibility features that the ATM offers e.g. InductionLoop
- OtherAccessibility - allows a bank to add it's own non-standard/proprietary codes, code names & descriptions
- Supported Languages - the 2-digit ISO 639-1 language code
- Location - This is where the ATM is located and is a mix of a postal address and the geographic coordinates (decimal Latitude & Longitude). Postal address information can either be:-
i) Up to 7 lines of unstructured address information (AddressLine)
ii) Structured address information e.g. BuildingNumber, StreetName, Town, PostCode etc or a mixture of both.
Location is very important so the API provider should ensure that either geographical coordinates (preferred) or a combination of building number & postcode are supplied so that the ATM can be accurately located on a map. - Base currency - currently restricted to 'GBP' only, but may be extended in future to cope with other currencies dispensed by ATMs at airports, for example, if the API providers are able to supply this information
- Minimum possible amount - This will inform a consumer as the minimum possible amount that they can withdraw from an ATM. Note: This is not the same as the minimum denomination. For example, an ATM may dispense £5 notes but require the consumer to withdraw a minimum possible amount of £10.
Specification
The following UML Class Diagram provides the hierarchical structure of the message in a graphical form, which is easier to digest.
- Data Dictionary - provides detailed descriptions for each field in the message specification along with the associated code lists, constraints and other technical details such as cardinality, any pattern constraints, min, max length etc.
- Swagger- the API specification written using the Swagger API specification format.
Compliance Report
- Compliance Report - highlights changes made to fields & datatypes from v1.x.
Message Implementation Guide
Purpose
The message implementation guide (MIG) is designed to assist the implementers of the messaging specification by providing worked examples as to how the message fields should be completed in different scenarios.
The intention is that this will better ensure consistency. This guide should be read alongside the data dictionary which provides fuller information about the rules, constraints and guidelines that should be adhered to when populating the fields.
Format Notation
The format that we use in this document for field value assignment is:-
[] enclose a set of field values.
Where there are multiple records for a particular field, we depict this as [<record 1 value1>,< record 1 value2>…<recordn valuen>], whilst where we are showing that there is 1 field value in 1 record, and another field value in a 2nd record, I depict this as [<record1 value1>],[<record 2 value 1>],[<record 3 value 3>]
, seperates individual field values within a field value set.
“ surrounds a text or date field value.
Implementation Notes
Before implementing the message standard, it is useful browsing current ATM Locator websites e.g. Link ATM Locator/, Visa ATM Locator and Mastercard ATM Locator, along with the ATM Locator webpages provided by your own organisation, in order to get a feel as to why you need to supply this information.
© Open Banking Limited 2019 | https://www.openbanking.org.uk/open-licence | https://www.openbanking.org.uk