Understanding Transaction Data

Table of Contents

Overview
Payment Transaction Notable Columns
Failed Transactions
Successful Transaction Examples
Failed Transaction Examples

Overview

A Payment (blc_payment) holds data about the payment method and the total amount that will be captured (e.g. credit card and $10). The Payment contains a collection of PaymentTransactions (blc_payment_transaction records) which are used to record transactional interactions with a payment gateway. In this section, we’ll dive into the details of blc_payment_transaction records to learn how to interpret these records and recognize various transaction scenarios.

Payment Transaction Notable Columns

Field Description

Field	Description
PAYMENT_ID	The primary key of the `blc_payment` record related to this transaction.
REQUEST_ID	The id representing the customer’s request to execute one or more transactions. This field can be used to identify transactions that were executed within the same process - e.g. the transactions executed during a checkout attempt.
TRANSACTION_REFERENCE_ID	A unique, Broadleaf-produced ID that is passed to the payment gateway, that can be used to link the Broadleaf representation of the transaction to the gateway’s representation of the transaction.
PARENT_TRANSACTION_ID	The id of the parent Payment Transaction. Necessary for operations on a payment that act upon a previously-executed transaction. For instance, a `CAPTURE` must act upon an `AUTHORIZE` parent transaction, and a `REFUND` must act upon a `CAPTURE` parent transaction. The full set of expected parent-child transaction relationships are as follows: Child Transaction → Parent Transaction Reverse Authorize → Authorize Capture → Authorize Refund → Capture Refund → AuthorizeAndCapture
SOURCE	The name of the system that initiated the transaction - e.g. `CART_OPERATION_SERVICES` or `ORDER_OPERATION_SERVICES`
SOURCE_ENTITY_TYPE	The type of the source entity associated with the transaction - e.g. `CHECKOUT_REQUEST` or `ORDER_FULFILLMENT`
SOURCE_ENTITY_ID	The ID of the source entity associated with the transaction - e.g. the checkout request ID or the OrderFulfillment’s ID
PARENT_SOURCE_ENTITY_TYPE	The type of the source entity of the transaction that proceeded this transaction. This is used to identify the parent transactions within the same entity. For example, the execution of a refund transaction requires a proceeding capture or authorize and capture transaction. Let’s say the proceeding capture transaction has the source entity type of `ORDER_FULFILLMENT`, and the refund transaction has the entity source type of `RETURN_CONFIRMATION`. In this case, the refund transaction request needs the parent source entity type of `ORDER_FULFILLMENT` and its id in order to identify the parent capture transaction. Note that if this field is not provided, it will retrieve parent transactions from any entity based on `paymentId` and `transactionType`
PARENT_SOURCE_ENTITY_ID	The ID of the source entity of the transaction that proceeded this transaction.
TYPE	The type of this transaction. See the Transaction Types section below for more details on the possible types.
STATUS	The status of the transaction. See the Transaction Statuses section below for more details.
MANAGEMENT_STATE	Describes how a transaction is being used, esp. if it needs to be reversed or if it has been reversed. See the Management States section below for more details on the possible states.
INDETERMINATE_RESULT	Tells if this transaction has an indeterminate result. Having an indeterminate result means that the true outcome of the transaction is not known. For example, if a transaction is sent to the payment processor but a network error occurred, it is not known to us whether the user was actually charged or not (thus, the result is indeterminate). Transactions should be marked as indeterminate when sending to the payment processor, and then unmarked once a response is received, understood, and recorded. This means that a transaction in an indeterminate result state is <em>expected</em> during the sending to processor phase. However, if the transaction remains in that state for an excessive amount of time, something likely went wrong and the transaction will need to be reconciled. If the transaction changes from the sending to processor status but remains indeterminate, the transaction will also require reconciliation in that scenario. Some situations which may lead to an indeterminate result: A transaction request is sent to the processor, but a network error prevents the payment gateway from receiving the request A transaction request is sent to the processor, but a network error prevents us from receiving the response A transaction request is sent to the processor, but the processor returns an unexpected error (e.g. 500 internal server error) A transaction request is sent to the processor and a response is received from the payment gateway, but the result cannot be recorded because the database is down

PAYMENT_ID

The primary key of the blc_payment record related to this transaction.

REQUEST_ID

The id representing the customer’s request to execute one or more transactions. This field can be used to identify transactions that were executed within the same process - e.g. the transactions executed during a checkout attempt.

TRANSACTION_REFERENCE_ID

A unique, Broadleaf-produced ID that is passed to the payment gateway, that can be used to link the Broadleaf representation of the transaction to the gateway’s representation of the transaction.

PARENT_TRANSACTION_ID

The id of the parent Payment Transaction.

Necessary for operations on a payment that act upon a previously-executed transaction. For instance, a CAPTURE must act upon an AUTHORIZE parent transaction, and a REFUND must act upon a CAPTURE parent transaction. The full set of expected parent-child transaction relationships are as follows:

Child Transaction → Parent Transaction

Reverse Authorize → Authorize

Capture → Authorize

Refund → Capture

Refund → AuthorizeAndCapture

SOURCE

The name of the system that initiated the transaction - e.g. CART_OPERATION_SERVICES or ORDER_OPERATION_SERVICES

SOURCE_ENTITY_TYPE

The type of the source entity associated with the transaction - e.g. CHECKOUT_REQUEST or ORDER_FULFILLMENT

SOURCE_ENTITY_ID

The ID of the source entity associated with the transaction - e.g. the checkout request ID or the OrderFulfillment’s ID

PARENT_SOURCE_ENTITY_TYPE

The type of the source entity of the transaction that proceeded this transaction. This is used to identify the parent transactions within the same entity.

For example, the execution of a refund transaction requires a proceeding capture or authorize and capture transaction. Let’s say the proceeding capture transaction has the source entity type of ORDER_FULFILLMENT, and the refund transaction has the entity source type of RETURN_CONFIRMATION. In this case, the refund transaction request needs the parent source entity type of ORDER_FULFILLMENT and its id in order to identify the parent capture transaction.

Note that if this field is not provided, it will retrieve parent transactions from any entity based on paymentId and transactionType

PARENT_SOURCE_ENTITY_ID

The ID of the source entity of the transaction that proceeded this transaction.

TYPE

The type of this transaction.

See the Transaction Types section below for more details on the possible types.

STATUS

The status of the transaction.

See the Transaction Statuses section below for more details.

MANAGEMENT_STATE

Describes how a transaction is being used, esp. if it needs to be reversed or if it has been reversed.

See the Management States section below for more details on the possible states.

INDETERMINATE_RESULT

Tells if this transaction has an indeterminate result.

Having an indeterminate result means that the true outcome of the transaction is not known. For example, if a transaction is sent to the payment processor but a network error occurred, it is not known to us whether the user was actually charged or not (thus, the result is indeterminate).

Transactions should be marked as indeterminate when sending to the payment processor, and then unmarked once a response is received, understood, and recorded. This means that a transaction in an indeterminate result state is <em>expected</em> during the sending to processor phase. However, if the transaction remains in that state for an excessive amount of time, something likely went wrong and the transaction will need to be reconciled. If the transaction changes from the sending to processor status but remains indeterminate, the transaction will also require reconciliation in that scenario.

Some situations which may lead to an indeterminate result:

A transaction request is sent to the processor, but a network error prevents the payment gateway from receiving the request
A transaction request is sent to the processor, but a network error prevents us from receiving the response
A transaction request is sent to the processor, but the processor returns an unexpected error (e.g. 500 internal server error)
A transaction request is sent to the processor and a response is received from the payment gateway, but the result cannot be recorded because the database is down

Transaction Types

The transaction type is used to represent the types of operations/transactions that could occur against a single payment.

The default list of transaction types:

Type Description

Type	Description
AUTHORIZE	Funds have been authorized for capture. These transactions represent a temporary reserve on the customer’s funds, and they often auto-expire after a period of time.
REVERSE_AUTH	The reverse of an `AUTHORIZE` transaction - i.e. the release of the temporary reservation. NOTE: Some payment gateways refer to this transaction type as a "Void".
CAPTURE	Funds have been charged/submitted/debited from the customer and payment is complete. Can `ONLY` occur after an amount has been authorized (`AUTHORIZE`)
AUTHORIZE_AND_CAPTURE	Funds have been authorized and captured all at once. While this might be the simplest to implement from an order management perspective, the recommended approach is to `AUTHORIZE` and then `CAPTURE` in separate transactions and at separate times. For instance, an `AUTHORIZE` would happen once the order has completed checkout but then a `CAPTURE` would happen once the order has shipped NOTE: Many gateways like to refer to this as also a SALE transaction. The outcome of this transaction type should be treated the exact same as a `CAPTURE` transaction.
REFUND	Funds have been refunded/credited. This can `ONLY` occur after funds have been captured. This assumes that there will be a parent `AUTHORIZE_AND_CAPTURE` or `CAPTURE` transaction that this can be tied back to. NOTE: This can also be referred to as a "follow-on credit"
DETACHED_CREDIT	Some payment processors allow you to issue credit to a customer that is not tied to an initial `AUTHORIZE` or `AUTHORIZE_AND_CAPTURE` transaction. Most payment gateways disable this feature by default because it is against card association (e.g. Visa, MasterCard) rules. However, there may be legitimate instances where you had a sale transaction but are not able to issue a refund (e.g. closed account of original payment etc…) Please contact your payment gateway provider to see how to enable this feature. NOTE: This is also sometimes referred to as a "blind credit" or "stand-alone credit"

AUTHORIZE

Funds have been authorized for capture. These transactions represent a temporary reserve on the customer’s funds, and they often auto-expire after a period of time.

REVERSE_AUTH

The reverse of an AUTHORIZE transaction - i.e. the release of the temporary reservation.

NOTE: Some payment gateways refer to this transaction type as a "Void".

CAPTURE

Funds have been charged/submitted/debited from the customer and payment is complete. Can ONLY occur after an amount has been authorized (AUTHORIZE)

AUTHORIZE_AND_CAPTURE

Funds have been authorized and captured all at once. While this might be the simplest to implement from an order management perspective, the recommended approach is to AUTHORIZE and then CAPTURE in separate transactions and at separate times. For instance, an AUTHORIZE would happen once the order has completed checkout but then a CAPTURE would happen once the order has shipped

NOTE: Many gateways like to refer to this as also a SALE transaction.

The outcome of this transaction type should be treated the exact same as a CAPTURE transaction.

REFUND

Funds have been refunded/credited. This can ONLY occur after funds have been captured. This assumes that there will be a parent AUTHORIZE_AND_CAPTURE or CAPTURE transaction that this can be tied back to.

NOTE: This can also be referred to as a "follow-on credit"

DETACHED_CREDIT

Some payment processors allow you to issue credit to a customer that is not tied to an initial AUTHORIZE or AUTHORIZE_AND_CAPTURE transaction. Most payment gateways disable this feature by default because it is against card association (e.g. Visa, MasterCard) rules. However, there may be legitimate instances where you had a sale transaction but are not able to issue a refund (e.g. closed account of original payment etc…) Please contact your payment gateway provider to see how to enable this feature.

NOTE: This is also sometimes referred to as a "blind credit" or "stand-alone credit"

Transaction Statuses

The status is used to describe the current status of the transaction.

Status Description

Status	Description
SENDING_TO_PROCESSOR	The payment gateway call is being prepared, or has been made, and we don’t know the response yet. Transactions can remain in this status if the application restarts or if we encounter an unexpected network failure. If a transaction is in this state for an extended period of time, then it should be researched with the payment gateway to determine the result. In this case, the result will be indeterminate, and we expect the `INDETERMINATE_RESULT` column to be equal to `'Y'`.
REQUIRES_3DS_VERIFICATION	The transaction was received by the payment gateway, but they have requested 3DS verification from the customer before the transaction can be executed. If this status is present, then the `THREE_D_SEC_VERIFICATION_URL` column should contain the URL where the customer will need to be redirected to.
SUCCESS	The transaction was successfully processed by the payment gateway
FAILURE	The payment gateway failed to successfully process the transaction. This primarily represents a declined payment

SENDING_TO_PROCESSOR

The payment gateway call is being prepared, or has been made, and we don’t know the response yet. Transactions can remain in this status if the application restarts or if we encounter an unexpected network failure. If a transaction is in this state for an extended period of time, then it should be researched with the payment gateway to determine the result. In this case, the result will be indeterminate, and we expect the INDETERMINATE_RESULT column to be equal to 'Y'.

REQUIRES_3DS_VERIFICATION

The transaction was received by the payment gateway, but they have requested 3DS verification from the customer before the transaction can be executed. If this status is present, then the THREE_D_SEC_VERIFICATION_URL column should contain the URL where the customer will need to be redirected to.

SUCCESS

The transaction was successfully processed by the payment gateway

FAILURE

The payment gateway failed to successfully process the transaction. This primarily represents a declined payment

Management State

Management States Description

Management States	Description
AUTOMATIC_REVERSAL_NOT_ALLOWED	Represents a transaction that cannot be reversed automatically by scheduled jobs. For example, an `AUTHORIZE` transaction can be reversed by executing a `REVERSE_AUTHORIZE` transaction by an external system. However, it will not be picked up by the `MarkPaymentTransactionsForReversalListener` scheduled job.
REQUIRES_REVERSAL	Represents a transaction that is needs to be reversed.
REVERSAL_IN_PROGRESS	Represents a transaction that is being actively reversed.
REVERSED	Represents a transaction that has been successfully reversed.
FAILED_REVERSAL	Represents a transaction that was not able to be reversed. This state likely requires manual review & reconciliation.
REVERSAL_TRANSACTION	Represents a transaction that reversed another transaction.

AUTOMATIC_REVERSAL_NOT_ALLOWED

Represents a transaction that cannot be reversed automatically by scheduled jobs. For example, an AUTHORIZE transaction can be reversed by executing a REVERSE_AUTHORIZE transaction by an external system. However, it will not be picked up by the MarkPaymentTransactionsForReversalListener scheduled job.

REQUIRES_REVERSAL

Represents a transaction that is needs to be reversed.

REVERSAL_IN_PROGRESS

Represents a transaction that is being actively reversed.

REVERSED

Represents a transaction that has been successfully reversed.

FAILED_REVERSAL

Represents a transaction that was not able to be reversed. This state likely requires manual review & reconciliation.

REVERSAL_TRANSACTION

Represents a transaction that reversed another transaction.

Failed Transactions

When the error occurred during the execution of the transaction it will contain the information about the error. The status of failed transaction will be FAILURE.

The key fields to analyze an error:

FAILURE_TYPE - The type of transaction failure
GATEWAY_RESPONSE_CODE - The response code provided by the payment gateway which may represent a success or failure
GATEWAY_MESSAGE - Message from the gateway describing the result of the transaction
RAW_RESPONSE - The string representation of the serialized response from the gateway.

The default failure types:

Failure	Description
GATEWAY_CREDENTIALS_ERROR	The provided payment gateway credentials are not valid
GATEWAY_CONFIGURATION_ERROR	The gateway is incorrectly configured or is not configured to handle the attempted type of request
INVALID_REQUEST	There was a failure to process the request because the request itself is invalid
INVALID_PAYMENT_METHOD	The provided payment method data is invalid. This could be an incorrect card number, expiration date, etc
PROCESSING_FAILURE	The payment gateway failed to successfully process the transaction. This primarily represents a declined payment
REQUIRES_3DS_VERIFICATION	Additional verification is required from the customer for the gateway to successfully process the transaction
REQUIRES_ADDITIONAL_ACTION	Additional action is required for the transaction to be successfully processed
GATEWAY_ERROR	There was an unexpected error with the payment gateway itself
NETWORK_ERROR	There was an error in communicating with the payment gateway. This can correlate to a known network failure/timeout or connection issue
RESPONSE_VALIDATION_FAILURE	There was an error when checking the validity of the response. Therefore, we’re unsure if we can trust the contents of the response. In this case, it’s best to treat the transaction as a failure and investigate it offline
API_RATE_LIMIT_ERROR	An error that occurs when too many requests hit the gateway’s API too quickly
INTERNAL_ERROR	There was an error in our preparation of the gateway interaction or in our interpretation/storing of the response

Failure

Description

GATEWAY_CREDENTIALS_ERROR

The provided payment gateway credentials are not valid

GATEWAY_CONFIGURATION_ERROR

The gateway is incorrectly configured or is not configured to handle the attempted type of request

INVALID_REQUEST

There was a failure to process the request because the request itself is invalid

INVALID_PAYMENT_METHOD

The provided payment method data is invalid. This could be an incorrect card number, expiration date, etc

PROCESSING_FAILURE

The payment gateway failed to successfully process the transaction. This primarily represents a declined payment

REQUIRES_3DS_VERIFICATION

Additional verification is required from the customer for the gateway to successfully process the transaction

REQUIRES_ADDITIONAL_ACTION

Additional action is required for the transaction to be successfully processed

GATEWAY_ERROR

There was an unexpected error with the payment gateway itself

NETWORK_ERROR

There was an error in communicating with the payment gateway. This can correlate to a known network failure/timeout or connection issue

RESPONSE_VALIDATION_FAILURE

There was an error when checking the validity of the response. Therefore, we’re unsure if we can trust the contents of the response. In this case, it’s best to treat the transaction as a failure and investigate it offline

API_RATE_LIMIT_ERROR

An error that occurs when too many requests hit the gateway’s API too quickly

INTERNAL_ERROR

There was an error in our preparation of the gateway interaction or in our interpretation/storing of the response

Successful Transaction Examples

Authorize Transaction

  {
    "id": "01FYBWMKPKSR4M0NM8YD9N0GQ0",
    "payment_id": "01FYBVP25SS9PN0H6B9YDK0CDN",
    "transaction_reference_id": "01FYBWMKP8MKAV1VTBDF1G03YM",
    "type": "AUTHORIZE",
    "amount": 19.19000,
    "status": "SUCCESS",
    "source": "CART_OPERATION_SERVICES",
    "request_id": "01FYBWMBWR1YY315QNJXZT1YS4",
    "source_entity_id": "01FYBWMBWR1YY315QNJXZT1YS4",
    "source_entity_type": "CHECKOUT_REQUEST",
    "date_recorded": "2022-03-17 12:11:32.725000",
    "management_state": "AUTOMATIC_REVERSAL_NOT_ALLOWED",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Authorize and Capture Transaction

  {
    "id": "01FYBXJ6J60MSR1X63T8KS1GYT",
    "payment_id": "01FYBXHXDXPP7S02QS4XRY1Z7A",
    "transaction_reference_id": "01FYBXJ6HSW6NJ1M4M5J8V1VSN",
    "type": "AUTHORIZE_AND_CAPTURE",
    "amount": 19.19000,
    "status": "SUCCESS",
    "source": "CART_OPERATION_SERVICES",
    "request_id": "01FYBXJ2V6NKD30S7MST5H10JW",
    "source_entity_id": "01FYBXJ2V6NKD30S7MST5H10JW",
    "source_entity_type": "CHECKOUT_REQUEST",
    "date_recorded": "2022-03-17 12:27:43.384000",
    "management_state": "AUTOMATIC_REVERSAL_NOT_ALLOWED",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Capture Transaction

  {
    "id": "01FYC570Y3AT6H1MV50V2E0PJK",
    "parent_transaction_id": "01FYC55DMQ61KV05H0ZDBC05JV",
    "payment_id": "01FYC4VNW9XMAP0738AK9A1ZZJ",
    "transaction_reference_id": "01FYC570Y2R2AG13N5541W0DWK",
    "type": "CAPTURE",
    "amount": 16.99000,
    "status": "SUCCESS",
    "source": "ORDER_OPERATION_SERVICES",
    "request_id": "01FYC570XC4VJA0DXHCS1Z0AH7",
    "source_entity_id": "01FYC55ZFFEXQD17K77HGG06AY",
    "source_entity_type": "ORDER_FULFILLMENT",
    "date_recorded": "2022-03-17 14:41:24.436000",
    "management_state": "AUTOMATIC_REVERSAL_NOT_ALLOWED",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Refund Transaction

  {
    "id": "01FYC5BWJP8EJZ0K5SPK5604ZP",
    "parent_transaction_id": "01FYC570Y3AT6H1MV50V2E0PJK",
    "payment_id": "01FYC4VNW9XMAP0738AK9A1ZZJ",
    "transaction_reference_id": "01FYC5BWJN1KQ70C35EJCW1QQC",
    "type": "REFUND",
    "amount": 16.99000,
    "status": "SUCCESS",
    "source": "ORDER_OPERATION_SERVICES",
    "request_id": "01FYC5BWJ5607Q0T0XT8CP189Z",
    "source_entity_id": "01FYC5BW30470A1A5MRW2V1243",
    "source_entity_type": "RETURN_CONFIRMATION",
    "parent_source_entity_id": "01FYC55ZFFEXQD17K77HGG06AY",
    "parent_source_entity_type": "ORDER_FULFILLMENT",
    "date_recorded": "2022-03-17 14:44:03.815000",
    "management_state": "AUTOMATIC_REVERSAL_NOT_ALLOWED",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Failed Transaction Examples

Failed Authorization Transaction (Insufficient Funds)

  {
    "id": "01FYC6A07YAD690SPTYKP203HE",
    "payment_id": "01FYC69TFVXXPQ07XB8THQ1P6Z",
    "transaction_reference_id": "01FYC6A07XTARP1HCDP4AG1TBM",
    "type": "AUTHORIZE",
    "amount": 16.99000,
    "status": "FAILURE",
    "decline_type": "HARD",
    "failure_type": "PROCESSING_FAILURE",
    "gateway_response_code": "insufficient_funds",
    "gateway_message": "Insufficient funds",
    "source": "CART_OPERATION_SERVICES",
    "request_id": "01FYC69VVJAM3Z0V120ZAJ07QB",
    "source_entity_id": "01FYC69VVJAM3Z0V120ZAJ07QB",
    "source_entity_type": "CHECKOUT_REQUEST",
    "date_recorded": "2022-03-17 12:11:32.725000",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Authorization Transaction Requiring 3DS Verification

  {
    "id": "01FYC6A07YAD690SPTYKP203HE",
    "payment_id": "01FYC69TFVXXPQ07XB8THQ1P6Z",
    "transaction_reference_id": "01FYC6A07XTARP1HCDP4AG1TBM",
    "type": "AUTHORIZE",
    "amount": 16.99000,
    "status": "FAILURE",
    "decline_type": "SOFT",
    "failure_type": "REQUIRES_3DS_VERIFICATION",
    "gateway_response_code": "REQUIRES_3DS_VERIFICATION",
    "gateway_message": "Requires 3DS verification",
    "three_d_sec_verification_url": "https://my.cc.processor.com/3DS-verification",
    "source": "CART_OPERATION_SERVICES",
    "request_id": "01FYC69VVJAM3Z0V120ZAJ07QB",
    "source_entity_id": "01FYC69VVJAM3Z0V120ZAJ07QB",
    "source_entity_type": "CHECKOUT_REQUEST",
    "date_recorded": "2022-03-17 12:11:32.725000",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }

Indeterminate result

  {
    "id": "01FYC5NDKR38PK1QZPKKY51Y21",
    "payment_id": "01FYC5N695M17W11C31VGX0MH6",
    "transaction_reference_id": "01FYC5NDKQYP8V0DPPFQBW160A",
    "type": "AUTHORIZE",
    "amount": 19.19000,
    "status": "SENDING_TO_PROCESSOR",
    "indeterminate_result": "Y",
    "source": "CART_OPERATION_SERVICES",
    "request_id": "01FYC5N9KXRG600EN5KESE131E",
    "source_entity_id": "01FYC5N9KXRG600EN5KESE131E",
    "source_entity_type": "CHECKOUT_REQUEST",
    "date_recorded": "2022-03-17 14:49:16.151000",
    ...
    "trk_tenant_id": "5DF1363059675161A85F576D",
    "version": 2
  }