Mastercard · Schema

Mastercard Payment

A payment transaction processed through the Mastercard network, representing a transfer of funds between a payer and payee. Applicable across Mastercard Send, Account to Account Commerce, Bill Pay, and checkout solutions.

Credit CardsDigital IdentityFinancial ServicesFraud DetectionOpen BankingPaymentsFortune 500

Properties

Name	Type	Description
paymentId	string	Unique identifier for the payment, generated using UUID logic to unambiguously link request and response messages.
paymentType	string	Classification of the payment indicating its purpose and processing path.
amount	string	Payment amount without decimal separators. The number of implied decimal places depends on the currency. For example, 10350 in USD represents $103.50.
currency	string	ISO 4217 numeric currency code for the payment amount.
status	string	Current status of the payment in its lifecycle.
timestamp	string	Timestamp of the payment initiation in ISO 8601 format with timezone offset.
sender	object	The party initiating or funding the payment.
recipient	object	The party receiving the payment funds.
cardNumber	string	Primary Account Number (PAN) of the card used for the payment. Must pass Luhn algorithm validation.
tokenNumber	string	Payment token representing the card number for tokenized transactions (MDES).
merchantId	string	Card acceptor or merchant unique identification number assigned by the acquirer.
merchantName	string	Name of the card acceptor or merchant.
merchantCategoryCode	string	Four-digit ISO 18245 Merchant Category Code (MCC) classifying the type of business.
acquirerId	string	Interbank Card Association (ICA) number of the acquiring institution.
icaNumber	string	ICA number of the issuer or acquirer initiating the request.
authorizationCode	string	Authorization code returned by the issuer for an approved transaction.
billingAmount	string	Amount appearing on the cardholder statement in the billing currency, without decimals.
billingCurrency	string	ISO 4217 numeric currency code for the billing amount.
conversionRate	string	Currency conversion rate applied when the transaction and billing currencies differ.
network	string	Payment network through which the transaction was processed.
channel	string	The channel through which the payment was initiated.
posEntryMode	string	Point of service entry mode indicating how the card data was captured at the terminal.
terminalId	string	Unique code identifying a terminal at the card acceptor location.
settlementDate	string	Date on which the transaction settles, in YYYYMMDD format.
referenceId	string	External reference identifier provided by the originator for reconciliation.
memo	string	Brief description or comment provided by the originator supporting the payment.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "https://github.com/api-evangelist/mastercard/blob/main/json-schema/payment.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Mastercard Payment",
  "description": "A payment transaction processed through the Mastercard network, representing a transfer of funds between a payer and payee. Applicable across Mastercard Send, Account to Account Commerce, Bill Pay, and checkout solutions.",
  "type": "object",
  "required": [
    "paymentId",
    "paymentType",
    "amount",
    "currency",
    "status"
  ],
  "properties": {
    "paymentId": {
      "type": "string",
      "description": "Unique identifier for the payment, generated using UUID logic to unambiguously link request and response messages.",
      "format": "uuid",
      "examples": ["ecb2d942-eabd-42b6-87fd-69c19692bdc6"]
    },
    "paymentType": {
      "type": "string",
      "description": "Classification of the payment indicating its purpose and processing path.",
      "enum": [
        "P2P",
        "P2M",
        "B2B",
        "DISBURSEMENT",
        "FUNDING",
        "BILL_PAYMENT",
        "ACCOUNT_TO_ACCOUNT",
        "CARD_ON_FILE",
        "RECURRING",
        "REFUND"
      ]
    },
    "amount": {
      "type": "string",
      "description": "Payment amount without decimal separators. The number of implied decimal places depends on the currency. For example, 10350 in USD represents $103.50.",
      "pattern": "^[0-9]+$",
      "minLength": 1,
      "maxLength": 12,
      "examples": ["10350"]
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 numeric currency code for the payment amount.",
      "pattern": "^[0-9]{3}$",
      "minLength": 3,
      "maxLength": 3,
      "examples": ["840"]
    },
    "status": {
      "type": "string",
      "description": "Current status of the payment in its lifecycle.",
      "enum": [
        "PENDING",
        "AUTHORIZED",
        "CAPTURED",
        "SETTLED",
        "DECLINED",
        "CANCELLED",
        "REFUNDED",
        "FAILED"
      ]
    },
    "timestamp": {
      "type": "string",
      "description": "Timestamp of the payment initiation in ISO 8601 format with timezone offset.",
      "format": "date-time",
      "examples": ["2024-02-02T02:34:37-06:00"]
    },
    "sender": {
      "$ref": "#/$defs/PaymentParty",
      "description": "The party initiating or funding the payment."
    },
    "recipient": {
      "$ref": "#/$defs/PaymentParty",
      "description": "The party receiving the payment funds."
    },
    "cardNumber": {
      "type": "string",
      "description": "Primary Account Number (PAN) of the card used for the payment. Must pass Luhn algorithm validation.",
      "pattern": "^[0-9]{12,19}$",
      "minLength": 12,
      "maxLength": 19
    },
    "tokenNumber": {
      "type": "string",
      "description": "Payment token representing the card number for tokenized transactions (MDES).",
      "pattern": "^[0-9]{12,19}$",
      "minLength": 12,
      "maxLength": 19
    },
    "merchantId": {
      "type": "string",
      "description": "Card acceptor or merchant unique identification number assigned by the acquirer.",
      "maxLength": 15,
      "examples": ["A42E51982100100"]
    },
    "merchantName": {
      "type": "string",
      "description": "Name of the card acceptor or merchant.",
      "maxLength": 22,
      "examples": ["ACME STORE"]
    },
    "merchantCategoryCode": {
      "type": "string",
      "description": "Four-digit ISO 18245 Merchant Category Code (MCC) classifying the type of business.",
      "pattern": "^[0-9]{4}$",
      "minLength": 4,
      "maxLength": 4,
      "examples": ["5411"]
    },
    "acquirerId": {
      "type": "string",
      "description": "Interbank Card Association (ICA) number of the acquiring institution.",
      "minLength": 3,
      "maxLength": 7,
      "examples": ["5450"]
    },
    "icaNumber": {
      "type": "string",
      "description": "ICA number of the issuer or acquirer initiating the request.",
      "minLength": 3,
      "maxLength": 7,
      "examples": ["1076"]
    },
    "authorizationCode": {
      "type": "string",
      "description": "Authorization code returned by the issuer for an approved transaction.",
      "maxLength": 6
    },
    "billingAmount": {
      "type": "string",
      "description": "Amount appearing on the cardholder statement in the billing currency, without decimals.",
      "pattern": "^[0-9]+$",
      "minLength": 1,
      "maxLength": 12,
      "examples": ["10350"]
    },
    "billingCurrency": {
      "type": "string",
      "description": "ISO 4217 numeric currency code for the billing amount.",
      "pattern": "^[0-9]{3}$",
      "minLength": 3,
      "maxLength": 3,
      "examples": ["840"]
    },
    "conversionRate": {
      "type": "string",
      "description": "Currency conversion rate applied when the transaction and billing currencies differ."
    },
    "network": {
      "type": "string",
      "description": "Payment network through which the transaction was processed.",
      "enum": [
        "MASTERCARD",
        "MAESTRO",
        "CIRRUS"
      ],
      "default": "MASTERCARD"
    },
    "channel": {
      "type": "string",
      "description": "The channel through which the payment was initiated.",
      "enum": [
        "POS",
        "ECOMMERCE",
        "MOBILE",
        "ATM",
        "MOTO",
        "RECURRING",
        "IN_APP"
      ]
    },
    "posEntryMode": {
      "type": "string",
      "description": "Point of service entry mode indicating how the card data was captured at the terminal.",
      "maxLength": 3,
      "examples": ["051"]
    },
    "terminalId": {
      "type": "string",
      "description": "Unique code identifying a terminal at the card acceptor location.",
      "maxLength": 8,
      "examples": ["5055D305"]
    },
    "settlementDate": {
      "type": "string",
      "description": "Date on which the transaction settles, in YYYYMMDD format.",
      "pattern": "^[0-9]{8}$",
      "examples": ["20240116"]
    },
    "referenceId": {
      "type": "string",
      "description": "External reference identifier provided by the originator for reconciliation.",
      "maxLength": 36
    },
    "memo": {
      "type": "string",
      "description": "Brief description or comment provided by the originator supporting the payment.",
      "maxLength": 1000
    }
  },
  "$defs": {
    "PaymentParty": {
      "type": "object",
      "description": "A party involved in a payment transaction, either as sender or recipient.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Full name of the payment party.",
          "maxLength": 100
        },
        "accountNumber": {
          "type": "string",
          "description": "Account number of the payment party.",
          "maxLength": 19
        },
        "institutionId": {
          "type": "string",
          "description": "Identifier for the financial institution of the payment party.",
          "maxLength": 11
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "Address": {
      "type": "object",
      "description": "A postal address.",
      "properties": {
        "line1": {
          "type": "string",
          "description": "First line of the street address.",
          "maxLength": 50
        },
        "line2": {
          "type": "string",
          "description": "Second line of the street address.",
          "maxLength": 50
        },
        "city": {
          "type": "string",
          "description": "City name.",
          "maxLength": 50
        },
        "stateProvinceCode": {
          "type": "string",
          "description": "State or province code.",
          "maxLength": 3
        },
        "postalCode": {
          "type": "string",
          "description": "Postal or ZIP code.",
          "maxLength": 10
        },
        "countryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-3 country code.",
          "pattern": "^[A-Z]{3}$",
          "minLength": 3,
          "maxLength": 3
        }
      }
    }
  }
}