Reverse Transaction API Documentation

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

The Reverse Transaction endpoint is intended to reverse previously processed debit transactions. Identification details of the transaction to be reversed are passed in the request. The entire amount for the given transaction will be reversed and a transaction identifier for the reversed transaction will be supplied in the response. Before invoking this service, an access token should be obtained from a successful call to the Create Token API.

Business Context

Here's the process flow:

Reverse Transactions Flow

  • The member undertakes a purchase journey and the account is debited appropriately. However, if for any reason a problem is detected post debit, the transaction will need to be reversed.
  • This is automatically performed within the partner application by means of a call to the Reverse Transaction endpoint.
  • This service creates a transaction that reverses the debit previously done as described above.

Important Technical Notes

  • All enumerated values must be recorded in upper case ASCII characters. Response messages will be returned in upper case.

Pre-conditions

  • An access token is obtained from a successful authentication call to the Create Token endpoint.
  • A transaction must have been created, which requires reversal.
  • The reversal request must be placed within the permitted time post the original transaction for it to get reversed.
  • The partner must be associated with BAEC programme as part of the standard partner on-boarding process.

Post-conditions

Success outcome: A reverse transaction is generated for the member's account with the original product value (credit).

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

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

Example

https://api.avios.com/v1/programmes/BAEC/accounts/36020200/reverse-transaction-requests?api_key=abcdef
NameData typeDescriptionExample
version
Required
StringThe version of the endpoint which will be confirmed during the on-boarding process.
Format: Alphanumeric v
v1
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: Currently restricted to ATRP or BAEC
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 configuration which takes place as part of the partner on-boarding process.
Format: Alphanumeric only. Min length = 24, Max length = 24
abcdabcdabcdabcdabcdabcd

Request Headers

NameData typeDescriptionExample
Authorization
Required
StringSecurity token authorising access to the specified member's account.
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/
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/
application/json
X-Forwarded-For
Optional
StringThe IP address of the end customer.
Format: Valid IP address
172.17.1.1
X-Agent-Id
Optional
StringAn agent Id represents the agent name/user name/login id for offline channels like call centres.
Format: Alphanumeric
Masanobu.Fukuoka

Request Elements

Example of a Request Call to the Reverse Transaction endpoint:

{
  "reversalTransaction": {
    "externalTransactionIdentifier": "12",
    "type": "CANCELLATION",
    "description": "dfs",
NameData typeDescription
externalTransactionIdentifier
Required
StringRepresents the transaction which was originally executed in the external system (i.e.: the external partner's system). Example: 12
Format: Alphanumeric with special characters: & . -
description
Required
StringDescription of the reversal transaction for which the request is placed.
Format: Alphanumeric with special characters: & . -
type
Required
StringReversal transaction type. This must be "CANCELLATION".
Format: Enumeration
reversedTransaction
Required
Complex type 1..1Contains the transaction that is to be reversed.
reversedTransaction.identifier
Required
StringThe identifier of the original or actual transaction that is to be reversed. Example: 3875243275815CB1E050A8C0020A4B4A
Format: Alphanumeric. Max length: 32

Response Elements

The following is an example of a response generated by the Reverse Transaction API:

{
  "reversalTransaction": {
    "identifier": "3875243275825CB1E050A8C0021A4B4A",
    "dateMade": "2016-12-19T10:46:00.696Z",
    "externalTransactionIdentifier": "12",

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

NameData typeDescription
identifier
Present
StringA transaction identifier that uniquely identify the debit or credit transaction specified in the request message. Example: 3875243275815CB1E050A8C0020A4B4A
Format: Alphanumeric. Min length: 1, Max length: 32
dateMade
Present
DateThis is the date that has been stored against the reversal transaction. Example: 2016-12-19T08:46:07.552Z
Format: ISO-8601
externalTransactionIdentifier
Present
StringThis identifies the transaction which was originally executed in the external system (i.e.: the external partner's system). Example: 12
Format: Alphanumeric with special characters: & . -
description
Present
StringReverse transaction description as placed in request. Example: dfs
Format: Alphanumeric with special characters: & . -
type
Present
StringReversal transaction type will always be "CANCELLATION".
Format: Enumeration
reversedTransaction
Present
Complex type 1..1Information describing the reversed transaction.
reversedTransaction.identifier
Present
StringIdentifier of original transaction which is reversed. Example: 3875243275815CB1E050A8C0020A4B4A
Format: Alphanumeric Max 32

Exception Message Elements

The following shows examples of error responses generated by the Reverse Transaction endpoint:

Example 1: Application error:

{
  "error": {
    "code": "REVERSAL_NO_LONGER_PERMITTED",
    "businessMessage": "Reversal No Longer Permitted",
    "developerLink": "https://developer.avios.com"

Example 2: Validation error:

{
  "error": {
    "code": "REQUEST_INVALID",
    "businessMessage": "Request Invalid",
    "developerLink": "https://developer.avios.com/docs",
NameData typeDescription
error.code
Present
StringError code. Example: REQUEST_INVALID
Format: Alphabetic plus underscore (
error.businessMessage
Present
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
Present
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. If the validation is done beyond the business api, then the path may not come.
Format: Alphabetic plus period (.), oblique (/), open bracket (
error.childError.businessMessage
Present
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
Present
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
Invalid enumeration in request or request not properly formed.
400
ACCOUNT_NOT_AUTHORIZED
Passed-in account id is cancelled, deceased, fraud or group.
400
REVERSAL_NO_LONGER_PERMITTED
Reversal request comes after permitted time post debit transaction.
400
REVERSAL_NOT_PERMITTED
It is not a debit transaction which was tried to reverse.
400
INVALID_MEMBER
If an invalid membership number is supplied from Offline channels.