XooCode(){

PaymentChargeSpecification

PaymentChargeSpecification is a PriceSpecification subtype for charges that depend on how the customer pays: credit-card surcharges, bank-transfer fees, cash-handling fees, buy-now-pay-later fees.

It adds one direct property: appliesToPaymentMethod, whose value is a PaymentMethod enumeration (ByBankTransferInAdvance, ByInvoice, Cash, CheckInAdvance, COD, DirectDebit, PaymentMethodCreditCard, PayPal).

It also inherits the full PriceSpecification property set: price, priceCurrency, eligibleTransactionVolume, and valueAddedTaxIncluded. The most common real-world pattern is "2.9% surcharge for credit-card transactions over $0, waived for bank transfer," which means two PaymentChargeSpecification blocks on the Offer.

Full example of schema.org/PaymentChargeSpecification json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/PaymentChargeSpecification
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Offer",
  "itemOffered": { "@type": "Service", "name": "XooStructured Enterprise annual license" },
  "price": 12000.00,
  "priceCurrency": "USD",
  "priceSpecification": [
    {
      "@type": "PaymentChargeSpecification",
      "price": 348.00,
      "priceCurrency": "USD",
      "appliesToPaymentMethod": "https://schema.org/PaymentMethodCreditCard",
      "description": "2.9% surcharge applied to credit-card payments."
    },
    {
      "@type": "PaymentChargeSpecification",
      "price": 0.00,
      "priceCurrency": "USD",
      "appliesToPaymentMethod": "https://schema.org/ByBankTransferInAdvance",
      "description": "No surcharge for bank transfer."
    }
  ]
}
</script>

Regulation note

Payment surcharges are regulated in the EU (Payment Services Directive bans most consumer surcharges) and in several US states; publish PaymentChargeSpecification only where your surcharges are legal, and reflect those rules in eligibleRegion on the surrounding Offer.

Minimal valid version

The smallest markup that still produces a valid PaymentChargeSpecification entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/PaymentChargeSpecification (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "PaymentChargeSpecification",
  "price": 348.00,
  "priceCurrency": "USD",
  "appliesToPaymentMethod": "https://schema.org/PaymentMethodCreditCard"
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

  • No dedicated rich result (used by checkout and invoice consumers)
    Google docs

Common PaymentChargeSpecification mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    Percentage surcharge as raw percent

    Wrong
    "price": "2.9%"
    Right
    Calculate the surcharge amount against the Offer price and publish the resolved figure in the Offer's currency

    price expects a Number in priceCurrency; percentage text cannot be aggregated by consumers into a final total.

  2. 02

    appliesToPaymentMethod as free text

    Wrong
    "appliesToPaymentMethod": "credit card"
    Right
    The enumeration URL https://schema.org/PaymentMethodCreditCard

    Free text bypasses the PaymentMethod enumeration and prevents any downstream matching on card-vs-bank rules.

  3. 03

    Publishing surcharges in jurisdictions where they are illegal

    Wrong
    PaymentChargeSpecification visible to EU customers where consumer card surcharges are banned
    Right
    Use eligibleRegion / ineligibleRegion on the Offer to scope the rule

    Regulators treat structured-data surcharges as public disclosure; scope them to compliant regions only.

Schema properties in this example

PaymentChargeSpecificationPriceSpecificationStructuredValueOfferitemOfferedServicepricepriceCurrencypriceSpecificationappliesToPaymentMethodPaymentMethodCreditCardByBankTransferInAdvancePaymentMethoddescription

About the example data

Xoo Code's invoicing portal charges a 2.9% credit-card surcharge on enterprise invoices paid by card, waived for bank transfers.

Comments

Loading comments...

Leave a comment