Credit Currency API Documentation

v1Showing ATRP 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 and returns 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 have been successfully created via Join Programme Service, or Avios channels (applies if crediting member via ATRP programme). Member Account must be successfully created in British Airways systems. (Applies if crediting member via BAEC programme.)
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/ATRP/accounts/3081470000000000/credit-transaction-requests?api_key=abcdef

Name	Data type	Description	Example
`version` Required	String	The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric	v1
`account-identifier` Required	Numeric	Unique Identifier of the member of the loyalty programme, e.g. membership number. Format: Min length = 1 Max Length = 24 Numeric only	3081470000000000
`programme-identifier` Required	String	The 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: ATRP	ATRP
`api_key` Required	String	The 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

Name	Data type	Description	Example
`Accept` Optional	String	The 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
`Authorization` Optional	String	This header contains the Access Token issued by the Authorisation Server. Must have a scope of `retrieve_username` Format: JWT Token
`Content-Type` Required	String	The 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	String	Identifies 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 API:
Example 1 – ATRP programme request with MI data

{
  "description": "666 Avios collected",
  "monetaryAmount": {
    "amount": 666,
    "currency": {...

Example 2 – ATRP programme request without MI data

{
  "description": "100 Avios collected",
  "monetaryAmount": {
    "amount": 100,
    "currency": {...

Name	Data Type	Description
`description` Conditional	String	The description of the transaction which is being submitted. Required for ATRP Format: Alphanumeric with special characters. Min length: 1
`monetaryAmount` Required	Complex type	Credit transaction amount details.
`monetaryAmount.amount` Required	String	Amount to be credited to the account. Example: 10 Format: Numeric only. For ATRP: Max value: Set per partner, limit 999,999 Max length: 6
`monetaryAmount.currency` Required	Complex type	Credit transaction currency detail.
`monetaryAmount.currency.currencyCode` Required	String	Loyalty programme currency identifier. Case sensitive. At present only Avios is supported, i.e.: currencyCode = “AVIOS”. Format: Enumeration
`externalTransactionIdentifier` Required	String	This is the partner’s identifier for the transaction that was previously executed externally within the partner’s system. Example for ATRP programme: ext. Format: Alphanumeric with special characters: Max length: 20 & . -
`externalTransactionDate` Required	Date	This 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 ATRP: API accepts 10 years old transaction dates. Format: ISO-8601 Calendar date format.
`externalReferenceIdentifier` Optional	String	This is the booking reference associated with the collection request. Example: ERI Format: Alphanumeric with special characters: Max length: 10 & . -
`externalReferenceDescription` Optional	String	The description of the transaction executed at partner channel. Example: ERD Format: Alphanumeric with special characters: Max length: 62 & . -
`externalPartnerIdentifier` Optional	String	This is the channel from where the request has been made from. Example: EPI Format: Alphanumeric with special characters: (space). Max length: 3
`externalSource` Required	String	ATRP: The billing code. BAEC: Location code. Format: Alphanumeric with special characters: Max length: 10 & . -
`productSummary` Optional	Array of Complex type	Details information about the product.
`productSummary.productInstanceIdentifier` Required	String	This 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	Product feature summary. This provides marketing information about the product and its features. There may be multiple instances of this element.
`productSummary.productFeatureSummary.code` Required	String	This 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	String	This 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	String	This element contains the sequence number of the selected product’s feature. Example: 1 Format: Numeric: Max numeric value 99999
`productSummary.productTypeSummary` Required	String	Product type. Must be one of the following: FLIGHT HOTEL CAR HIRE OTHER Format: Enumeration
`type` Required	String	Credit transaction type. This must be “COLLECTION”. Format: Enumeration
`person` Required	Complex type	Representation the personal attribute of the member.
`person.name` Required	Complex type	Contains the family name details of the member.
`person.name.firstName` Conditional	String	First name of the member. Optional for ATRP Format: For ATRP: Max length: 25. Latin symbols with quote ('), hyphen (-) and space ( ).
`person.name.familyName` Required	String	Family name of the member. Format: For ATRP: Max length: 40. Latin symbols with quote ('), hyphen (-) and space ( ).

Response Elements

Example Response:

{
  "identifier": "6425162290813 ",
  "dateMade": "2016-08-16T09:13:30.737Z",
  "description": "ccd8e491-973d-46b9-9b6b-f934c37cf945",
  "monetaryAmount": {...

Name	Data type	Description
`identifier` Present	String	A transaction identifier that uniquely identifies the credit transaction. Example: “19195D“ Format: Alphanumeric Max length: 16
`dateMade` Present	Date	This 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	String	Credit transaction description. Presence for ATRP. Format: Alphanumeric with special characters &.-
`monetaryAmount` Present	Complex type	Credit transaction amount details.
`monetaryAmount.amount` Present	String	Amount credited to the account. Example: 10 Format: Numeric Max length: 6
`monetaryAmount.formattedAmount` Present	String	The amount formatted as specified by the currency code. Example: 10 Format: Alphanumeric Max length: 6
`monetaryAmount.currency` Present	Complex type	Credit transaction currency detail.
`monetaryAmount.currency.currencyCode` Present	String	Loyalty programme currency identifier. At present only Avios is supported, i.e.: currencyCode = “AVIOS”. Format: Enumeration
`externalTransactionIdentifier` Present	String	This 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	Date	This 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	String	This is the booking reference associated with the collection request. Format: Alphanumeric with special characters & . -
`externalReferenceDescription` Optional	String	The 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	String	This is the channel from where the request was made. Format: Alphanumeric with special characters space ( ) Max length: 3
`externalSource` Present	String	ATRP: The billing code as given in request Format: Alphanumeric with special characters & . -
`type` Present	String	Credit transaction type. This will always be `COLLECTION`. Format: Enumeration

Exception Message Elements

Error Response:

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

Name	Data type	Description
`code` Present	String	Error code. Example: REQUEST_INVALID Format: Alphabetic plus underscore
`businessMessage` Present	String	A business level message describing the error which has occurred. Example: Request Invalid. Format: Alphabetic
`developerMessage` Conditional	String	Developer 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	String	A link to supporting documentation for this API. Example: https://developer.iagloyalty.com/docs Format: Alphabetic plus colon (:), forward slash (/), dash (-), underscore or period (.).
`childError` Conditional	Array of complex type	Present for certain errors (e.g. validation) where more than error may have occurred.
`childError.code` Present	String	The error code for the child error (if returned). Example: `DATA_INVALID` Format: Alphabetic plus underscore
`childError.path` Conditional	String	Identifies 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 (.), forward slash (/), open bracket (
`childError.businessMessage` Present	String	A business level message describing the error which has occurred. Example: Programme not supported Format: Alphabetic
`childError.developerMessage` Conditional	String	Developer 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	String	A link to supporting documentation for this API. Example: https://developer.iagloyalty.com/docs Format: Alphabetic plus colon (:), forward slash (/), dash (-), underscore or period (.).

Error Codes

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

Http Status Code	Description
`400` REQUEST_INVALID DATA_INVALID	Request element does not follow the request contract or request does not follow the JSON contract *Transaction ID invalid.
`400` REQUEST_INVALID PROGRAMME_INVALID	Programme information does not exist.
`400` REQUEST_INVALID ACCOUNT_INVALID	Account information does not exist.
`400` REQUEST_INVALID ACCOUNT_NOT_AUTHORISED	The provided account-identifier is cancelled, deceased, fraud.
`400` REQUEST_INVALID DUPLICATE_TRANSACTION	API returns this error when transaction made has the same amount, description and date values as previous transaction made.
`400` REQUEST_INVALID PROGRAMME_NOT_SUPPORTED	Partner is not associated with the programme.
`400` REQUEST_INVALID INVALID_PROMOTER_CODE	Invalid external source code (promoter) supplied (ATRP programme).
`400` MEMBERSHIP_NUMBER_NAME_MISMATCH	*The name provided in request does not match against the stored member details.
`400` MEMBERSHIP_NUMBER_SURNAME_MISMATCH	The surname provided in request does not match against the stored member details.