Card Transactions

API Documentation

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.

Transaction Type

The type field describes the kind of transaction, such as a purchase, cash_withdrawal, refund, or balance_inquiry. Column sets it from the processing code sent by the card network when the transaction is created, and it does not change afterwards. This is different from the event_type of each transaction event, which describes a step in the transaction's lifecycle, such as an authorization, clearing, or reversal (see Event Types).

Combine type with point_of_sale_details.terminal_type to understand where the card was used. For example, an ATM withdrawal has a type of cash_withdrawal and a terminal_type of atm, whereas a cash advance at a bank teller has a terminal_type of attended.

Event Types

A card transaction is made up of one or more events, and each event's event_type describes one step in the transaction's lifecycle. A typical purchase starts with an authorization event that places a hold on the card account, followed by a clear event when the merchant settles it. Each event's amounts show how that step changed the funds held or settled on the card account (see Amounts).

Authorizations

Clearing

Refunds and Credits

Inquiries

Disputes

Reversals

Every event type ending in _reversal undoes all or part of an earlier event of the matching type, and its amounts have the opposite sign of the event it reverses. For example, an authorization_reversal releases some or all of the hold placed by an authorization, and a clear_reversal returns funds settled by a clear. Merchants and card networks send reversals when a transaction is canceled, times out, or was sent in error, and Column creates some itself, such as a dispute_credit_reversal when a dispute is resolved in the merchant's favor.

The reversal event types are financial_reversal, authorization_reversal, incremental_authorization_reversal, reauthorization_reversal, refund_authorization_reversal, refund_financial_reversal, clear_reversal, credit_clear_reversal, credit_applied_reversal, force_clear_reversal, original_credit_reversal, dispute_credit_reversal, and dispute_debit_reversal.

Webhook Events

The data of card transaction webhooks is the card transaction webhook payload, which contains two fields: card_transaction, the card transaction object without its events array, and latest_card_transaction_event, the card transaction event that triggered the webhook.

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.

The terminal_type field indicates where the card was accepted: an ATM, a merchant-staffed (attended) terminal, a self-service (unattended) terminal such as a fuel pump or kiosk, an online checkout (ecommerce), or a mail or telephone order.

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, and sends an issuing.card_transaction.transaction_data_updated webhook when it does.

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.