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)
- Values:
message_type— ISO 8583 protocol level: "What message was sent to the network?"- Values:
authorization,financial,reversal,advice - A single
PURCHASEcan generate multiple messages (auth → financial → reversal), each billed separately
- Values:
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_indicatorsarray cannot contain empty stringstransaction_statusis 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
