Payment Transaction Services Data Model

Table of Contents

Payments
- BLC_PAYMENT
Payment Transactions
- BLC_PAYMENT_TRANSACTION
Persistence Patterns
- Entity Versioning
- Payment Persistence Actions Do Not Cascade to the Payment Transactions

Figure 1. The following model shows the key tables and their relationships within the Payment Transaction Service.

Payments

Tip	See Payment and PaymentTransaction javadocs for further details.

BLC_PAYMENT

Field Description

Field	Description
ID	Unique row ID.
OWNER_TYPE	Describes the owner of the payment. For example, the payment could have originated with a cart or a subscription, therefore this value might be `CART` or `SUBSCRIPTION`.
OWNER_ID	The id of the entity that owns this payment. For example, this may be a cart id, or a subscription billing cycle id.
CUSTOMER_ID	The customer’s id.
IS_CUSTOMER_REGISTERED	Whether the customer is registered. If false, then the customer is considered anonymous.
ACCESS_RESTRICTIONS	The list of restrictions that apply to the customer’s ability to access the payment.
NAME	The name of this payment. This name is typically something like "Visa ending in 1234".
SAVED_PAYMENT_METHOD_ID	The id of the saved payment method that was used to build this payment object. Note: This property is only relevant if the user desires to use a saved payment method to pay for their order. Otherwise, this value should remain unset.
TYPE	The type of payment such as Credit Card or Gift Card.
GATEWAY_TYPE	The gateway used to process this payment. Only a SINGLE payment gateway can be used for a payment.
CURRENCY	The currency of the payment.
AMOUNT	The amount for which this payment is allotted.
SUBTOTAL	The payment’s total usually excluding adjustments, tax, and shipping.
ADJUSTMENTS_TOTAL	The payment’s adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.
FULFILLMENT_TOTAL	The payment’s total fulfillment cost.
FEES_TOTAL	The Payment’s total fees cost.
TAX_TOTAL	The payment’s total tax cost.
INCLUDED_TAX_TOTAL	The amount of taxes that are included in the subtotal.
ADDRESSES	The collection of related addresses that may include billing and/or shipping addresses.
PAYMENT_METHOD_PROPERTIES	Map to capture any information about the payment method needed to perform gateway transactions.
ATTRIBUTES	General use map to capture any additional attributes needed for this Payment.
DISPLAY_ATTRIBUTES	General use map to capture any display properties for this Payment.
SINGLE_USE_PAYMENT_METHOD	Whether the underlying payment method can only be used once.
SHOULD_SAVE_PMT_TO_CUSTOMER	Should the payment method be saved for future use by the customer. See Saving a Payment Method for Future Use for more details.
VERSION	The JPA managed version of this payment.

Unique row ID.

OWNER_TYPE

Describes the owner of the payment.

For example, the payment could have originated with a cart or a subscription, therefore this value might be CART or SUBSCRIPTION.

OWNER_ID

The id of the entity that owns this payment.

For example, this may be a cart id, or a subscription billing cycle id.

CUSTOMER_ID

The customer’s id.

IS_CUSTOMER_REGISTERED

Whether the customer is registered. If false, then the customer is considered anonymous.

ACCESS_RESTRICTIONS

The list of restrictions that apply to the customer’s ability to access the payment.

NAME

The name of this payment. This name is typically something like "Visa ending in 1234".

SAVED_PAYMENT_METHOD_ID

The id of the saved payment method that was used to build this payment object.

Note: This property is only relevant if the user desires to use a saved payment method to pay for their order. Otherwise, this value should remain unset.

TYPE

The type of payment such as Credit Card or Gift Card.

GATEWAY_TYPE

The gateway used to process this payment. Only a SINGLE payment gateway can be used for a payment.

CURRENCY

The currency of the payment.

AMOUNT

The amount for which this payment is allotted.

SUBTOTAL

The payment’s total usually excluding adjustments, tax, and shipping.

ADJUSTMENTS_TOTAL

The payment’s adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

FULFILLMENT_TOTAL

The payment’s total fulfillment cost.

FEES_TOTAL

The Payment’s total fees cost.

TAX_TOTAL

The payment’s total tax cost.

INCLUDED_TAX_TOTAL

The amount of taxes that are included in the subtotal.

ADDRESSES

The collection of related addresses that may include billing and/or shipping addresses.

PAYMENT_METHOD_PROPERTIES

Map to capture any information about the payment method needed to perform gateway transactions.

ATTRIBUTES

General use map to capture any additional attributes needed for this Payment.

DISPLAY_ATTRIBUTES

General use map to capture any display properties for this Payment.

SINGLE_USE_PAYMENT_METHOD

Whether the underlying payment method can only be used once.

SHOULD_SAVE_PMT_TO_CUSTOMER

Should the payment method be saved for future use by the customer.

See Saving a Payment Method for Future Use for more details.

VERSION

The JPA managed version of this payment.

Payment Transactions

BLC_PAYMENT_TRANSACTION

Field Description

Field	Description
ID	Unique row ID.
PAYMENT_ID	The id of the payment that this transaction belongs to.
TYPE	The type of this transaction (authorize, capture, refund, etc.)
GATEWAY_TRANSACTION_TYPE	The type of this transaction, as described by the gateway.
MANAGEMENT_STATE	The state of this transaction - e.g. whether the transaction is scheduled for reversal or if it’s being used in an active checkout. If the transaction was not successful, then we expect this value to be null.
STATUS	The status of the transaction.
TRANSACTION_REFERENCE_ID	The transaction id known by the payment gateway. This reference can be used to link the request to the gateway’s record of the transaction in the case that the calling application does not receive a response from the gateway.
GATEWAY_TRANSACTION_ID	The gateway-specific ID for the transaction.
SOURCE	The name of the system that initiated the transaction - e.g. `CART_OPERATION_SERVICES` vs `ORDER_OPERATION_SERVICES`.
PARENT_SOURCE_ENTITY_TYPE	The type of the parent source entity of the transaction that proceeded this transaction. This is used to identify the parent transaction instead of using the parent transaction id itself, because other systems have no knowledge of specific transactions.
PARENT_SOURCE_ENTITY_ID	The id of the parent source entity of the transaction that proceeded this transaction.
SOURCE_ENTITY_TYPE	The type of the source entity associated with the transaction. For example, `CHECKOUT_REQUEST` or `ORDER_FULFILLMENT`.
SOURCE_ENTITY_ID	The ID of the source entity associated with the transaction. For example, if `sourceEntityType` is `ORDER_FULFILLMENT`, this would be the ID of the OrderFulfillment.
REQUEST_ID	The id used to represent the request that produced this transaction.
CURRENCY	The currency of the payment transaction.
AMOUNT	The amount related to this transaction. Depending on the type, this may be the amount authorized, captured, refunded, etc.
SUBTOTAL	The transaction’s total usually excluding adjustments, tax, and shipping.
ADJUSTMENTS_TOTAL	The transaction’s adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.
FULFILLMENT_TOTAL	The transaction’s total fulfillment cost.
FEES_TOTAL	The transaction’s total fees cost.
TAX_TOTAL	The transaction’s total tax cost.
INCLUDED_TAX_TOTAL	The amount of taxes that are included in the subtotal.
DATE_RECORDED	The timestamp when this transaction response was recorded.
GATEWAY_RESPONSE_CODE	The response code provided by the payment gateway which may represent a success or failure.
FAILURE_TYPE	The type of transaction failure.
DECLINE_TYPE	The type of transaction failure (hard vs soft failure).
THREE_D_SEC_VERIFICATION_URL	The gateway-provided url where the customer must verify that they are in fact the owner of the payment method.
GATEWAY_MESSAGE	Message from the gateway describing the result of the transaction.
RAW_RESPONSE	The string representation of the serialized response from the gateway. This is usually the complete request parameter map serialized in string form.
PARENT_TRANSACTION_ID	The id of the parent PaymentTransaction. Necessary for operations on a payment that require a transaction to have been executed beforehand. For instance, an authorize transaction would not have a parent, but a capture must have an authorize parent transaction and a refund must have a capture parent transaction. See Identifying the Parent Transactions for more details.
ATTRIBUTES	Map of specific attributes that have been gathered from the raw response. This should be used for data points that are to be used programmatically. For example, a gateway-specific transaction id that can be used to capture or refund the transaction.
CUSTOMER_IP_ADDRESS	The customer IP address that instigated this transaction.
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).
VERSION	The JPA managed version of this payment.

Unique row ID.

PAYMENT_ID

The id of the payment that this transaction belongs to.

TYPE

The type of this transaction (authorize, capture, refund, etc.)

GATEWAY_TRANSACTION_TYPE

The type of this transaction, as described by the gateway.

MANAGEMENT_STATE

The state of this transaction - e.g. whether the transaction is scheduled for reversal or if it’s being used in an active checkout. If the transaction was not successful, then we expect this value to be null.

STATUS

The status of the transaction.

TRANSACTION_REFERENCE_ID

The transaction id known by the payment gateway. This reference can be used to link the request to the gateway’s record of the transaction in the case that the calling application does not receive a response from the gateway.

GATEWAY_TRANSACTION_ID

The gateway-specific ID for the transaction.

SOURCE

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

PARENT_SOURCE_ENTITY_TYPE

The type of the parent source entity of the transaction that proceeded this transaction.

This is used to identify the parent transaction instead of using the parent transaction id itself, because other systems have no knowledge of specific transactions.

PARENT_SOURCE_ENTITY_ID

The id of the parent source entity of the transaction that proceeded this transaction.

SOURCE_ENTITY_TYPE

The type of the source entity associated with the transaction. For example, CHECKOUT_REQUEST or ORDER_FULFILLMENT.

SOURCE_ENTITY_ID

The ID of the source entity associated with the transaction.

For example, if sourceEntityType is ORDER_FULFILLMENT, this would be the ID of the OrderFulfillment.

REQUEST_ID

The id used to represent the request that produced this transaction.

CURRENCY

The currency of the payment transaction.

AMOUNT

The amount related to this transaction. Depending on the type, this may be the amount authorized, captured, refunded, etc.

SUBTOTAL

The transaction’s total usually excluding adjustments, tax, and shipping.

ADJUSTMENTS_TOTAL

The transaction’s adjustments (a.k.a discounts) total, usually excluding shipping/fulfillment discounts.

FULFILLMENT_TOTAL

The transaction’s total fulfillment cost.

FEES_TOTAL

The transaction’s total fees cost.

TAX_TOTAL

The transaction’s total tax cost.

INCLUDED_TAX_TOTAL

The amount of taxes that are included in the subtotal.

DATE_RECORDED

The timestamp when this transaction response was recorded.

GATEWAY_RESPONSE_CODE

The response code provided by the payment gateway which may represent a success or failure.

FAILURE_TYPE

The type of transaction failure.

DECLINE_TYPE

The type of transaction failure (hard vs soft failure).

THREE_D_SEC_VERIFICATION_URL

The gateway-provided url where the customer must verify that they are in fact the owner of the payment method.

GATEWAY_MESSAGE

Message from the gateway describing the result of the transaction.

RAW_RESPONSE

The string representation of the serialized response from the gateway. This is usually the complete request parameter map serialized in string form.

PARENT_TRANSACTION_ID

The id of the parent PaymentTransaction. Necessary for operations on a payment that require a transaction to have been executed beforehand. For instance, an authorize transaction would not have a parent, but a capture must have an authorize parent transaction and a refund must have a capture parent transaction.

See Identifying the Parent Transactions for more details.

ATTRIBUTES

Map of specific attributes that have been gathered from the raw response. This should be used for data points that are to be used programmatically. For example, a gateway-specific transaction id that can be used to capture or refund the transaction.

CUSTOMER_IP_ADDRESS

The customer IP address that instigated this transaction.

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).

VERSION

The JPA managed version of this payment.

Persistence Patterns

Entity Versioning

JpaPayment and JpaPaymentTransaction are versioned entities, meaning that they have a numeric version that is incremented each time they are updated. Requests to modify a payment or execute a transaction must provide the version to verify that the request is not acting upon out-of-date data.

Modifying requests that supply an out-of-date (lower) version will be rejected with an HTTP 409 (Conflict). Clients of the API are expected to keep track of the payment version. Each API response will include the latest version.

Payment Persistence Actions Do Not Cascade to the Payment Transactions

Payment persistence actions don’t cascade to payment transactions. Instead, the persistence actions of JpaPaymentTransactions must be done completely independently of persistence actions of JpaPayments. This is done to avoid the unintentional loss of transaction data when persisting JpaPayment updates.