Welcome to the mPAY24 Developer portal.

mPAY24 makes it easy to accept payments in your website or app.
Get integrated quickly using our documentation or using a plugin for your shop system.

MDXI XML

MDXI XMLOverview
DescriptionMerchant Data Exchange Interface
Version3
Schema locationhttps://www.mpay24.com/schemas/MDXI/v3.0/MDXI.xsd

The MDXI XML describes the payment order and how the mPAY24 PayPage is constructed. It defines the shown shopping cart and the usable payment systems for the customer.

Information stated within the MDXI are passed to the financial institution, if possible. Therefore, it is recommended to provide all available information.

Customization and examples

The mPAY24 PayPage can be adjusted by setting attributes within the MDXI. Attributes defining styles have the surfix Style in their name.

Center mPAY24 PayPage

To center the mPAY24 PayPage in the browser’s display area set the Style attribute within the Order element to the following:

<?xml version="1.0" encoding="UTF-8"?>
<Order Style="margin-left: auto; margin-right: auto;">
  <Tid>826241</Tid>
  <Price>1.00</Price>
</Order>

Alternating item rows

To create alternating item rows the Style attribute has to be set for each sub element of each Item.

<?xml version="1.0" encoding="UTF-8"?>
<Order>
  <Tid>13548293</Tid>
  <ShoppingCart>
    <Item>
      <Description Style="background-color:lightgray">Desc A</Description>
      <Quantity Style="background-color:lightgray">1</Quantity>
      <ItemPrice Style="background-color:lightgray">7.50</ItemPrice>
      <Price Style="background-color:lightgray">7.50</Price>
    </Item>
    <Item>
      <Description Style="background-color:gray">Desc B</Description>
      <Quantity Style="background-color:gray">3</Quantity>
      <ItemPrice Style="background-color:gray">2.50</ItemPrice>
      <Price Style="background-color:gray">7.50</Price>
    </Item>
    <Item>
      <Description Style="background-color:lightgray">Desc C</Description>
      <Quantity Style="background-color:lightgray">4</Quantity>
      <ItemPrice Style="background-color:lightgray">4.25</ItemPrice>
      <Price Style="background-color:lightgray">17.00</Price>
    </Item>
    </ShoppingCart>
  <Price>32.00</Price>
</Order>

Preselecting payment type

To preselect a payment type/system, the element PaymentTypes should be used. It can either whitelist (set Enable="true") or blacklist (set Enable="false") payment types/systems.

📘

If predefining of payment systems is unnecessary, mPAY24 recommends to not use this element, in order to be able to use further activated payment systems immediately.

<?xml version="1.0" encoding="UTF-8"?>
<Order>
  <Tid>267351</Tid>
  <PaymentTypes Enable="true">
    <Payment Type="EPS"/>
  </PaymentTypes>
  <Price>1.00</Price>
</Order>

Stating tax amounts

Please be aware that mPAY24 does not calculate any net or gross amounts as they have to be provided within the ShoppingCart element. All amounts have to be stated absolutely and not percentaged.

mPAY24 does not notice the merchant if the sum of the shopping cart and the total sum are not equal. When the sums are different, the shopping cart will be discard and only the Price element is transmitted to the financial institution.

Net prices

If the shopping cart should contain only net prices, the elements ItemPrice have to be defined with net amounts. The attribute Tax should not be set.

The element Tax holds the absolute value of the incurred tax of the total amount.

Therefore, the total amount of the order (element Price of Order) is made up from each Price element within an Item and the Price element itself.

<?xml version="1.0" encoding="UTF-8"?>
<Order>
  <Tid>Order excl. Tax</Tid>
  <ShoppingCart>
    <Item>
      <Number>1</Number>
      <Quantity>1</Quantity>
      <ItemPrice>1.00</ItemPrice>
    </Item>
    <Item>
      <Number>2</Number>
      <Quantity>2</Quantity>
      <ItemPrice>2.00</ItemPrice>
    </Item>
    <ShippingCosts>3.00</ShippingCosts>
    <Tax>1.60</Tax>
  </ShoppingCart>
  <Price>9.60</Price>
</Order>

The total amount of the shopping cart in the Price element are calculated as followed:

Price = SUM(Quantity x ItemPrice) + SUM(Discount) + SUM(ShippingCost) + Tax

Gross prices

If the shopping cart should contain only gross prices, the element ItemPrice has to be defined with gross amounts. The attribute Tax has to be set to the absolute value of the incurred tax within the ItemPrice element.

The element Tax holds the absolute value of the incurred tax of the total amount.

The total amount of the order (element Price) is made up only from each Price element and optional from the Tax attribute of ShippingCosts, since these prices already include the tax. Additional the tax will be displayed with the abbr. incl. prefix on the mPAY24 PayPage, if no header was set (via the Header attribute).

<?xml version="1.0" encoding="UTF-8"?>
<Order>
  <Tid>Order incl. Tax</Tid>
  <ShoppingCart>
    <Item>
      <Number>1</Number>
      <Quantity>1</Quantity>
      <ItemPrice Tax="0.20">1.20</ItemPrice>
    </Item>
    <Item>
      <Number>2</Number>
      <Quantity>2</Quantity>
      <ItemPrice Tax="0.40">2.40</ItemPrice>
    </Item>
    <ShippingCosts Tax="0.60">3.60</ShippingCosts>
    <Tax>1.60</Tax>
  </ShoppingCart>
  <Price>9.60</Price>
</Order>

The total amount of the shopping cart in the Price element are calculated as followed:

Price = SUM(Quantity x ItemPrice) + SUM(Discount) + SUM(ShippingCost)

The total tax of the shopping cart in the Tax element are calculated as followed:

Tax = SUM(Quantity x Tax of ItemPrice) + SUM(Tax of ShippingCosts)`

Schema description

The encoding of the MDXI XML is either UTF-8 or ISO-8859-1.

Order

Order element description

The Order element is used for the SelectPayment operation to describe order details (such as order number, shopping cart, amount, ...) and/or customer details (name, address, ...).

ElementTypeRestrictionDescription
ClientIPstring[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3} maxLength: 15Customer client IP address
UserFieldstringLength: 0 - 255User variable (is communicated over the URLs)
TidstringLength: 1 - 32Unique transaction ID assigned by the merchant
TemplateSetTemplateSetWEBTemplate set definition
PaymentTypesPaymentTypes-Payment type restriction
PaymentProfilesPaymentProfiles-Payment profile restriction
ShoppingCartShoppingCart-Shopping cart of the order
Pricefloat2 decimal placesTotal amount of the order
CurrencystringLength: 3Currency of the order
CustomerstringLength: 0 - 50Customer name
BillingAddrAddressType-Customer billing address
ShippingAddrAddressType-Customer shipping address
URLURLType-URLs for redirection and notification

If ShippingAddr is not set, the same values as for BillingAddr are assumed for the shipping address.

Profile

The Profile element is used only by CreateProfile.

Profile element description

ElementTypeRestrictionDescription
ClientIPstringLength: 0 - 15Customer client IP address
TemplateSetenumerationWEBTemplate set definition
PaymentTypesPaymentTypes-Payment type restriction
CustomerIDstringLength: 1 - 32Customer ID assigned by the merchant
BillingAddrAddressType-Customer billing address
URLURLType-URLs for redirection and notification

Special types

TemplateSet

AttributeTypeRestrictionDescription
CSSNameenumerationDEFAULT, MOBILE, MODERNCSS template name
LanguageenumerationEN, DE, BG, FR, HU, NL, ES, IT, CS, HR, SK, SL, SR, RO, RU, PL, PT, TR, ZH, JA, DA, FI, SV, NO, UK, ELLanguage of the mPAY24 PayPage

PaymentTypes

The element PaymentTypes could be used if payment systems are to be excluded for selection by the customer. For example due to currency restrictions, payment type preselections, disabling or enabling payment methods on a per billing address country basis, ...

PaymentType element description

AttributeTypeRestrictionDescription
Enableenumerationtrue, falseEnables or disables the specified payment types

If only payment systems not available to the merchant are enabled or all payment systems available to the merchant are disabled, the mPAY24 PayPage shows an error message upon opening.

📘

If predefining of payment systems is unnecessary, mPAY24 recommends to not use this element, in order to use future activated payment systems immediately.

ElementsTypeRestrictionDescription
PaymentPayment-Specifies a payment type with brand

Payment

AttributeTypeRestrictionDescription
TypeenumerationCC, MAESTRO, EPS, PB, PSC, ELV, QUICK, GIROPAY, PAYPAL, MPASS, BILLPAY, INVOICE, HP, KLARNA, SOFORTPayment type abbreviation (if only Type is given, all brands of this type are affected)
BrandenumerationAMEX, DINERS, MASTERCARD, VISA, JCB, ATOS, HOBEX-AT, HOBEX-DE, HOBEX-NL, INVOICE, HPBrand abbreviation (Only for type CC, ELV, BILLPAY and KLARNA)
SubBrandintegerLength: 0 - 3Sub brand abbreviation/id (currently only used for Type = EPS as bank id)

PaymentProfiles

The element PaymentProfiles can be used in combination with the interactive profiles to include or exclude payment profiles of the customer for a transaction. Also it can be used to define the order in which profiles are displayed to the customer.

PaymentProfiles element description

AttributeTypeRestrictionDescription
Enableenumerationtrue, falseEnables or disables the payment profile
ElementsTypeRestrictionDescription
ProfileIDstringLength: 1 - 12Enable or disable specified customer payment profiles

ShoppingCart

ShoppingCart element description

AttributeTypeRestrictionDescription
HeaderstringLength: 0 - 255Sets the header text
HeaderStylestringLength: 0 - 255Sets the header style
StylestringLength: 0 - 255Sets the element style
CaptionStylestringLength: 0 - 255Sets the caption style
NumberHeaderstringLength: 0 - 255Sets the Number header text
NumberStylestringLength: 0 - 255Sets the Number header style
ProductNrHeaderstringLength: 0 - 255Sets the ProductNr header text
ProductNrStylestringLength: 0 - 255Sets the ProductNr header style
DescriptionHeaderstringLength: 0 - 255Sets the Description header text
DescriptionStylestringLength: 0 - 255Sets the Description header style
PackageHeaderstringLength: 0 - 255Sets the Package header text
PackageStylestringLength: 0 - 255Sets the Package header style
QuantityHeaderstringLength: 0 - 255Sets the Quantity header text
QuantityStylestringLength: 0 - 255Sets the Quantity header style
ItemPriceHeaderstringLength: 0 - 255Sets the ItemPrice header text
ItemPriceStylestringLength: 0 - 255Sets the ItemPrice header style
PriceHeaderstringLength: 0 - 255Sets the Price header text
PriceStylestringLength: 0 - 255Sets the Price header style

📘

If attributes are used to define an alternative text, this text is fixed and is not affected by any language setting.

ElementTypeRestrictionDescription
DescriptionstringLength: 0 - 255Order description (shown above the shopping cart)
ItemItem-Items of the shopping cart
SubTotalfloat2 decimal placesSub total for displaying
Discountfloat2 decimal placesDiscount of total amount as negative number
ShippingCostsfloat2 decimal placesShipping costs
Taxfloat2 decimal placesTotal tax of the order

The elements Discount and ShippingCosts can occur multiple times with or without tax.

Item

ElementTypeRestrictionDescription
NumberstringLength: 0 - 255Number of shopping cart row
ProductNrstringLength: 0 - 255Product number of the item
DescriptionstringLength: 0 - 255Item description resp. title
PackagestringLength: 0 - 255Scale size of the item
QuantitystringLength: 0 - 255Quantity of the item ordered
ItemPricestringLength: 0 - 255Amount of a single unit
PricestringLength: 0 - 255Total amount of all units

The total in Price is automatically calculated (by multiply Quantity with ItemPrice) if Quantity and ItemPrice is provided. Quantity is assumed to be 1 if not provided. If Price and Quantity is given as well as Quantity is other than 1, the Price element is discarded.

📘

It is recommended to provide the Price only to represent potential intended rounding ups.

The elements Number, ProductNr, Description, Package, Quantity, ItemPrice and Price have the following attribute:

AttributeTypeRestrictionDescription
StylestringLength: 0 - 255Sets a value style

SubTotal, Discount

AttributeTypeRestrictionDescription
HeaderstringLength: 0 - 255Sets a fixed label text
HeaderStylestringLength: 0 - 255Sets a label style
StylestringLength: 0 - 255Sets a value style

ShippingCosts

AttributeTypeRestrictionDescription
HeaderstringLength: 0 - 255Sets a fixed label text
HeaderStylestringLength: 0 - 255Sets a label style
StylestringLength: 0 - 255Sets a value style
Taxfloat2 decimal placesTotal amount of incurrent tax

Tax

AttributeTypeRestrictionDescription
HeaderstringLength: 0 - 255Sets a fixed label text
HeaderStylestringLength: 0 - 255Sets a label style
StylestringLength: 0 - 255Sets a value style
PercentstringLength: 1 - 6Sets the Tax header to <Percent>% Ust. or inkl. <Percent>% Ust. (if Header and HeaderStyle is not set)

Currency

AttributeTypeRestrictionDescription
DisplaystringLength: 0 - 50Alt. value for currency code

Customer

AttributeTypeRestrictionDescription
IdstringLength: 1 - 32Customer ID assigned by the merchant
UseProfilebooleantrue, falseEnables or disables profile usage/storage

AddressType

The AddressType type is for all customer address definitions.

The AddressType requires at least the Name. If either Street, Zip, City or Country is specified, the other elements (Street, Zip, City, Country) are also mandatory to specify. The elements Street2, State, Email and Phone are always optional.

Please note, the element Email is not shown on the mPAY24 PayPage.

AddressType element description

AttributeTypeRestrictionDescription
GenderenumerationF, MCustomer gender
BirthdaydateFormat: YYYY-MM-DDCustomer birthday
ElementTypeRestrictionDescription
NamestringLength: 1 - 50Customer name
FirstNamestring-Deprecated, use Name instead
LastNamestring-Deprecated, use Name instead
StreetstringLength: 0 - 50First street line
Street2stringLength: 0 - 50Second street line
ZipstringLength: 0 - 50Zip code
CitystringLength: 0 - 50City name
StatestringLength: 0 - 40State name
CountrystringLength: 0 - 50Country name
EmailstringLength: 1 - 64Customer e-mail address
PhonestringLength: 1 - 20Customer phone number

Country

AttributeTypeRestrictionDescription
CodestringLength: 2Two digit ISO county code

URLType

ElementTypeRestrictionDescription
SuccessanyURILength: 5 - 2040URL for customer redirection incase of success
ErroranyURILength: 5 - 2040URL for customer redirection incase of error
ConfirmationanyURILength: 5 - 2040URL for receiving push notificationsabout the transaction state
CancelanyURILength: 5 - 2040URL for customer redirection incase of abortion

All URL values need to start with http:// or https://.

Updated about a year ago

MDXI XML


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.