DIGITAL SERVICES. API Documentation Retrieve Transactions

Size: px

Start display at page:

Download "DIGITAL SERVICES. API Documentation Retrieve Transactions"

Sherilyn McKenzie
6 years ago
Views:

1 DIGITAL SERVICES API Documentation Retrieve Transactions Document Version Reason for change Author Signed-off by Status 0.12 Creation Gary Inkpen Final Draft 2016 Avios Group (AGL) Limited. All rights reserved. 1 Version 0.12

2 Contents 1. Overview Avios API Overview Retrieve Transactions Overview Introduction Business context Technical context Important Technical Notes Pre-conditions Post-conditions Service details URI Parameters Request Header Request Message Definition Request Elements Response Message Definition Response Message Diagram Retrieve Transactions Response Debit Transaction Credit Transaction Response Elements Exception Message Definition Exception Message Diagram Retrieve Transactions Error Exception Message Elements Error codes...21 Appendix A: Examples of Request Calls...22 Appendix B: Examples of Responses...23 Appendix C: Example of an Error Response...26 Glossary of Terms Avios Group (AGL) Limited. All rights reserved. 2 Version 0.12

3 1.Overview 1.1 Avios API Overview This document is a specification of the Retrieve Transactions API. An overview of this API is provided below in 1.2 and an overview of the entire Avios API service, including a general description that is relevant to all APIs, is contained in a separate document entitled API Overview. This overview is stored within the project s Reference Library. Any text that is shown italicised and underlined in the body of an API document refers to an entry inthe Reference Library. The contents of the library are summarised in the following table: Title Description Location/Link API Overview This general description is relevant to all APIs. Reference Library 1.2Retrieve Transactions Overview This Service is used to extract Member s transactions details. Transactions retrieved are either a subset of the member s statement of account or is the account statement with most recent made transactions as part of it Avios Group (AGL) Limited. All rights reserved. 3 Version 0.12

4 1.2.1Introduction Business context The process is illustrated in the following swim-lanes diagram: Retrieve Transactions API The Retrieve Transactions API provides filterable access to a maximum of 60 transactions made on the authenticated member s account. Avios APIs Partner Channel Member Is login required? Login form programme identifier, member credentials, partner credentials Call Retrieve Transactions membership number, access token membership number, access token, filters Retrieve Transactions Display account balance and transactions Filtered Debit & Credit Transactions Success? No Display error message Avios Authorisation Server Create token Success? No An overview of the process flow is as follows: The Retrieve Transactions API provides the ability to retrieve a filtered selection of up to 60 of themember s transactions for use within the partner channel. The member needs to be authenticated before calling API. The partner calls Retrieve Transactions API using the Access Token obtained from Login with Avios. If the API call is successful it will return a collection of up to 60 transactions. If the API call fails then the relevant error message needs to be displayed text Avios Group (AGL) Limited. All rights reserved. 4 Version 0.12

5 Technical context In order to call Retrieve Transactions, a token must have been obtained via a Create Token APIservice. The following steps are performed by the Retrieve Transactions application: Retrieve the member s transactionsfor a specified range. The range is a set of optional parameters, which if specified,may be either a transaction number range or a date range. An overview of the entireavios API journey is shown in the following diagram. This positions the Retrieve Transactions API within the overall application: THE AVIOS API JOURNEY FORGOTTEN DETAILS JOIN PROGRAMME REGISTER ACCOUNT CREATE TOKEN RETRIEVE TRANSACTIONS Note 1: For ticket pricing in isolation, it is not necessary to have previously invoked the Create Token service. Note 2: It is possible to use the Product Pricing service without a member having activated an account (ie: prior to invoking the Join Programme and Register Account services). PRODUCT PRICING RETRIEVE MEMBER UPDATE MEMBER To debit a currency the Create Token, Product Pricing & Retrieve Member services must all have previously been invoked. DEBIT CURRENCY REVERSE TRANSACTION Important Technical Notes Request elements are not stored. However, all enumerated values must be upper case. Elements in the response message are all returned in upper case ASCII characters. You can try this live service using I/O docs if you Register or Sign in with your Mashery ID Avios Group (AGL) Limited. All rights reserved. 5 Version 0.12

6 1.2.2 Pre-conditions A token must be supplied in order to use this service. A member identity must have been obtained Post-conditions Success outcome:transaction details arereturned in the API response message. Error outcome:service error is returned. Refer to Section 5 for a list of service errors Avios Group (AGL) Limited. All rights reserved. 6 Version 0.12

7 2.Service details Version v1.0 Type Http method Endpoint REST GET Test environment: transactions host = api.avios.com version = test/v1 programme-identifier = ATRP account-identifier = Response format XML, JSON 2016 Avios Group (AGL) Limited. All rights reserved. 7 Version 0.12

8 2.1 URI Parameters Name Required Data type Format Description Example programme-identifier Mandatory String Min length = 1. Max Length = 20. Alphabetic only. The identifier for the loyalty programme to which the member belongs.this will have been provided to the member as part of the Avios API partner on-boarding process along with your API key and Mashery credentials. Avios, BAEC account-identifier Mandatory Numeric Min length = 1. Max Length = 24. Numeric only. The 16-digit membership number starting with Request Header Name Required Data type Format Description Example accept Mandatory String application/<content-type> The Accept request-header field is used to specify certain media types which are acceptable for the response. Application/XML, Application/JSON content-type Mandatory String application/<content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Application/XML, Application/JSON authorization Mandatory String application/<content-type> Security token authorising access to the specified member s account Avios Group (AGL) Limited. All rights reserved. 8 Version 0.12

9 Name Required Data type Format Description Example partneridentifier Mandatory String Max length = 20 Alphanumeric Identifies the Partner Avios Group (AGL) Limited. All rights reserved. 9 Version 0.12

10 3. Request Message Definition This is a GET method and therefore there is no separate request payload. 3.1 Request Elements The elements that make up the request message are detailed in the following table. The following rules apply to request elements: Request elements are not stored. However, all enumerated values must be upper case. Elements in the response message are all returned in upper case ASCII characters. Default values are not assigned to elements that have not been supplied within a request message. Appendix A shows an example of a Retrieve Transactions API request call, expressed in XML and JSON format. Name Required Data type Format Description startrecord Optional Integer Numeric only Max numeric value = Index of the first item in the range of transactions to be returned.eg: 1 endrecord Optional Integer Numeric only Index of the last item in the range of transactions to be returned.eg: 6 Max numeric value = datemadefrom Optional Date ISO-8601 Calendar date format (YYYY- MM-DD). The date of the first item in the range of transactions to be returned. Eg: datemadeto Optional Date ISO-8601 Calendar date format (YYYY- MM-DD). The date of the last item in the range of transactions to be returned. Eg: Avios Group (AGL) Limited. All rights reserved. 10 Version 0.12

11 Name Required Data type Format Description externalsource Optional String String of maxl ength 10 The partner name related to the transaction Avios Group (AGL) Limited. All rights reserved. 11 Version 0.12

4.1.3Credit Transaction 2016 Avios Group

15 4.2 Response Elements The elements that make up the request message are detailed in the following table. All response elements are provided in uppercase ASCII characters. Appendix B shows an example of a Retrieve Transactions API response message, expressed in JSON format. Name Presence? Data type Format Description Transaction/Identifier Yes String Debit transaction identifier. transaction/ Yes Complex type [0..n] Detailed information relating to the member s debit and credit transactions. This element can either contain credit or debit transactions per node.there may be multiple instances of this element. transaction/debittransaction Conditional Complex type [0..1] transaction/debittransaction/datemade Yes Date YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format. transaction/debittransaction/description Yes String Max length: 51 Alphanumeric with special characters: Detailed information relating to the member s debit transactions. This is the specialised transaction element. This is the date that has been stored against the transaction.eg: T00:00: :00 A description of the debit transaction.eg: DESC ERI ( ) &. - _ /,%+ transaction/ debittransaction/ externalsource transaction/ debittransaction/ externalreferenceidentifier Yes String Max length: 10 Alphanumeric with special characters: ( ) &. - _ /,%+ Yes String Max length: 10 Alphanumeric only The partner name related to the transaction. The partner sreference for the debit transaction. Eg: 14426D 2016 Avios Group (AGL) Limited. All rights reserved. 15 Version 0.12

16 Name Presence? Data type Format Description Transaction/Identifier Yes String Debit transaction identifier. transaction/debittransaction/amount Yes Complex type [1..1] The complex type for the transaction amount. transaction/debittransaction/amount/amount Yes Big decimal Max length: 9 Numeric The transaction amount.eg: 1 transaction/debittransaction/amount/ formattedamount Yes String Max length: 9 Alphanumeric The transaction amount formatted as specified by the currency code. transaction/debittransaction/amount/currency Yes Complex type [1..1] Currency detail. The complex type for a specific unit of currency. transaction/debittransaction/amount/currency currencycode Yes String Enumeration Loyalty programme currency identifier. At present only Avios is supported, ie: currencycode = AVIOS. transaction/debittransaction/type Conditional String Enumeration Debit transaction typeredemption transaction/credittransaction Conditional Complex type [0..1] transaction/credittransaction/datemade Yes Date YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format. transaction/credittransaction/description Yes String Max length: 51 transaction/credittransaction/amount Yes Complex type [1..1] Alphanumeric with special characters: ( ) &. - _ /,%+ Detailed information relating to the member s credit transactions. This is the specialised transaction element. This is the date that has been stored against the transaction.eg: T00:00: :00 A description of the debit transaction.eg: JKL The complex type for the transaction amount Avios Group (AGL) Limited. All rights reserved. 16 Version 0.12

17 Name Presence? Data type Format Description Transaction/Identifier Yes String Debit transaction identifier. transaction/credittransaction/amount/amount Yes Big decimal Max length: 9 Numeric The transaction amount.eg: transaction/credittransaction/amount/ formattedamount Yes String Max length: 9 Alphanumeric The amount formatted as specified by the currency code.eg: transaction/credittransaction/amount/currency Yes Complex type [0..1] Currency detail. The complex type for a specific unit of currency. transaction/credittransaction/amount/currency currencycode Yes String Enumeration Loyalty programme currency identifier. At present only Avios is supported, ie: currencycode = AVIOS. transaction/credittransaction/type Conditional String Enumeration Credit transaction type. Must be one of the following: COLLECTION 2016 Avios Group (AGL) Limited. All rights reserved. 17 Version 0.12

19 5.2 Exception MessageElements This service returns standard OAuth 2.0 error messages.the exception message responses may be formatted in either upper or lower case. An example of an error response is shown in Appendix C. Name Presence? Data type Format Description error Conditional Complex Type [0..1] Will only be present if an error has been detected and reported by the API. error/code Yes String Alphabetic plus under-score (_). Error code. Eg: REQUEST_INVALID error/businessmessage Yes String Alphabetic Error message to business.eg: Request invalid error/developermessage Yes String Alphabetic Error message specific to client developer. error/developerlink Yes String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). error/childerror Conditional Array of complex type [0..n] error/childerror/code Yes String Alphabetic plus under-score (_). A URL link to a web page containing more detailed information about the error code.eg: Will only be present if an error has been detected and reported by the API. Error code. Eg: DATA_INVALID error/childerror/path Yes String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Path of the node on which error occurred. Eg: member.person.name.firstname 2016 Avios Group (AGL) Limited. All rights reserved. 19 Version 0.12

20 Name Presence? Data type Format Description error/childerror/businessmessage Yes String Alphabetic Error message to business. Eg: Data invalid error/childerror/developermessage Yes String Alphabetic Error message specific to client developer. error/childerror/developerlink Yes String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code.eg: Avios Group (AGL) Limited. All rights reserved. 20 Version 0.12

21 5.3 - Error codes All the errors from the service are returned in <Parent error code> <Child error code> format. The table below shows a full list of error codes. Parent error code Child error code Description REQUEST_INVALID MANDATORY_DATA_MISSING Mandatory element in the request is missing. REQUEST_INVALID DATA_INVALID Request element does not follow the request contract.for example the end-date is before the start-date. REQUEST_UNAUTHORIZED TOKEN_INVALID Token in authorization header is invalid for the member. REQUEST_INVALID PROGRAMME_INVALID Invalid programme identifier is passed in the request. REQUEST_UNAUTHORIZED AUTHORIZATION_LEVEL_INSUFFICIENT The authorization level of the token is not in the defined list. REQUEST_UNAUTHORIZED TOKEN_EXPIRED The token is expired or an expired token has been used. REQUEST_UNAUTHORIZED DATA_INVALID Invalid data input for authorizing the request. REQUEST_INVALID SYSTEM_UNAVAILABLE When a system is not available. See Appendix C for examples of API error response messages Avios Group (AGL) Limited. All rights reserved. 21 Version 0.12

22 Appendix A: Examples of Request Calls The following are all examples of request calls to the Retrieve Transactions API: Example 1: Example 2: startrecord=1&end-record=8&date-made-from= &date-made-to= Example 3: startrecord=1&end-record=8&external-source=tesco% 2016 Avios Group (AGL) Limited. All rights reserved. 22 Version 0.12

23 Appendix B: Examples of Responses The following shows 3examples ofresponsesgenerated by the Retrieve Transactions API: Example 1: { "transaction": [ { "credittransaction": { "datemade": " T00:00: :00", "description": "CANCELLED BOOKING", "externalreferenceidentifier": "14426D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS", { "debittransaction": { "datemade": " T00:00: :00", "description": "DESC ERI", "externalreferenceidentifier": "14426D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS", { "debittransaction": { "datemade": " T00:00: :00", "description": "DESC ERI", "externalreferenceidentifier": "14082D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS", { "debittransaction": { 2016 Avios Group (AGL) Limited. All rights reserved. 23 Version 0.12

24 ], { "datemade": " T00:00: :00", "description": "DESC ERI", "externalreferenceidentifier": "14081D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS" "credittransaction": { "datemade": " T00:00: :00", "description": "JKL", "externalsource": "TESCO (STA", "externalreferenceidentifier": "HJG", "amount": { "amount": , "formattedamount": " ", "currency": { "currencycode": "AVIOS" Example 2: { "transaction": [ { "credittransaction": { "datemade": " T00:00: :00", "description": "CANCELLED BOOKING", "externalreferenceidentifier": "14426D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS", { "debittransaction": { "datemade": " T00:00: :00", "description": "DESC ERI", 2016 Avios Group (AGL) Limited. All rights reserved. 24 Version 0.12

25 ] "externalreferenceidentifier": "14426D", "amount": { "amount": 1, "formattedamount": "1", "currency": { "currencycode": "AVIOS" Example 3: { "transaction": [ { "credittransaction": { "datemade": " T00:00: :00", "description": "JKL", "externalsource": "TESCO (STA", "externalreferenceidentifier": "HJG", "amount": { "amount": , "formattedamount": " ", "currency": { "currencycode": "AVIOS" ] 2016 Avios Group (AGL) Limited. All rights reserved. 25 Version 0.12

26 Appendix C: Example of an Error Response The following shows an example of anerror response generated by the Retrieve Transactions API: { "error": { "code": "REQUEST_INVALID", "businessmessage": "Request invalid", "developerlink": " "childerror": [ { "code": "DATA_INVALID", "businessmessage": "Data Invalid", "developerlink": " ] 2016 Avios Group (AGL) Limited. All rights reserved. 26 Version 0.12

27 Glossary of Terms Acronym API APID ATRP Avios BAEC ISO JSON Mashery on-boarding SOAP URI and URL Description Application Program Interface: a set of routines, protocols and tools for building software applications. The API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components. Avios Partner Identification Avios Travel Rewards Programme. The Avios reward programme. British Airways Executive Club. International Standards Organisation Java Script Object Notation: An open standard format that uses humanreadable text to transmit data objects consisting of attribute value pairs. It is the primary data format used for asynchronous browser/server communication (AJAJ), largely replacing XML (used by AJAX). A cloud hosted component of the API handling process. This function adds or modifies certain API parameters when a call is received and prior to processing by the called Avios application. The process of signing-up a partner commercially and getting them up to speed with Avios. Simple Object Access Protocol: a protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses the XML Information Set for its message format, and relies on other application layer protocols, most notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission A Uniform Resource Locator (URL), commonly informally termed a web address is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifier (URI) although many people use the two terms interchangeably. A URL implies the means to access an indicated resource, which is not true of every URI. URLs are most commonly used to reference web pages (http), but are also used for file transfer (ftp), (mailto), database access (JDBC) and many other applications Avios Group (AGL) Limited. All rights reserved. 27 Version 0.12

28 Acronym XML Description Extensible Markup Language: a mark-up language that defines a set of rules for encoding documents in a format which is both humanreadable and machine-readable. End of Document 2016 Avios Group (AGL) Limited. All rights reserved. 28 Version 0.12

DIGITAL SERVICES. API Documentation Product Pricing

DIGITAL SERVICES. API Documentation Product Pricing DIGITAL SERVICES API Documentation Product Pricing Document Version Reason for change Author Signed-off by Status 0.10 Creation Gary Inkpen Final Draft 2016 Avios Group (AGL) Limited. All rights reserved.