Guides

Transaction

Suggest Edits

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

Attributes

Field nameRequired/ OptionalDescriptionType
id requiredThe identifier utilized to correlate a sequence of transaction messages, the unique identifier of this Transactionstring
uuid format
status requiredA semantic understanding of the state of the transaction within the transaction lifecycle.
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.		string enum: PENDING,VOIDED, DECLINED, SETTLED
transactionTypeoptionalTypes provide additional information about the transaction message, describing the effect that it had on the customer account and the type of accounts affected.

Learn more about Transaction Types.		string enum: Types
networkrequiredThe card network on which the message occurredstring enum: VISA,
MASTERCARD, UNKNOWN
subaccountIdrequiredThe Astrada Subaccount identifierstring
uuid format
transactionHoldAmountrequiredThis amount models the hold on the cardholder account that occurs after an authorization and before a financial message.
This amount will change as both authorization and financial messages are added to the Transaction in order to reflect the remaining hold amount.
Learn more about how the holdAmount is impacted in Example Transaction Flows

Note: Astrada does not receive authorization expiry advices from the networks. Learn more about Authorization Holds and Expiry.		number
transactionSettledAmountrequiredThe settled amount models the bottom line impact to the customer's bank statement.
This amount will change as financial messages are added to the Transaction.
Learn more about how the settledAmount is impacted in Example Transaction Flows		number
transactionCurrencyrequiredThe currency in which the transaction took placestring
ISO 4217 format, alpha3
cardholderBillingHoldAmountrequiredLike transactionHoldAmount, but in the cardholder’s billing currencynumber
cardholderBillingSettledAmountrequiredLike transactionSettledAmount, but in the cardholder’s billing currencynumber
cardholderBillingCurrencyrequiredThe currency that the cardholder is billed in (usually the currency of the country of issuance)string
ISO 4217 format, alpha3
cardIdrequiredThe tokenized card identifier used by Astradastring
uuid format
descriptorrequiredCleansed merchant name.string
messagesrequiredA list of all message events that have modified this transaction.
Learn more about Transaction Messages.

JSON

{
    "id": "FEDCBA0987654321",
    "status" : "SETTLED",
    "cardholderBillingHoldAmount": 0,
    "cardholderBillingSettledAmount": 1200,
    "cardholderBillingCurrency": "USD",
    "descriptor": "Uber",
    "network" : "VISA",
    "subaccountId": "453bd8c8-2212-40f2-a1f5-b43547865630",
    "transactionHoldAmount" : 0,
    "transactionSettledAmount" : 1200, 
    "transactionCurrency" : "USD",
    "messages" : [
        {
            "link": "/transaction-messages/b64deaa6-5974-4e8a-afe9-83caa393fef5"
        },
        {
            "link": "/transaction-messages/e20feaa6-5974-4e8a-afe9-83caa393eaa7"
        },
        {
            "link": "/transaction-messages/a699deaa6-5974-4e8a-afe9-83caa393fea6"
        }
    ],
    "cardId": "3c4b862f-607f-4873-be08-e5336d2c2745",
}

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.

Updated 19 days ago