Transaction Metadata

Transaction metadata provides additional context about a payment transaction that affects fee calculations. It is passed in the txn_metadata field of transaction requests.

Structure

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "ECOM",
    "transaction_status": "NEW",
    "service_indicators": ["3ds_v2"],
    "authentication_method": "3ds",
    "terminal_id": "POS-001-GB",
    "message_type": null,
    "response_code": null,
    "eci": null,
    "cof_type": null,
    "cof_initiator": null,
    "wallet_type": null
  }
}

Required Fields

These three fields must be present in every request.

Field	Type	Values	Notes
transaction_type	string	PURCHASE, AUTHORISATION, REFUND, REVERSAL, CREDIT, CASH_ADVANCE, ATM, TRANSFER, CHARGEBACK, REPRESENTMENT, FUNDS_TRANSFER, INSTALLMENT	Case-insensitive
entry_mode	string	ECOM, CHIP, CONTACTLESS, MANUAL, MAGNETIC_STRIPE, TOKEN, CARD_ON_FILE, MAIL_ORDER, TELEPHONE_ORDER	Case-insensitive
transaction_status	string	NEW, AUTHORIZED, CHARGED, DECLINED, CREDITED, PREPARED, REFUNDED, CHARGEDBACK, REVERSED, ERROR, FRAUD, REJECTED	Case-insensitive

Optional Fields — Core

These fields improve fee matching accuracy. Send them when available.

Field	Type	Values	Notes
category	string	consumer, business, commercial, corporate, government, non_profit, educational	Usually auto-detected from BIN
service_indicators	string[]	3ds_v1, 3ds_v2, secure_code, identity_check, dynamic_linking_validation, obs_54, authentication, merchant_ucaf, full_ucaf	Auth indicators — affect fee conditions
authentication_method	string	3ds, 3ds_v1, 3ds_v2, secure_code, identity_check	Authentication method used
terminal_id	string	"POS-001-GB"	Terminal ID for POS transactions

Optional Fields — Tier 3 (Processor/Acquirer)

These fields are available to processors and acquirers with full ISO 8583 visibility. They significantly improve fee accuracy but are safe to omit for merchant or gateway integrations.

Field	Type	Values	Notes
message_type	string	authorization, financial, reversal, advice	ISO DE 0 — not the same as transaction_status
response_code	string	"00", "05", "51", "65", "80", "96"	ISO DE 39 — enables decline fees, reversal exclusions
eci	string	Visa: "05", "06", "07" / MC: "02", "01", "00"	3DS authentication result
cof_type	string	initial, subsequent	Credential-on-File type
cof_initiator	string	cardholder, merchant	CIT vs MIT
wallet_type	string	apple_pay, google_pay, samsung_pay, click_to_pay	Triggers VTS/MDES tokenization fees

message_type vs transaction_status

These are two distinct concepts:

• transaction_status — Business-level state: "What happened to the transaction?"

  • Values: NEW, AUTHORIZED, CHARGED, DECLINED, REVERSED, etc.
  • Used for fee exclusion (e.g., don't charge certain fees on declined transactions)

• message_type — ISO 8583 protocol level: "What message was sent to the network?"

  • Values: authorization, financial, reversal, advice
  • A single PURCHASE can generate multiple messages (auth → financial → reversal), each billed separately

Both can be sent — they serve different purposes in fee matching.

Extensibility

The txn_metadata object uses extra="allow" — any additional fields you include are preserved:

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "ECOM",
    "custom_field": "your-value",
    "internal_ref": "REF-12345"
  }
}

Usage Examples

E-commerce with 3DS

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "ECOM",
    "transaction_status": "NEW",
    "service_indicators": ["3ds_v2"],
    "authentication_method": "3ds"
  }
}

POS Transaction

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "CHIP",
    "transaction_status": "AUTHORIZED",
    "terminal_id": "POS-001-DE"
  }
}

Processor/Acquirer — Full Tier 3

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "ECOM",
    "transaction_status": "AUTHORIZED",
    "service_indicators": ["3ds_v2"],
    "authentication_method": "3ds",
    "message_type": "authorization",
    "response_code": "00",
    "eci": "05",
    "cof_type": "initial",
    "cof_initiator": "cardholder",
    "wallet_type": "apple_pay"
  }
}

Refund

{
  "txn_metadata": {
    "transaction_type": "REFUND",
    "entry_mode": "ECOM",
    "transaction_status": "CHARGED"
  }
}

Recurring / Subscription (Merchant-Initiated)

{
  "txn_metadata": {
    "transaction_type": "PURCHASE",
    "entry_mode": "CARD_ON_FILE",
    "cof_type": "subsequent",
    "cof_initiator": "merchant"
  }
}

Validation Rules

• Case-Insensitive: "purchase" or "PURCHASE" → both accepted
• Auto-Normalization: Values are converted to the correct format
• Dynamic Validation: Enum values are read from the database schema
• service_indicators array cannot contain empty strings
• transaction_status is required for all transactions

Impact on Fee Calculation

• Entry Mode: E-commerce vs POS have different fee structures
• Transaction Status: Different statuses may exclude certain fees
• Service Indicators: 3DS indicators may qualify for lower interchange
• ECI: Determines 3DS authentication result — more granular than authentication_method
• COF Type/Initiator: Visa and Mastercard have specific MIT vs CIT interchange programs
• Wallet Type: Apple Pay, Google Pay trigger tokenization fee lines
• Message Type: Scheme fees bill differently per message type
• Response Code: Enables decline-specific fees and reversal exclusion logic