openapi: 3.0.0 info: title: UAE Ozone Connect - Open Data API description: >- ## UAE Ozone Connect - Bank Open Data Provides support for bank-related open data APIs, such as ATM data, to be supported by LFIs. ### Versioning The `version` property implements the following pattern `{standards-major}.{standards-minor}.{ozone-connect-version}`, where: * `standards-major` is the major version of the latest UAE standard that the API description implements. * `standards-minor` is the minor version of the latest UAE standard that the API description implements. * `ozone-connect-version` is the version of the Ozone Connect API description. So, for example, `v2.0.1` indicates the first version of the Ozone Connect API description that implements the UAE standard version 2.0. version: v2.1.1 tags: - name: ATM description: Operations to support providing ATM data. paths: /atm: get: operationId: ReadAtmData_read summary: Retrieve ATM data description: Retrieve all ATM data for ATMs provided by the LFI. parameters: - $ref: '#/components/parameters/providerId' - $ref: '#/components/parameters/callerOrgId' - $ref: '#/components/parameters/callerClientId' - $ref: '#/components/parameters/callerSoftwareStatementId' - $ref: '#/components/parameters/apiUri' - $ref: '#/components/parameters/apiOperation' - $ref: '#/components/parameters/callerInteractionId' - $ref: '#/components/parameters/ozoneInteractionId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AEReadAtmsData1' meta: allOf: - $ref: '#/components/schemas/UAEATMAPI.AEReadAtmsMeta1' description: Metadata reflecting the state of the ATM data. required: - data - meta '400': $ref: '#/components/responses/error400Response' '403': $ref: '#/components/responses/error403Response' '500': $ref: '#/components/responses/error500Response' default: $ref: '#/components/responses/errorResponse' tags: - ATM components: parameters: apiOperation: name: o3-api-operation in: header required: true description: The API operation carried out by the caller (e.g. GET, POST, PUT, DELETE, PATCH) schema: type: string apiUri: name: o3-api-uri in: header required: true description: The URL of the API being called by the caller schema: type: string callerClientId: name: o3-caller-client-id in: header required: true description: An identifier for the OIDC clientId calling the API schema: type: string callerInteractionId: name: o3-caller-interaction-id in: header required: false description: The interaction ID passed in by the caller, if any schema: type: string callerOrgId: name: o3-caller-org-id in: header required: true description: An identifier for the organization calling the API schema: type: string callerSoftwareStatementId: name: o3-caller-software-statement-id in: header required: true description: An identifier for the software statement calling the API schema: type: string ozoneInteractionId: name: o3-ozone-interaction-id in: header required: true description: >- An interaction ID generated by Ozone if the caller did not send in one. If the callerInteractionId is specified, this takes the same value. schema: type: string providerId: name: o3-provider-id in: header required: true description: Identifier for the financial institution that the request is targeted to schema: type: string schemas: AECustomErrorCode: type: string pattern: ^[A-Za-z]+\.[A-Za-z0-9]+$ AEDefaultErrorCode: type: string description: Custom error code without prefix, retained for compatibility with version 1.2. AEError400Codes: type: string enum: - Consent.Invalid - Consent.BusinessRuleViolation - Consent.FailsControlParameters - Consent.InvalidUserIdentifier - JWS.InvalidSignature - JWS.Malformed - JWS.InvalidClaim - JWS.InvalidHeader - JWS.InvalidPayload - JWE.DecryptionError - JWE.InvalidHeader - GenericRecoverableError - GenericError - Event.UnexpectedEvent - Body.InvalidFormat - Resource.InvalidFormat AEError403Codes: type: string enum: - AccessToken.InvalidScope - Consent.TransientAccountAccessFailure - Consent.AccountTemporarilyBlocked - Consent.PermanentAccountAccessFailure - GenericRecoverableError - GenericError AEErrorGenericCodes: type: string enum: - GenericRecoverableError - GenericError AEReadAtmsData1: type: array items: type: object properties: LFIId: type: string minLength: 1 maxLength: 36 title: LFIId LFIBrandId: type: string minLength: 1 maxLength: 140 title: LFIBrandId ATMId: type: string minLength: 1 maxLength: 36 title: ATMId SupportedLanguages: type: array items: type: string title: SupportedLanguages Services: type: array items: anyOf: - type: string enum: - Balance - BillPayments - CashDeposits - CharityDonation - ChequeDeposits - CashWithdrawal - EnvelopeDeposit - FastCash - MobileBankingRegistration - MobilePaymentRegistration - MobilePhoneTopUp - OrderStatement - Other - PINActivation - PINChange - PINUnblock - MiniStatement - $ref: '#/components/schemas/UAEATMAPI.AENamespacedPattern' title: Services Accessibility: type: array items: type: string enum: - AudioCashMachine - AutomaticDoors - ExternalRamp - InductionLoop - InternalRamp - LevelAccess - LowerLevelCounter - Other - WheelchairAccess title: Accessibility IsAccess24Hour: type: boolean title: IsAccess24Hour Availability: type: object properties: Status: type: string enum: - Available - Unavailable - UnderMaintenance OperatingHours: type: array items: type: object properties: Days: type: array items: type: string enum: - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday OpenTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ CloseTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ required: - Days - OpenTime - CloseTime title: Availability SupportedCurrencies: type: array items: type: string minItems: 1 title: SupportedCurrencies MinimumPossibleAmount: $ref: '#/components/schemas/UAEATMAPI.AEActiveOrHistoricCurrencyAndAmount_0' MaximumPossibleAmount: $ref: '#/components/schemas/UAEATMAPI.AEActiveOrHistoricCurrencyAndAmount_0' Notes: type: array items: type: string title: Note Branch: type: object properties: SchemeName: type: string enum: - BICFI - Other Identification: type: string minLength: 1 maxLength: 36 title: Identification title: Branch Location: type: object properties: LocationCategory: type: array items: type: string enum: - BranchExternal - BranchInternal - BranchLobby - Other - RetailerOutlet - RemoteUnit - DriveThru title: LocationCategory Site: type: object properties: Identification: type: string minLength: 1 maxLength: 36 title: Identification Name: type: string minLength: 1 maxLength: 140 title: Name title: Site PostalAddress: type: object properties: AddressType: type: string enum: - Business - Other AddressLine: type: array items: type: string minItems: 1 maxItems: 7 BuildingNumber: type: string minLength: 1 maxLength: 16 BuildingName: type: string minLength: 1 maxLength: 140 Floor: type: string minLength: 1 maxLength: 70 StreetName: type: string minLength: 1 maxLength: 140 DistrictName: type: string minLength: 1 maxLength: 140 PostBox: type: string minLength: 1 maxLength: 16 TownName: type: string minLength: 1 maxLength: 140 CountrySubDivision: type: string enum: - AbuDhabi - Ajman - Dubai - Fujairah - RasAlKhaimah - Sharjah - UmmAlQuwain Country: type: string pattern: ^[A-Z]{2}$ GeoLocation: $ref: '#/components/schemas/UAEATMAPI.GeoLocation' required: - PostalAddress - GeoLocation title: Location Links: type: object properties: FeesUri: type: string format: uri ATMFee: type: array items: type: object properties: Type: type: string enum: - Withdrawal - BalanceInquiry - MiniStatement - PINChange - CashDeposit - CardlessWithdrawal - InternationalWithdrawal - CrossBankWithdrawal - OverLimit - DeclinedTransaction - EmergencyCashWithdrawal - ForeignATMUsage - ServiceDenial - FastCashWithdrawal - NetworkSurcharge - ForeignExchange - DomesticCrossBank - InternationalCrossBank - Other Amount: $ref: '#/components/schemas/UAEATMAPI.AEActiveOrHistoricCurrencyAndAmount_0' Percentage: type: number ApplicableNetworks: type: array items: type: string enum: - Visa - Mastercard - AmericanExpress - Diners - Other Conditions: type: string required: - Type required: - LFIId - LFIBrandId - ATMId - SupportedCurrencies - Location description: List of ATMs DefaultError: type: object properties: errorCode: allOf: - $ref: '#/components/schemas/AEDefaultErrorCode' description: >- Generic error code set by the LFI. Non-namespaced error codes are allowed for compatibility versions prior to v2.0. errorMessage: type: string description: Message describing what problem has occurred Error400: type: object required: - errorCode - errorMessage properties: errorCode: anyOf: - $ref: '#/components/schemas/AEError400Codes' - $ref: '#/components/schemas/AECustomErrorCode' - $ref: '#/components/schemas/AEDefaultErrorCode' description: >- Error code identifying the problem that occurred. This may either be one of the prescribed Error Code(s) or a namespaced Error Code where the namespace is the system or organisation that has responded with the error, and the code is the code specific to the system or organisation. organisation or system. LFIs should implement error codes based on the prescribed codes or guidance in the standards, with non-specific codes maintained for backward compatibility with version 1.2. errorMessage: type: string description: Message describing what problem has occurred description: Default error response payload structure for Ozone Connect Error403: type: object required: - errorCode - errorMessage properties: errorCode: anyOf: - $ref: '#/components/schemas/AEError403Codes' - $ref: '#/components/schemas/AECustomErrorCode' - $ref: '#/components/schemas/AEDefaultErrorCode' description: >- Error code identifying the problem that occurred. This may either be one of the prescribed Error Code(s) or a namespaced Error Code where the namespace is the system or organisation that has responded with the error, and the code is the code specific to the system or organisation. LFIs should implement error codes based on the prescribed codes or guidance in the standards, with non-specific codes maintained for backward compatibility with version 1.2. errorMessage: type: string description: Message describing what problem has occurred description: >- Error code identifying the problem that occurred. The first part of the code is the namespace, which is the name of the organisation or system that is rejecting the payment, and the second part is the specific rejection reason code for the originating organisation or system. Error500: type: object required: - errorCode - errorMessage properties: errorCode: anyOf: - $ref: '#/components/schemas/AEErrorGenericCodes' - $ref: '#/components/schemas/AECustomErrorCode' - $ref: '#/components/schemas/AEDefaultErrorCode' description: >- Error code identifying the problem that occurred. This may either be one of the prescribed Error Code(s) or a namespaced Error Code where the namespace is the system or organisation that has responded with the error, and the code is the code specific to the system or organisation. LFIs should implement error codes based on the prescribed codes or guidance in the standards, with non-specific codes maintained for backward compatibility with version 1.2. errorMessage: type: string description: Message describing what problem has occurred description: >- Error code identifying the problem that occurred. The first part of the code is the namespace, which is the name of the organisation or system that is rejecting the payment, and the second part is the specific rejection reason code for the originating organisation or system. UAEATMAPI.AEActiveCurrencyAndAmount_SimpleType: type: string pattern: ^\d{1,13}$|^\d{1,13}\.\d{1,5}$ description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. UAEATMAPI.AEActiveOrHistoricCurrencyAndAmount_0: type: object required: - Amount - Currency properties: Amount: $ref: '#/components/schemas/UAEATMAPI.AEActiveCurrencyAndAmount_SimpleType' Currency: $ref: '#/components/schemas/UAEATMAPI.ActiveOrHistoricCurrencyCode_0' description: This is the value of the amount in the currency UAEATMAPI.AENamespacedPattern: type: string pattern: ^[A-Za-z]+\.[A-Za-z]+$ UAEATMAPI.AEReadAtmsMeta1: type: object required: - LastUpdatedDateTime - TotalRecords properties: LastUpdatedDateTime: type: string format: date-time TotalRecords: type: integer UAEATMAPI.ActiveOrHistoricCurrencyCode_0: type: string pattern: ^[A-Z]{3,3}$ description: >- Identification of the currency in which the account is held. A code allocated to a currency under an international currency identification scheme, as described in the latest edition of the international standard ISO 4217 'Codes for the representation of currencies and funds'. UAEATMAPI.GeoLocation: type: object required: - Latitude - Longitude properties: Latitude: type: string description: latitude Longitude: type: string description: longitude description: GPS to identify the whereabouts of the ATM. securitySchemes: OzoneConnectApiKey: description: >- Communications between the API Hub and the LFI Ozone Connect implementation are secured using an API Key, which is a secret shared between the API Hub and the LFI. type: apiKey in: header name: Authorization OzoneConnectClientCredentials: type: oauth2 description: > Communications between the API Hub and the LFI Ozone Connect implementation are secured using a Client Credentials grant type. LFIs must host an OAuth 2.0 Authorization Server to utilise this security pattern. Scope values are set during the onboarding process, and represented by a placeholder in this API description. flows: clientCredentials: tokenUrl: https://example.lfi.ae/token scopes: placeholder: Placeholder for scopes, which are set by the LFI during onboarding OzoneConnectJwtAuth: description: > Communications between the API Hub and the LFI Ozone Connect implementation are secured using the "JWT Auth" mechanism, where the Client presents a signed JSON Web Token as a credential. The Server MUST verify the signature in order to authenticate the Client. Please note that the value of the `scheme` parameter is not a registered HTTP Authentication Scheme, to indicate it is specific to Ozone Connect. Please refer to API Hub documentation for further details. type: http scheme: Ozone-Connect-JWT-Auth OzoneConnectServiceInitiationToken: description: > Communications between the API Hub and the LFI Ozone Connect implementation are secured using a Service Initiation Token. The API Hub will set an Access Token based on a value set by the LFI, which has been patched onto the associated consent. The value will be transmitted in the `Authorization` header, which is represented as a `Bearer` in this Security Scheme Object. type: http scheme: Bearer responses: error400Response: description: Operation failed due to a invalid request parameter content: application/json: schema: $ref: '#/components/schemas/Error400' error403Response: description: Operation failed as access to the requested resource is forbidden content: application/json: schema: $ref: '#/components/schemas/Error403' error500Response: description: Operation failed due to an internal server error content: application/json: schema: $ref: '#/components/schemas/Error500' errorResponse: description: Default error response content: application/json: schema: $ref: '#/components/schemas/DefaultError' servers: - url: description: '' variables: {} security: - {} - OzoneConnectApiKey: [] - OzoneConnectClientCredentials: - placeholder - OzoneConnectJwtAuth: []