Debit Currency API Documentation

v1Showing ATRP specific information

The Debit Currency endpoint is available specifically to redemption partners to request a debit transaction to a member’s loyalty account from a partner’s application. This is typically part of a purchase where Avios loyalty points are redeemed in exchange for a product. This service would normally be used for a purchase that is part-paid in Avios and part-paid in cash, requiring the partner to manage both transactions. It is AGL’s business requirement to have as detailed product information as part of the Debit Currency call. Some of the information, like currency code and PNR, might be required to appear in multiple data elements.

In order to specify the number of Avios to be redeemed as part of this transaction request, the partner may have either called the Avios Retrieve Product Pricing endpoint or calculated the value themselves.

The redemption rate will have been agreed between Avios and the partner in advance. An OAuth access token will also need to be obtained by the partner based upon the member authorising the debit request against their account.

Business Context

Here’s the process flow:

Debit Currency Flow

  • The member browses product offering in the partner’s channel and commits to a purchase.
  • If the member has not previously logged in, they must do so.
  • The partner obtains an access token.
  • The partner (optionally) checks the member’s balance for sufficient available points.
  • The partner makes a debit request to the member’s account.
  • If successful, the points are debited, if not an error is returned.
  • If the cash portion of the transaction fails, the partner must make a call to the Reverse Transaction endpoint to restore the debited Avios to the customer.

Technical Context

In order to call the Debit Currency endpoint the partner must have previously been issued with a valid Access Token in exchange for the member providing authorisation with their Avios credentials. Although specifying an amount which exceeds the member’s current balance is not permitted (an appropriate error will be returned), the customer journey will be improved if the partner first checks the balance through a call to the Retrieve Account endpoint.

This endpoint performs following steps:

  • Validate the fields specified in the request
  • Check the member’s balance to ensure sufficient Avios loyalty points are available
  • Debit the member’s account and confirm the transaction.

Important Technical Notes

  • All enumerated values must be upper case.

Pre-conditions

  • The partner must have a valid API key to access the Debit Currency endpoint.
  • The partner must have obtained authorisation from the member to invoke this endpoint. Authorisation is given by the member providing the Avios credentials which will be exchanged for a valid access token.
  • Member must have enough Avios loyalty points in his balance to be debited.

Post-conditions

Success outcome: The member’s account is debited by the specified number of Avios loyalty points.

Error outcome: An error is returned and the member’s account balance remains unchanged.

Service Details

URI Parameters

Production Endpoint:

'POST https://api.avios.com/{version}/programmes/{programme-identifier}/accounts/{account-identifier}/debit-transaction-requests?api_key={api_key}'

Example

https://api.avios.com/v1/programmes/ATRP/accounts/3081470000000000/debit-transaction-requests?api_key=abcdef
NameTypeDescriptionExample
version
Required
StringThe version number of the API being called. The correct version is confirmed during the partner on-boarding process.
Format: Alpha numeric v
v1
programme-identifier
Required
StringThe identifier for the loyalty programme to which the member belongs. This will have been provided during the partner on-boarding process.
Format: Currently restricted to ATRP or BAEC
ATRP
account-identifier
Required
StringThe 16-digit membership number starting with 308147.
Format: Min length = 1 Max Length = 24 Numeric only
3081470000000000
api_key
Required
StringThe API key provided during the partner on- boarding process.
Format: Alpha-numeric Max Length = 24 Min Length = 24
abcdefabcdefabcdefa bcdef

Request Headers

NameTypeDescriptionExample
Authorization
Required
StringThis header contains the Access Token issued by the Authorisation Server. This API can only be accessed when a member has provided authorisation to the partner by providing their membership credentials. Must have a scope of retrieve_username
Format: JWT token
Accept
Optional
StringThe Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted currently.
Format: application/json
application/json
Content-Type
Required
StringThe Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted currently.
Format: application/json
application/json
X-Forwarded-For
Business Required
StringIdentifies the originating IP address of a consumer. This is required by AGL to mitigate against a risk of fraud and a misuse of customer’s credentials.
Format: IP address
172.128.25.24
X-Agent-Id
Optional / Business Required
StringAn agent Id represents the agent name/user name/login id and should be provided for offline channels like call centres. API won’t return error if not provided but partners should populate this field as much as possible in order to track potential irregular agent activities. This header is Optional for online channels and Business Required for offline channels.
Format: Alphanumeric
Masanobu.Fukuoka

Request Elements

The following shows examples of request calls to the Debit Currency API:

Request Example 1 – with product summary MI data

{
  "debitTransaction": {
    "externalTransactionDate": "2019-05-10T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 100,

Request Example 2 – without MI data

{
  "debitTransaction": {
    "externalTransactionDate": "1991-12-15T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 100,

Request Example 3 for Flight Ancillaries

{
  "debitTransaction": {
    "externalTransactionDate": "2016-12-15T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 350,
NameTypeDescription
debitTransaction
Required
Complex type 1..1This element represents debit transaction with associated attributes which are to be recorded.
debitTransaction.externalTransactionDate
Required
DateThis is the date of the transaction at partner channel for which the AVIOS redemption is being sought by calling Debit Currency API. Example:1991-12-15T20:37:21.886Z
Format: YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format.
debitTransaction.monetaryAmount
Required
Complex type 1..1This element contains the amount related attribute associated with the transaction which is requested to Debit Currency API.
debitTransaction.monetaryAmount.amount
Required
StringAmount (number of Avios) to be debited from the account. Example:100
Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.monetaryAmount.currency
Required
Complex type 1..1Represents the currency related information.
debitTransaction.monetaryAmount.currency.currencyCode
Required
StringRepresents the currency in which the transaction amount will be recorded. This value must be “AVIOS”.
Format: Enumeration
debitTransaction.exchangeRate
Optional
Complex type 1..1Redemption rate.
debitTransaction.exchangeRate.code
Required
StringRedemption rate code. The cash currency used for this transaction with Avios. If no cash currency used, use default value 1.
Format: Alphanumeric Min length: 1 Use 3-letter currency codes as defined in ISO 4217 (GBP, EUR, USD, CHF etc.).
debitTransaction.description
Required
StringThe description of the transaction which is being submitted. This description will appear in customer’s Transaction History.
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalTransactionIdentifier
Required
StringThis is the partner’s identifier for the transaction that was previously executed externally within the partner’s system against which the AVIOS redemption is being sought by calling Debit Currency API. Element can accept accented characters but won’t convert them. Example:00000012345. In case of partner system not generating a unique reference number, a dummy value must be agreed with AGL.
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalReferenceIdentifier
Business Required
StringA unique reference used by partner’s system, this could be partner generated booking reference number or externally generated like a PNR. Element can accept accented characters but won’t convert them. Examples: ISS12345678, 4ZS4JI. In case of partner system not generating a unique reference number, or it is not yet known at the time of the debit_currency API call, a dummy value must be agreed with AGL.
Format: Alphanumeric with special ~!@#\$%^&
debitTransaction.externalReferenceDescription
Required
StringThe description of the transaction at partner channel against which redemption is being sought by calling Debit Currency API. Example: ERD
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalPartnerIdentifier
Required
StringThe redemption channel used for submitting Debit Currency API request. Example: FLB
Format: Alphanumeric with special characters: ~!@#\$%^&
debitTransaction.productSummary
Business Required
Array of Complex type 0..nContains the details of the product which has been selected by a customer through partner channel.
debitTransaction.productSummary.productInstanceIdentifier
Required
StringThis element describes the identifier of the product which is booked as part of the transaction at partner site. Example: PNR001
Format: Alphanumeric with special characters: & . -
debitTransaction.productSummary.productFeatureSummary
Business Required
Array of Complex type 0..nProduct feature summary. This provides marketing information about the product and its features. There may be multiple instances of this element.
debitTransaction.productSummary.productFeatureSummary.code
Required
StringThis element contains the code of the selected product’s feature. Please use one of the following: ADULT_COUNT YOUNG_ADULT_COUNT CHILD_COUNT INFANT_COUNT SUPPLIER_ID BOOKING_DATE PNR PNR_CREATE_DATE FLIGHT_SEGMENT_ID LEG_DEPARTURE_DATE LEG_DEPARTURE_LOCATION LEG_ARRIVAL_LOCATION LEG_BOOKING_CLASS_CODE LEG_CABIN_CLASS_CODE MARKETING_CARRIER_IATA_CODE OPERATING_CARRIER_IATA_CODE MARKETING_CARRIER_FLIGHT_NO OPERATING_CARRIER_FLIGHT_NO HOTEL_NAME HOTEL_CHAIN HOTEL_CITY HOTEL_COUNTRY HOTEL_STAY_DURATION HOTEL_CHECK_IN_DATE HOTEL_CHECK_OUT_DATE HOTEL_OCCUPANT_TYPE HOTEL_ROOM_TYPE HOTEL_BOARD_BASIS HOTEL_SPECIAL_ORDER_ACCESSORY HOTEL_CHANNEL HOTEL_STAR_RATING HOTEL_NUMBER_OF_ROOMS CAR_HIRE_CITY CAR_HIRE_COUNTRY CAR_HIRE_DROP_OFF_TIME CAR_HIRE_PICK_UP_TIME CAR_HIRE_VEHICLE_TYPE CAR_HIRE_MILEAGE_ALLOCATED PICK_UP_LOCATION DROP_OFF_LOCATION PICK_UP_DATE DROP_OFF_DATE CHANNEL PRODUCT_CLASS TICKET_PRICE PURCHASE_CHANNEL CASH_DISCOUNT_CURRENCY_CODE BILLING_CURRENCY_CODE CASH_DISCOUNT If a suitable code for partner’s product details is not found, please contact to get them added. This is required to enable smooth ongoing reporting. Example: PNR
Format: Alphanumeric with special characters: & . -
debitTransaction.productSummary.productFeatureSummary.value
Required
StringThis element contains the value of the selected product’s feature. Example: PNR001
Format: Alphanumeric with special characters: & . -
debitTransaction.productSummary.productFeatureSummary.index
Optional / Business Required
StringThis element contains the sequence number of the selected product’s feature. Example: 0. This is Optional for single product products like Lounge_pass, but mandatory for Flights and any other products where there is multiple of same type of products. For example: flight, all codes and values related to first segment must have index 0, 1 for next segment and so on
Format: Numeric Max numeric value 99999
debitTransaction.productSummary.productTypeSummary
Required
StringProduct type. Must be one of the following: FLIGHT HOTEL CAR_HIRE INSURANCE SEAT PET BAGGAGE SPECIAL_BAGGAGE LOUNGE_PASS PARKING MEALS WIFI UPGRADE BUY_ON_BOARD UNACCOMPANIED_MINOR FEES SMS BASKET PRIORITY_BOARDING OTHER
Format: Enumeration
debitTransaction.type
Required
StringDebit transaction type. This must be “REDEMPTION”.
Format: Enumeration

Response Elements

The following example shows a response from the Debit Currency API:

{
  "debitTransaction": {
    "identifier": "19596A",
    "dateMade": "2017-01-24T12:28:45.197Z ",
    "monetaryAmount": {

The elements that make up the response message are detailed in the following table:

NameTypeDescription
debitTransaction
Conditional
Complex type 1..1This element represents debit transaction with associated attributes. This will be present in case of success response only.
debitTransaction.identifier
Present
StringA transaction identifier that uniquely identifies the debit transaction which has been recorded in ATRP system. The member account gets debited by the amount in request.
Format: Alphanumeric Max length: 32
debitTransaction.dateMade
Present
ISO-8601 StringThis is the date that has been stored against the transaction. This represents the date when the transaction occurred in ATRP or BAEC system. Example: 2016-02-26T10:53:14.301Z
Format: YYYY-MM-DDThh:mm:ss.sTZD
debitTransaction.monetaryAmount
Present
Complex type 1..1This element contains the amount related attribute associated with the transaction which is recorded by Debit Currency API.
debitTransaction.monetaryAmount.amount
Present
StringAmount (number of Avios) debited from the account. Example: 100
Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.monetaryAmount.formattedAmount
Present
StringString representation of the amount (number of Avios) debited from the account. Example: 100
Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.monetaryAmount.currency
Present
Complex type 1..1Represents the currency related information.
debitTransaction.monetaryAmount.currency.currencyCode
Present
StringRepresents the currency in which the transaction amount has been recorded. This will always be “AVIOS”.
Format: Enumeration
debitTransaction.description
Present
StringDescribes the description associated with the debit transaction as provided in request. In case if accented characters were passed in request for this field it will return converted characters.
Format: Alphanumeric with special characters ~!@#\$%^&
debitTransaction.externalTransactionIdentifier
Present
StringThe transaction identifier of the partner channel against which debit currency API was called. In case if accented characters were passed in request for this field API won’t convert them and will return them as it is.
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalReferenceIdentifier
Conditional
StringThis reference identifier similar which was passed in the request. In case if accented characters were passed in request for this field API won’t convert them and will return them as it is.
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalReferenceDescription
Present
StringDescription of the transaction at partner channel for which debit currency api was invoked. This value will be same as provided in request. In case if accented characters were passed in request for this field it will return converted characters.
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalPartnerIdentifier
Present
StringPartner identifier will be the same that was passed in request.
Format: Alphanumeric with special and ~!@#\$%^&
debitTransaction.type
Present
StringDebit transaction type. This will always be “REDEMPTION” for debit transactions.
Format: Enumeration.

Exception Message Elements

Example of an Error Response

The following shows two examples of error responses generated by the Debit Currency API:

Example 1:

{
  "error": {
    "code": "REQUEST_UNAUTHORIZED",
    "businessMessage": "Request Unauthorized",
    "developerLink": "https://developer.avios.com/docs",

Example 2:

{
  "error": {
    "code": "BALANCE_INSUFFICIENT",
    "businessMessage": "Balance Insufficient",
    "developerLink": "https://developer.avios.com/docs"

The exception message responses may be formatted in either upper or lower case.

NameTypeDescription
error
Conditional
Complex type 0..1Will only be present if an error has been detected and reported by the API.
error.code
Present
StringError code. Example: REQUEST_INVALID
Format: Alphabetic plus underscore (
error.businessMessage
Conditional
StringA business level message describing the error which has occurred. Example: Request Invalid
Format: Alphabetic
error.developerMessage
Conditional
StringDeveloper message will be present when detailed technical description is required for the error, which has occurred, by the API. If no specific developer message is required, developer message will be as business message.
Format: Alphabetic
error.developerLink
Conditional
StringA link to supporting documentation for this API. Example: https://developer.avios.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (
error.childError
Conditional
Array of complex type 0..nPresent for certain errors (e.g. validation) where one or more child error may have occurred.
error.childError.code
Present
StringThe error code for the child error (if returned). Example: DATA_INVALID
Format: Alphabetic plus underscore (
error.childError.path
Conditional
StringIdentifies the element in the request which has caused the error to occur. This will not come in case of any of the authorisation header elements are invalid or missing Paths are not sustained originating from backend system.
Format: Alphabetic plus period (.), oblique (/), open bracket (
error.childError.businessMessage
Conditional
StringA business level message describing the error which has occurred. Example: Data Invalid
Format: Alphabetic
error.childError.developerMessage
Conditional
StringDeveloper message will be present when detailed technical description is required for the error, which has occurred, by the API. If no specific developer message is required, developer message will be as business message.
Format: Alphabetic
error.childError.developerLink
Conditional
StringA link to supporting documentation for this API. Example: https://developer.avios.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (

Error Codes

The elements that make up the error messages are detailed in the following table:

Http Status CodeDescription
400
REQUEST_INVALID
DATA_INVALID
Request element does not follow the request contract.
400
REQUEST_INVALID
MANDATORY_DATA_MISSING
No content in the request body or a mandatory element is missing from the request or JSON provided in request doesn’t follow its contract.
400
INVALID_MEMBER
If an invalid membership number is supplied from Offline channels.
400
BALANCE_INSUFFICIENT
If there is not enough balance in the account to fulfil the debit request.