Introduction

The Transaction is a holistic representation of a single card transaction. Unlike Transaction Messages, which offer a segmented view, the Transaction aims to provide a comprehensive overview of the entire lifecycle of a single card tap or swipe. It amalgamates all relevant messages and states to offer a complete picture.

The Transaction enables an understanding of the status of a transaction and what to expect next. Specifically, it is valuable in understanding complex transaction lifecycles such as gas stations, offline (airplane), and others.

For the steps of a card transaction, see Home. For the individual message types that modify the Transaction, see Transaction Messages.

Transaction resource

Transaction `status`

Value	Definition
`PENDING`	This transaction has only seen non-financial messages → Expect a financial message
`VOIDED`	This transaction has a holdAmount of 0 and a settledAmount of 0 (due to an authorization reversal) → No further messages are expected.
`SETTLED`	We have processed a financial message for this transaction → no further messages are guaranteed, but may occur in a multiple completion scenario.
`DECLINED`	The initial authorization message for this transaction was declined and no money was moved.

Example Transaction Flows

There are many permutations for the flow of a transaction, with for example partial reversals, authorization advices and refunds all impacting the final state of a transaction.
Learn more about the different Message Types.

Here is a summary of how different Transaction Messages impact a Transaction:

Authorization Request → Financial Advice

In the most common scenario, an authorization request is approved and then followed by a financial advice, which triggers the movement of money from the cardholder’s account to the merchant’s account.

The financial advice can cover the full amount, a partial amount (in which case further financial advice messages may follow) or even an amount that exceeds the hold amount. A financial advice message with a partial amount can occur when a purchase is made for multiple goods and the authorization covers all of them, however as not all of them can be shipped at the same time, the financial messages only cover part as they are shipped.

A financial advice message with an amount that exceeds the hold amount can occur in situations where a tip, gratuity or other addition has been made after the original authorization request, but has not triggered an authorization advice (typically merchants do not trigger authorization advices unless the amount added is more than 25% of the original authorization request).

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 1100, 
  "transactionCurrency" : "USD",
  "status" : "SETTLED",
  "messages" : [
    {
      "link": "/transaction-messages/b64deaa6-5974-4e8a-afe9-83caa393fef5"
    },
    {
      "link": "/transaction-messages/e20feaa6-5974-4e8a-afe9-83caa393eaa7"
    }
  ]
}

Related Transaction Messages

{
  "id": "b64deaa6-5974-4e8a-afe9-83caa393fef5",
  "messageType": "AUTH_REQU",
  "createdDateTime": "2023-08-03 06:08:14", 
  "result": "APPROVED",
  "amount" : 1100
  ...
},
{
  "id": "e20feaa6-5974-4e8a-afe9-83caa393eaa7",
  "messageType": "FINL_ADVC",
  "createdDateTime": "2023-08-05 12:14:14", 
  "result": "APPROVED",
  "amount" : 1100
  ...
}

Authorization Request → Authorization Advice (negative amount)

In this scenario, the approved authorization request is being reversed (also called voided or cancelled) by an authorization advice with a negative amount, which removes the hold on the cardholder’s account. This happens when a merchant cancels a purchase before the money has moved between accounts.

Note that the authorization advice (negative amount) can also occur for partial amounts (e.g. when only part of the original purchase is cancelled).

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 0, 
  "transactionCurrency" : "USD",
  "status" : "VOIDED",
  "messages" : [
    {
        "link": "/transaction-messages/453bd8c8-2212-40f2-a1f5-b43547865630"
    },
    {
        "link": "/transaction-messages/b64deaa6-5974-4e8a-afe9-83caa393fef5"
    }
  ]
}

Related Transaction Messages

{
    "id": "453bd8c8-2212-40f2-a1f5-b43547865630",
    "messageType": "AUTH_REQU",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 1100
    ...
},
{
    "id": "b64deaa6-5974-4e8a-afe9-83caa393fef5",
    "messageType": "AUTH_ADVC",
    "createdDateTime": "2023-08-03 06:12:16", 
    "result": "APPROVED",
    "amount" : -1100
    ...
}

Authorization Request → Authorization Advice → Financial Advice

In cases like gas stations, hotels or car rentals, a “pre-authorization” is put through to hold a certain amount of money (i.e. making sure the cardholder has funds to actually pay). The pre-authorization amount is estimated, so it may differ from the final amount. The authorization advice updates the authorization amount to the final one.

In some cases, the authorization amount may be adjusted by a partial reversal (authorization advice with negative amount). You may also expect to receive a financial advice in the days following the authorization advice, typically with an amount correlating to that of the authorization advice (the example below shows such a case).

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 1300, 
  "transactionCurrency" : "USD",
  "status" : "PENDING",
  "messages" : [
    {
      "link": "/transaction-messages/b64deaa6-5974-4e8a-afe9-83caa393fef5"
    },
    {
      "link": "/transaction-messages/453bd8c8-2212-40f2-a1f5-b43547865630"
    },
    {
      "link": "/transaction-messages/381e9b8c-8580-4d22-9ff7-86c9e827618b"
    }
  ]
}

Related Transaction Messages

{
    "id": "b64deaa6-5974-4e8a-afe9-83caa393fef5",
    "messageType": "AUTH_REQU",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 1100
    ...
},
{
    "id": "453bd8c8-2212-40f2-a1f5-b43547865630",
    "messageType": "AUTH_ADVC",
    "createdDateTime": "2023-08-03 06:12:16", 
    "result": "APPROVED",
    "amount" : 1300
    ...
}
{
    "id": "381e9b8c-8580-4d22-9ff7-86c9e827618b",
    "messageType": "FINL_ADVC",
    "createdDateTime": "2023-08-06 09:48:31", 
    "result": "APPROVED",
    "amount" : 1300
    ...
}

Authorization Request → Financial Advice → Financial Advice (negative amount)

In this scenario, a cardholder makes a purchase and the transaction is first authorized and then a financial message debits the cardholder’s account. 5 days later, the cardholder returns the goods and the balance is returned to the cardholder’s account.

Note that the financial advice (negative amount) can also occur for partial amounts (e.g. when the cardholder only returns part of the original purchase).

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 0, 
  "transactionCurrency" : "USD",
  "status" : "VOIDED",
  "messages" : [
    {
      "link": "/transaction-messages/453bd8c8-2212-40f2-a1f5-b43547865630"
    },
    {
      "link": "/transaction-messages/b64deaa6-5974-4e8a-afe9-83caa393fef5"
    },
    {
      "link": "/transaction-messages/3c4b862f-607f-4873-be08-e5336d2c2745"
    }
  ]
}

Related Transaction Messages

{
    "id": "453bd8c8-2212-40f2-a1f5-b43547865630",
    "messageType": "AUTH_REQU",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 1000
    ...
},
{
    "id": "b64deaa6-5974-4e8a-afe9-83caa393fef5",
    "messageType": "FINL_ADVC",
    "createdDateTime": "2023-08-05 12:14:14", 
    "result": "APPROVED",
    "amount" : 1000
    ...
}
{
    "id": "3c4b862f-607f-4873-be08-e5336d2c2745",
    "messageType": "FINL_ADVC",
    "createdDateTime": "2023-08-10 16:00:21", 
    "result": "APPROVED",
    "amount" : -1000
    ...
}

Authorization Request

There are cases where the Transaction only contains one authorization. This can happen for a variety of reasons:
The Authorization was declined by the issuer - status is DECLINED.

The authorization was made for a nominal amount (such as $1) to test whether the account was valid and there was no intention to clear. The merchant did not clear in time and the authorization expired.

Authorization Holds and Expiry

When an issuer approves an authorization request, they place a hold on the cardholder’s account for the authorized amount to ensure that enough funds are available once the financial message comes through.

An authorization hold can last between up to 31 days after the authorization (dependent on card type, merchant type, whether it is a pre-authorization for e.g. card hire, etc).

As Astrada does not receive authorization expiry advices from the networks, you may wish to implement your own logic.

Transaction

{
  "transactionHoldAmount" : 1000,
  "transactionSettledAmount" : 0, 
  "transactionCurrency" : "USD",
  "status" : "PENDING",
  "messages" : [
    {
      "link": "/transaction-messages/3c4b862f-607f-4873-be08-e5336d2c2745"
    }
  ]
}

Related Transaction Messages

{
    "id": "3c4b862f-607f-4873-be08-e5336d2c2745",
    "messageType": "AUTH_REQU",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 1000
    ...
}

Financial Request (single message)

This type of transaction includes both the authorization and the financial message in one step and is therefore marked as SETTLED if it was approved by the issuer ("result": "APPROVED"). In case of a decline, the status will be DECLINED.

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 2000, 
  "transactionCurrency" : "USD",
  "status" : "SETTLED",
  "messages" : [
    {
      "link": "/transaction-messages/3c4b862f-607f-4873-be08-e5336d2c2745"
    }
  ]
}

Related Transaction Messages

{
    "id": "3c4b862f-607f-4873-be08-e5336d2c2745",
    "messageType": "FINL_REQU",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 2000
    ...
}

Financial Advice

Not all Financial Advices will be linked to an authorization. This happens e.g. in the case of offline authorizations. If no related message can be found, the financial advice triggers a new Transaction creation and is designated as SETTLED. This is also known as “force post”.

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : 2000, 
  "transactionCurrency" : "USD",
  "status" : "SETTLED",
  "messages" : [
    {
      "link": "/transaction-messages/3c4b862f-607f-4873-be08-e5336d2c2745"
    }
  ]
}

Related Transaction Messages

{
    "id": "3c4b862f-607f-4873-be08-e5336d2c2745",
    "messageType": "FINL_ADVC",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : 2000
    ...
}

Financial Advice (negative amount)

A financial advice with a negative amount denotes what may elsewhere be called a refund, return or original credit.
This message type does not always contain the relevant data points to map it to the original financial message which debited the cardholder. Where this is the case, a new Transaction is created and marked as SETTLED.

Transaction

{
  "transactionHoldAmount" : 0,
  "transactionSettledAmount" : -2000, 
  "transactionCurrency" : "USD",
  "status" : "SETTLED",
  "messages" : [
    {
      "link": "/transaction-messages/3c4b862f-607f-4873-be08-e5336d2c2745"
    }
  ]
}

Related Transaction Messages

{
    "id": "3c4b862f-607f-4873-be08-e5336d2c2745",
    "messageType": "FINL_ADVC",
    "createdDateTime": "2023-08-03 06:08:14", 
    "result": "APPROVED",
    "amount" : -2000
    ...
}

API

See our API reference with the endpoints available to get Transactions.

Introduction

Transaction resource

Transaction status

Example Transaction Flows

Authorization Request → Financial Advice

Transaction

Related Transaction Messages

Authorization Request → Authorization Advice (negative amount)

Transaction

Related Transaction Messages

Authorization Request → Authorization Advice → Financial Advice

Transaction

Related Transaction Messages

Authorization Request → Financial Advice → Financial Advice (negative amount)

Transaction

Related Transaction Messages

Authorization Request

Authorization Holds and Expiry

Transaction

Related Transaction Messages

Financial Request (single message)

Transaction

Related Transaction Messages

Financial Advice

Transaction

Related Transaction Messages

Financial Advice (negative amount)

Transaction

Related Transaction Messages

API

Transaction `status`