Mastercard

Network Detection

Mastercard cards are detected by PAN prefix:

51-55 (traditional)
2221-2720 (2-series BINs)
16 digits

from iso8583sim.core.types import detect_network, CardNetwork

network = detect_network("5500000000000004")
assert network == CardNetwork.MASTERCARD

network = detect_network("2221000000000009")
assert network == CardNetwork.MASTERCARD

Required Fields

Mastercard authorization requests require:

Field	Name	Format
2	PAN	LLVAR (16 digits)
3	Processing Code	n6
4	Amount	n12
11	STAN	n6
22	POS Entry Mode	n3
24	NII	n3
25	POS Condition Code	n2

Note: Field 14 (Expiration) is optional but recommended.

Mastercard-Specific Fields

Field 48 - Additional Data

Mastercard’s field 48 starts with a one-character transaction category code (for example R for retail), followed by any number of subelements. Each subelement is a 2-digit ID, a 2-digit length, then that many characters:

message.fields[48] = "R0103ABC"  # TCC "R", then subelement 01 with 3 characters "ABC"

The validator checks this layout and reports truncated or misaligned subelements.

Field 61 - POS Data Extended

Extended point-of-service data:

# Format varies by transaction type
message.fields[61] = "0000000001"

DE127 - Private Data

Mastercard’s Data Element 127 contains subfields for network data.

POS Entry Modes (Field 22)

Common Mastercard values:

Value	Meaning
011	Manual entry, terminal accepts PINs
051	Chip, terminal accepts PINs
071	Contactless M/Chip, terminal accepts PINs
801	Chip fallback to magnetic stripe, terminal accepts PINs
812	E-commerce, no PIN entry
911	Contactless magnetic stripe, terminal accepts PINs

The third digit is PIN entry capability (1 accepts PINs, 2 doesn’t, 8 PIN pad not working). 95x is a VISA-only code and is rejected for Mastercard. See Field 22 for every code the validator accepts.

Response Codes (Field 39)

Code	Description
00	Approved
01	Refer to Issuer
04	Pick Up Card
05	Do Not Honor
12	Invalid Transaction
14	Invalid Card Number
41	Lost Card
43	Stolen Card
51	Insufficient Funds
54	Expired Card
55	Incorrect PIN
57	Transaction Not Permitted
58	Transaction Not Permitted to Terminal
61	Exceeds Amount Limit
65	Exceeds Frequency Limit
75	PIN Tries Exceeded
91	Issuer System Error

Example: Mastercard Authorization Request

from iso8583sim.core.types import ISO8583Message, CardNetwork
from iso8583sim.core.builder import ISO8583Builder

message = ISO8583Message(
    mti="0100",
    network=CardNetwork.MASTERCARD,
    fields={
        0: "0100",
        2: "5500000000000004",      # Mastercard PAN
        3: "000000",                # Purchase
        4: "000000010000",          # $100.00
        7: "1225120000",            # Dec 25, 12:00:00
        11: "123456",               # STAN
        14: "2512",                 # Exp Dec 2025
        22: "051",                  # Chip, CVV reliable
        24: "100",                  # NII
        25: "00",                   # Normal transaction
        41: "TERM0001",
        42: "MERCHANT123456 ",
    }
)

builder = ISO8583Builder()
raw = builder.build(message)

Example: Mastercard EMV Authorization

from iso8583sim.demo import generate_emv_auth

# Use a Mastercard PAN
emv_message = generate_emv_auth(
    pan="5500000000000004",
    amount=25000,
    cryptogram="ABCDEF1234567890",
)

print(f"Network: {emv_message.network}")  # CardNetwork.MASTERCARD

MasterCard Payment Gateway (MPG)

Mastercard authorizations route through MasterCard Payment Gateway:

Authorization timeouts: 30 seconds standard
Reversal required for timeout scenarios
Advice messages for offline approvals

SecureCode / 3DS

For e-commerce transactions with 3D Secure:

# Field 48 contains authentication data
# Field 22 = 812 for authenticated e-commerce
message.fields[22] = "812"

Validation

Mastercard-specific validation:

from iso8583sim.core.validator import ISO8583Validator
from iso8583sim.core.types import CardNetwork

validator = ISO8583Validator()
message.network = CardNetwork.MASTERCARD

errors = validator.validate_message(message)
# Validates:
# - All Mastercard required fields present
# - PAN passes Luhn check
# - PAN prefix matches Mastercard ranges
# - Field formats match Mastercard specs

2-Series BINs

Mastercard 2-series BINs (2221-2720) are supported:

# Both are valid Mastercard PANs
"5500000000000004"  # Traditional
"2221000000000009"  # 2-series

Get started

Core

Card networks

Tools and interfaces

LLM features

Architecture

Operations

Network Detection

Required Fields

Mastercard-Specific Fields

Field 48 - Additional Data

Field 61 - POS Data Extended

DE127 - Private Data

POS Entry Modes (Field 22)

Response Codes (Field 39)

Example: Mastercard Authorization Request

Example: Mastercard EMV Authorization

MasterCard Payment Gateway (MPG)

SecureCode / 3DS

Validation

2-Series BINs

​Network Detection

​Required Fields

​Mastercard-Specific Fields

​Field 48 - Additional Data

​Field 61 - POS Data Extended

​DE127 - Private Data

​POS Entry Modes (Field 22)

​Response Codes (Field 39)

​Example: Mastercard Authorization Request

​Example: Mastercard EMV Authorization

​MasterCard Payment Gateway (MPG)

​SecureCode / 3DS

​Validation

​2-Series BINs

Network Detection

Required Fields

Mastercard-Specific Fields

Field 48 - Additional Data

Field 61 - POS Data Extended

DE127 - Private Data

POS Entry Modes (Field 22)

Response Codes (Field 39)

Example: Mastercard Authorization Request

Example: Mastercard EMV Authorization

MasterCard Payment Gateway (MPG)

SecureCode / 3DS

Validation

2-Series BINs