Debit Currency API Documentation

v1Showing BAEC specific information(This functionality currently only works with our SwitchFly partner)

The Debit Currency API 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 API 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. The request to debit a member's account is often accompanied with information about the product being purchased.

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 API 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 API 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 API to restore the debited Avios to the customer.

Technical Context

In order to call the Debit Currency API the partner must have previously been issued with a valid Access Token in exchange for the member providing authorisation with their BA 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 API.

The following steps are performed by this API:

  • 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 API.
  • The partner must have obtained authorisation from the member to invoke this API. Authorisation is given by the member providing the BA credentials which will be exchanged for a valid access token.
  • Member must have enough Avios loyalty points in his balance for the API to debit it.
  • The partner must be associated with BAEC programme as part of the standard partner on-boarding process.

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/BAEC/accounts/36020200/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: Alphabets
BAEC
account-identifier
Required
StringMembership number of member
Format: Min length = 1 Max Length = 24 Numeric only
36020200
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 BA Authorisation Server. This API can only be accessed when a member has provided authorisation to the partner by providing their membership credentials.
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
Optional
StringIdentifies the originating IP address of a consumer.
Format: IP address
172.128.25.24
ba_client_application_name
Required
StringIdentify application name for BA application.
Format: Alphanumeric
AviosRewardApp
X-Agent-Id
Optional
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.
Format: Alphanumeric
Masanobu.Fukuoka

Request Elements

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

Success scenarios Single Product in Basket ( e.g. HOTEL) Request

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

Multiple Products(Hotel + CAR)

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

Multiple Products (Hotel +Experience) Request

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

Multiple products (CAR +HOTEL+EXPERIENCE) Request

{
  "debitTransaction": {
    "externalTransactionDate": "1991-12-15T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 1,
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. This value is ignored for non-monetary currency AVIOS.
Format: Alphanumeric Min length: 1 it has no restriction in max length
debitTransaction.description
Required
StringThe description of the transaction which is being submitted.
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:ETI
Format: Alphanumeric with special and accented characters: ~!@#\$%^&
debitTransaction.externalReferenceIdentifier
Optional
StringA unique reference generated by the Avios system. Element can accept accented characters but won't convert them. Example: 4ZS4JI
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
Optional
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: 12345
Format: Alphanumeric with special characters: & . -
debitTransaction.productSummary.productFeatureSummary
Optional
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. 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
StringThis element contains the sequence number of the selected product's feature. Example: 1
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 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": "RH001555293",
    "dateMade": "2019-03-25T19:18:16.957Z",
    "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 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",
    "developerMessage": "Member does not have sufficient mileage balance to carry out this transaction",

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.
400
REQUEST_INVALID
PARTNER_CONFIGURATION_INVALID
if there is not partner configuration found in configuration database.