Credit Currency API Documentation

v1Showing BAEC specific information

The Credit Currency service allows partners to credit Avios to member accounts. Each credit request will immediately credit an account on successful processing of request.

This service will credit an account with a number of Avios awarded for a range of activities including non-air transactions, transactions for full return flights or a transaction for one leg of a return flight. Credit Currency will return a unique transaction identifier for each credit transaction.

Business Context

Here's the process flow:

Credit Currency Flow

  • The Partner invokes the Credit Currency service from the partner application to credit an account.
  • The Credit Currency service credits the account with the requested monetary amount along with a unique identifier and a timestamp for the transaction made. If crediting an account fails, an appropriate business message and developer message is returned.

Technical Context

Important Technical Notes

  • All values in elements which has format enumeration must be recorded in upper case ASCII characters. Response messages will be returned in upper case.
  • To credit Household account, the family name must be sent as "HOUSEHOLD" or as merged member's surname.

Pre-conditions

  • A Member Account must be successfully created in British Airways systems.
  • The partner must have a valid API key to access the Credit Currency service. The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process.

Post-conditions

Success outcome: The member's account is credited with the amount as specified in the credit transaction request.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

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

Example URI

https://api.avios.com/v1/programmes/BAEC/accounts/3081470000000000/credit-transaction-requests?api_key=abcdef
NameData typeDescriptionExample
version
Required
StringThe version of the API which will be confirmed during the on-boarding process.
Format: Alphanumeric v
v1
account-identifier
Required
NumericUnique Identifier of the member of the loyalty programme.
Format: Min length = 1 Max Length = 24 Numeric only
10429844
programme-identifier
Required
StringThe identifier for the loyalty programme to which the member belongs. This will have been provided to the member as part of the Loyalty Programme API partner on-boarding process along with API key.
Format: BAEC
BAEC
api_key
Required
StringThe partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process.
Format: Length = 24

Request Headers

NameData typeDescriptionExample
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.
Format: application/< content-type >
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.
Format: application/< content-type >
application/json
X-Forwarded-For
Optional
StringIdentifies the originating IP address of a consumer.
Format: Comma separated valid IP addresses
172.128.25.24, 172.128.25.24

Request Elements

The following shows examples of request calls to the Credit Currency endpoint:

Example 1 BAEC programme request

{
  "monetaryAmount": {
    "amount": 1000,
    "currency": {
      "currencyCode": "AVIOS"
NameData TypeDescription
description
Optional
StringThe description of the transaction which is being submitted.
Format: Alphanumeric with special characters. Min length: 1
monetaryAmount
Required
Complex type 1..1Credit transaction amount details.
monetaryAmount.amount
Required
StringAmount to be credited to the account. Example: 1000
Format: Numeric only. For BAEC: Max length: 6
monetaryAmount.currency
Required
Complex type 1..1Credit transaction currency detail.
monetaryAmount.currency.currencyCode
Required
StringLoyalty programme currency identifier. Case sensitive. At present only Avios is supported, i.e.: currencyCode = "AVIOS".
Format: Enumeration
externalTransactionIdentifier
Required
StringThis is the partner's identifier for the transaction that was previously executed externally within the partner's system.Example for BAEC programme: AS+ 087070700, AS%087070700, AS_087070700
Format: Numerical characters only. Max length: 20
externalTransactionDate
Required
DateThis is the date that the client requires to be stored against the transaction, and would normally relate to the time of the associated activity such as collection time. API doesn't accept future dates and API time zone is UTC.For BAEC: API accepts transaction dates only later than member's join date for which transaction is being executed.
Format: ISO-8601 Calendar date format.
externalReferenceIdentifier
Optional
StringThis is the booking reference associated with the collection request. Example: ERI
Format: Alphanumeric with special characters: Max length: 10 & . -
externalReferenceDescription
Optional
StringThe description of the transaction executed at partner channel. Example: ERD
Format: Alphanumeric with special characters: Max length: 62 & . -
externalPartnerIdentifier
Optional
StringThis is the channel from where the request has been made from. Example: EPI
Format: Alphanumeric with special characters: (space). Max length: 3
externalSource
Required
StringBAEC: Location code.
Format: Alphanumeric with special characters: Max length: 10 & . -
productSummary
Optional
Array of Complex type 0..nDetails information about the product.
productSummary.productInstanceIdentifier
Required
StringThis element describes the identifier of the product which is booked as part of the transaction. Example: 12345
Format: Alpha numeric with special characters: Max length: 200 & . -
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.
productSummary.productFeatureSummary.code
Required
StringThis element contains the code of the selected product's feature. Example: PNR
Format: Alpha numeric with special characters: Max length: 200 & . -
productSummary.productFeatureSummary.value
Required
StringThis element contains the value of the selected product's feature. Example: COL222
Format: Alpha numeric with special characters: Max length: 200 & . -
productSummary.productFeatureSummary.index
Optional
StringThis element contains the sequence number of the selected product's feature. Example: 1
Format: Numeric: Max numeric value 99999
productSummary.productTypeSummary
Required
StringProduct type. Must be one of the following: FLIGHT HOTEL CAR HIRE OTHER EXPERIENCE WINE CAR
Format: Enumeration
type
Required
StringCredit transaction type. This must be "COLLECTION".
Format: Enumeration
person
Required
Complex type 1..1Representation the personal attribute of the member.
person.name
Required
Complex type 1..1Contains the family name details of the member.
person.name.firstName
Conditional
StringFirst name of the member.
Format: For BAEC: Accented Latin characters, apostrophes ('), hyphens (- ) and spaces ( ) accepted.
person.name.familyName
Required
StringFamily name of the member.
Format: For BAEC: Accented Latin characters, apostrophes ('), hyphens (- ) and spaces ( ) accepted.

Response Elements

Example Response:

{
  "dateMade": "2019-04-25T07:18:40.785Z",
  "description": "ExternalReferenceDescription",
  "monetaryAmount": {
    "amount": 1000,
NameData typeDescription
dateMade
Present
DateThis is the date and time when credit transaction request was performed. API time zone is UTC. Example: 2016-02-26T10:53:14.301Z
Format: ISO-8601 Calendar date format.
description
Conditional
StringOptional presence for BAEC Example: ExternalReferenceDescription
Format: Alphanumeric with special characters with pattern (\s
monetaryAmount
Present
Complex type 1..1Credit transaction amount details.
monetaryAmount.amount
Present
StringAmount credited to the account. Example: 10
Format: Numeric Max length: 6
monetaryAmount.formattedAmount
Present
StringThe amount formatted as specified by the currency code. Example: 10
Format: Alphanumeric Max length: 6
monetaryAmount.currency
Present
Complex type 1..1Credit transaction currency detail.
monetaryAmount.currency.currencyCode
Present
StringLoyalty programme currency identifier. At present only Avios is supported, i.e.: currencyCode = "AVIOS".
Format: Enumeration
externalTransactionIdentifier
Present
StringThis is the partner's identifier for the transaction that was previously executed externally within the partner's system against which the AVIOS collection is being sought by calling Credit Currency API.
Format: Alphanumeric with special characters . -
externalTransactionDate
Present
DateThis is the date the client requires to be stored against the transaction, and would normally relate to the time of the associated activity such as collection time. Example.: 1991-12-15T20:37:21.886Z
Format: YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format.
externalReferenceIdentifier
Optional
StringThis is the booking reference associated with the collection request.
Format: Alphanumeric with special characters & . -
externalReferenceDescription
Optional
StringThe description of the transaction executed at partner channel against which collection is being sought by calling Credit Currency API.
Format: Alphanumeric with special characters & . -
externalPartnerIdentifier
Optional
StringThis is the channel from where the request was made.
Format: Alphanumeric with special characters space ( ) Max length: 3
externalSource
Present
StringBAEC: The location code as given in request
Format: Alphanumeric with special characters & . -
type
Present
StringCredit transaction type. This will always be COLLECTION.
Format: Enumeration

Exception Message Elements

Error Response Example - 1:

{
  "code": "REQUEST_INVALID",
  "businessMessage": "Request Invalid",
  "developerLink": "https://developer.iagloyalty.com/docs",
  "childError": [

Error Response Example - 2:

{
  "code": "REQUEST_INVALID",
  "businessMessage": "Request Invalid",
  "developerLink": "https://developer.iagloyalty.com/docs",
  "childError": [
NameData typeDescription
code
Present
StringError code. Example: REQUEST_INVALID
Format: Alphabetic plus underscore (
businessMessage
Present
StringA business level message describing the error which has occurred. Example: Request Invalid.
Format: Alphabetic
developerMessage
Conditional
StringDeveloper message will be present when error message requires a detailed technical description. If no specific developer message is required, developer message will be the same as business message.
Format: Alphabetic
developerLink
Present
StringA link to supporting documentation for this API. Example: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (
childError
Conditional
Array of complex type 0..nPresent for certain errors (e.g. validation) where more than error may have occurred.
childError.code
Present
StringThe error code for the child error (if returned). Example: DATA_INVALID
Format: Alphabetic plus underscore (
childError.path
Conditional
StringIdentifies the element in the request which has caused the error to occur. This element will not be visible when headers provided in request message is invalid or missing or the validation of element is done beyond the business API.
Format: Alphabetic plus period (.), oblique (/), open bracket (
childError.businessMessage
Present
StringA business level message describing the error which has occurred. Example: Programme not supported
Format: Alphabetic
childError.developerMessage
Conditional
StringDeveloper message will be present when error message requires a detailed technical description. If no specific developer message is required, developer message will be the same as business message.
Format: Alphabetic
childError.developerLink
Present
StringA link to supporting documentation for this API. Example: https://developer.iagloyalty.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
ACCOUNT_INVALID
BAEC account does not exist or you are attempting to credit a member with a future date.
400
REQUEST_INVALID
DATA_INVALID
Amount credited cannot exceed the limit or be equal to or less than zero.

Invalid JSON request, Amount, Currency code, ExternalSource, ExternalReferenceIdentifier, description, ExternalTransactionIdentifier, ExternalSourcefield, ExternalTransactionDate, Transaction type or XML format (Currency code, ExternalTransactionDate, FirstName or FamilyName or X-Forwarded-For values).

Missing mandatory Amount, Currency code, ExternalTransactionDate, ExternalTransactionIdentifier, ExternalSource, FirstName, FamilyName or Type field.
400
REQUEST_INVALID
DUPLICATE_TRANSACTION
Duplicate transaction.
400
REQUEST_INVALID
INVALID_PROMOTER_CODE
Invalid transaction ID, ExternalTransactionIndentifier or ExternalSource, or you are attempting to Credit BAEC member with partner without active BAEC programme.
400
REQUEST_INVALID
MEMBERSHIP_NUMBER_NAME_MISMATCH
Membership Number Name Mismatch.
400
REQUEST_INVALID
PARTNER_INVALID
Invalid partner code or non-existant partner.
400
REQUEST_INVALID
PROGRAMME_INVALID
Invalid programme-id or programme not supported.
405
REQUEST_INVALID
HTTP_METHOD_NOT_SUPPORTED
The HTTP method used to call the API is not allowed.
415
REQUEST_INVALID
HEADER_INVALID
Unsupported media type.