Card Issuing
Card Transactions
A card transaction represents a single financial operation on a card. Examples could include a purchase, refund, original credit, authorization, etc. The transaction object contains all metadata about the transaction itself, as well as the card account that the transaction was performed on. It also includes the timeline of the transaction and the amount of money involved through associated transaction events.
Metadata Fields
Card Acceptor Details
This struct contains information about the acquirer and merchant that processed the transaction. The name field is
typically what is used as the descriptor on a card statement. The identifier, terminal_identifier,
acquiring_institution_identifier, and forwarding_institution_identifier fields are card network assigned values for
the various parties involved in the transaction.
The merchant category code is included in this struct, which is a commonly used field for spend controls and providing category-based rewards. Column currently does not normalize this code and passes back the code directly from the card network, so it will vary depending on the network a transaction is processed on.
Network Details
Network details contain information about the card network that processed the transaction. The identifier in this struct are all network-specific values and are handled internally by Column for operations such as linking events and transactions together. These values could be useful to you if you use an external vendor for handling disputes.
Point of Sale Details
This struct contains information about how the card was presented and processed when the transaction was created. This information is useful for fraud scoring and enforcing restrictions about how a card can be used.
Cardholder Verification Details
This struct contains the values and evaluation outcomes of information passed by the acquirer about the cardholder including name, address, email, phone number, etc. This information can be used by your system for fraud scoring and approval rules.
Authentication Details
This struct contains information about card authentication outcomes, specifically 3DS. This data indicates if a transaction is approved, if your program assumes liability for fraud-related chargebacks.
Fee Details
This struct will contain information about any fees assessed by the acceptor that are included in the transaction. Common fees that would be assessed are ATM usage fees, card surcharges, dynamic currency conversion assessments, etc.
Recurring Transaction Details
This struct contains information about merchant-initiated recurring payments. Column will flag when a merchant requests that a card be used for future recurring payments, and the validity of recurring payments in this struct.
Note: some merchants are permitted to submit merchant initiated transactions based on their type, for example, many travel and entertainment merchants are permitted to submit additional transactions without first establishing a recurring contract.
Transaction Details
This struct contains level 3 data about the transaction such as hotel folio information, fuel filler metadata, line-item transaction data, and more. In most cases, L3 data is included in clearing records, so data will be populated in the transaction after the initial authorization. Column will populate this field once the information is received from the associated card network.
Amounts
A core data model of the card transaction are the total_amounts struct and the amounts struct in each associated
transaction event. These structs contain various fields that represent funds held and cleared from both the merchant and
cardholder perspectives.
Each transaction event contains six amount types:
- Merchant Requested: The amount requested by the merchant.
- Cardholder Requested: The amount requested by the merchant in the currency of the card.
- Merchant Authorized: The amount being held on the card account in the merchant's currency.
- Cardholder Authorized: The amount being held on the card account in the cardholder's currency.
- Merchant Settled: The amount settled on the card account in the merchant's currency.
- Cardholder Settled: The amount settled on the card account in the cardholder's currency.
If the merchant and cardholder currencies are the same, the amounts between merchant and cardholder will be the same. However, if they are different, the amounts will show the FX information between the two currencies and the actual amounts being held or settled against the card account.
There are two places where amounts are stored: in the transaction object itself and in transaction events. The top-level
total_amounts struct contains a simple sum of the authorized and settled amounts in the transaction events and represents
the current total accounting of funds that have been held or settled on the card account. It does not include the
requested amounts.
When reading amounts in these structs, negative amounts indicate funds being held/withdrawn from the card account, whereas positive amounts indicate funds being released/deposited into the card account.
Amounts Examples
Let's assume a card is used at a hotel and $500 AUD is authorized and the exchange rate is 1 AUD = 0.5 USD. The current state would look like (note that non-amount fields and the requested amounts on events are removed for brevity):
{
"total_amounts": {
"merchant_authorized": {
"currency_code": "AUD",
"amount": -50000
},
"cardholder_authorized": {
"currency_code": "USD",
"amount": -25000,
"fx_rate": "0.5"
},
"merchant_settled": {
"currency_code": "AUD",
"amount": 0
},
"cardholder_settled": {
"currency_code": "USD",
"amount": 0
}
},
"events": [
{
"event_type": "authorization",
"amounts": {
"merchant_authorized": {
"currency_code": "AUD",
"amount": -50000
},
"cardholder_authorized": {
"currency_code": "USD",
"amount": -25000,
"fx_rate": "0.5"
},
"merchant_settled": {
"currency_code": "AUD",
"amount": 0
},
"cardholder_settled": {
"currency_code": "USD",
"amount": 0
}
}
}
]
}Now, let's assume the hotel only clears $400 AUD. Another event will be appended to the card transaction representing clearing, and the total amounts at the top level change to be the sum of the two events. Note that the full amount is released after clearing in this example, but depending on the merchant or transaction type this will not always be the case.
{
"total_amounts": {
"merchant_authorized": {
"currency_code": "AUD",
"amount": 0
},
"cardholder_authorized": {
"currency_code": "USD",
"amount": 0
},
"merchant_settled": {
"currency_code": "AUD",
"amount": -40000
},
"cardholder_settled": {
"currency_code": "USD",
"amount": -20000
}
},
"events": [
{
"event_type": "authorization",
"amounts": {
"merchant_authorized": {
"currency_code": "AUD",
"amount": -50000
},
"cardholder_authorized": {
"currency_code": "USD",
"amount": -25000,
"fx_rate": "0.5"
},
"merchant_settled": {
"currency_code": "AUD",
"amount": 0
},
"cardholder_settled": {
"currency_code": "USD",
"amount": 0
}
}
},
{
"event_type": "clear",
"amounts": {
"merchant_authorized": {
"currency_code": "AUD",
"amount": 50000
},
"cardholder_authorized": {
"currency_code": "USD",
"amount": 25000,
"fx_rate": "0.5"
},
"merchant_settled": {
"currency_code": "AUD",
"amount": -40000
},
"cardholder_settled": {
"currency_code": "USD",
"amount": -20000,
"fx_rate": "0.5"
}
}
}
]
}After the authorization and clear, we can see we're left with $200 USD that was settled out of the card account and no funds held.