Redirect Integration

With the Redirect Integration the merchant provides the payment description (e.g. amount, customer name, shopping cart, ...) to the mPAY24 system. The system generates the mPAY24 PayPage with input forms for the customer's payment credentials and returns its URL to the merchant. The customer is redirected to the secure mPAY24 PayPage by the merchant. Afterwards the merchant is informed about the result of the transaction (e.g. success). The merchant does not have to deal with payment system specifics and offers the customer a consistent user experience with various payment systems.

The Redirect Integration uses the SelectPayment operation and the final transaction result is depending on a customer's input and behaviour. It is possible, that the customer initiates several transactions (with the same payment description). In this case either all made transactions are unsuccessful or only the last one is successful (the mPAY24 PayPage sessions terminates after a successful transaction).

❗️

The display of the payment page in frames is not permitted.

Integration steps

  • The customer requests a payment (e.g. by pressing a Checkout button)
  • The merchant sends a SelectPayment call including details (within the MDXI XML) to mPAY24.
  • mPAY24 responds with a SelectPaymentResponse including a returnCode = REDIRECT and a location value (if status = OK).
<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:etp="https://www.mpay24.com/soap/etp/1.5/ETP.wsdl">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <etp:SelectPayment>
      <merchantID>90000</merchantID>
      <mdxi>
        <Order>
          <Tid>9275</Tid>
          <ShoppingCart>
            <Description>Example order</Description>
            <Item>
              <Description>Example product</Description>
              <Price>10.00</Price>
            </Item>
          </ShoppingCart>
          <Price>10.00</Price>
          <URL>
            <Success>http://www.hotelmuster.at/succ.php</Success>
            <Error>http://www.hotelmuster.at/err.php</Error>
            <Confirmation>http://www.hotelmuster.at/conf.php</Confirmation>
          </URL>
        </Order>
      </mdxi>
    </etp:SelectPayment>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:etp="https://www.mpay24.com/soap/etp/1.5/ETP.wsdl">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <etp:SelectPaymentResponse>
      <status>OK</status>
      <returnCode>REDIRECT</returnCode>
      <location>https://test.mpay24.com/app/bin/checkout/payment/f76d87325[...]</location>
    </etp:SelectPaymentResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
mpay.selectPayment({
  tid: '9275',
  shoppingCart: {
    item: [{
      number: 1,
      quantity: 1,
      itemPrice: '1.00',
    }],
  },
  price: 100,
}).then(result => {
  result.location // redirect customer to this url
});
  • The customer is redirected to the mPAY24 location URL by the merchant (e.g. by supplying the location as a link or just forwarding the browser to the URL).
  • The customer follows the payment process specified by mPAY24.
  • mPAY24 communicates the payment result via the push method using the confirmationURL (see chapter Payment notification for more information).
http://www.hotelmuster.com/confirmation.php?OPERATION=CONFIRMATION&TID=9275&
  STATUS=RESERVED&PRICE=1000&CURRENCY=EUR&P_TYPE=CC&BRAND=VISA&MPAYTID=1682984&
  USER_FIELD=&ORDERDESC=Example+order&CUSTOMER=9275&CUSTOMER_EMAIL=&LANGUAGE=DE&
  CUSTOMER_ID=&PROFILE_STATUS=IGNORED&FILTER_STATUS=OK&APPR_CODE=%2Dtest%2D
  • The merchant confirms the receipt of the transaction notification with either OK or ERROR (status depends if the confirmation could successfully update the merchant's system).

📘

In PHP this could be achieved by echo 'OK'

  • mPAY24 forwards the customer to the successURL or errorURL specified by the merchant dynamically within the MDXI XML or static over the merchant portal.
  • The customer requests the successURL or errorURL.
  • (optional) If the payment notification upon the confirmationURL has not been received yet, the merchant should initiate a TransactionStatus call using the tid to determine the transaction status (see chapter Payment notification for more information).

🚧

Never rely on the parameters provided by the successURL or errorURL alone, since they can be manipulated!

<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:etp="https://www.mpay24.com/soap/etp/1.5/ETP.wsdl">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <etp:TransactionStatus>
      <merchantID>90000</merchantID>
      <tid>9275</tid>
    </etp:TransactionStatus>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
mpay24.transactionStatus({
  tid: '9275'
}).then(result => {
  console.log(result);
}).catch(err => {
  console.error(err);
});
  • The merchant informs the customer about the transaction by returning/showing him the successURL or errorURL.

Supported languages

The mPAY24 PayPage supports currently the following languages:

BG, CS, DA, DE, EN, EL, FI, ES, FR, HR, HU, IT, JA, NL, NO, PL, PT, RO, RU, SK, SL, SR, SV, TR, UK, ZH

The fallback for not supported languages is English.

mPAY24 PayPage session and idle timeouts

The mPAY24 PayPage is configured for a total session timeout of 30 minutes. The session idle timeout is set to 15 minutes. If one of these timeouts is exceeded, the session is terminated and the payment should be restarted.

Notifications for successful payments could occur even if the session is expired. In such case the customer is returned to the successURL.

Basic requirements

These chapter explains the basic requirements to process payments with any payment system using the Redirect Integration. Some payment systems may demand additional requirements which are listed further.

The SelectPayment defines the mdxi element which holds all payment relevant information. The minimum information provided in the MDXI XML are the transaction id (of the merchant system; e.g. a order number) as Tid and the amount of the order as Price. Additional the URLs should be definied within the request, if the URLs are not configured via the Merchant Interface called MIF.

<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV ="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:etp ="https://www.mpay24.com/soap/etp/1.5/ETP.wsdl">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <etp:SelectPayment>
      <merchantID>90000</merchantID>
      <mdxi>
        <Order>
          <Tid>90021</Tid>
          <Price>10.00</Price>
          <URL>
            <Success>http://www.hotelmuster.at/succ.php</Success>
            <Error>http://www.hotelmuster.at/err.php</Error>
            <Confirmation>http://www.hotelmuster.at/conf.php</Confirmation>
          </URL>
        </Order>
      </mdxi>
    </etp:SelectPayment>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<Order>
  <Tid>90021</Tid>
  <Price>10.00</Price>
  <URL>
    <Success>http://www.hotelmuster.at/succ.php</Success>
    <Error>http://www.hotelmuster.at/err.php</Error>
    <Confirmation>http://www.hotelmuster.at/conf.php</Confirmation>
  </URL>
</Order>

🚧

mPAY24 recommends to always state all available information when submitting a request.

Extended requirements

Note: The basic requirements must be implemented.

The following payment systems are covered in this section: ELV, KLARNA, PAYPAL, PAYOLUTION

As additional requirements the following elements need to be stated within the MDXI XML. For detailed information about the MDXI XML or specific elements see chapter MDXI XML.

  • The ClientIP provides the IP address of the customer.
<ClientIP>208.67.222.222</ClientIP>
  • The ShoppingCart should be provided as detailed as possible and item prices should be stated as gross prices with an tax amount.
<ShoppingCart>
  <Description>Example shopping cart</Description>
  <Item>
    <ProductNr>001</ProductNr>
    <Description>Test product A</Description>
    <Quantity>2</Quantity>
    <ItemPrice Tax="1.00">6.00</ItemPrice>
  </Item>
  <Item>
    <ProductNr>002</ProductNr>
    <Description>Test product B</Description>
    <Quantity>1</Quantity>
    <ItemPrice Tax="1.80">10.80</ItemPrice>
  </Item>
  <SubTotal>22.50</SubTotal>
  <Discount>-5.00</Discount>
  <ShippingCosts Tax="1.25">7.50</ShippingCosts>
  <Tax>5.05</Tax>
</ShoppingCart>

The shopping cart total must also be equal the price stated in the element Price outside the ShoppingCart. If not, the complete shopping cart is discarded. See the MDXI XML chapter for detailed information about stating amounts and calculating the total amount.

<Price>25.30</Price>
  • The BillingAddr should be provided as detailed as possible with the elements Name, Street, Zip, City, Country, Email, Phone and State. State is to specifiy if the address is of Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. If Mode=ReadWrite is set and the required elements are set empty, the data can be entered by the customer on the mPAY24 PayPage.
<BillingAddr Mode="ReadOnly">
  <Name Gender="M" Birthday="1990-01-31">John Doe</Name>
  <Street>Main street 1</Street>
  <Zip>1010</Zip>
  <City>Vienna</City>
  <Country Code="AT"/>
  <Email>[email protected]</Email>
  <Phone>+4368012345678</Phone>
</BillingAddr>
  • The ShippingAddr only needs to be provided if it differs from the BillingAddr.

🚧

Payments could be rejected by the acquirer if invalid data is provided or neccessary data is missing.

Full example

<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV ="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:etp ="https://www.mpay24.com/soap/etp/1.5/ETP.wsdl">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <etp:SelectPayment>
      <merchantID>90000</merchantID>
      <mdxi>
        <Order>
          <ClientIP>208.67.222.222</ClientIP>
          <Tid>90021</Tid>
          <ShoppingCart>
            <Description>Example shopping cart</Description>
            <Item>
              <ProductNr>001</ProductNr>
              <Description>Test product A</Description>
              <Quantity>2</Quantity>
              <ItemPrice Tax="1.00">6.00</ItemPrice>
            </Item>
            <Item>
              <ProductNr>002</ProductNr>
              <Description>Test product B</Description>
              <Quantity>1</Quantity>
              <ItemPrice Tax="1.80">10.80</ItemPrice>
            </Item>
            <SubTotal>22.80</SubTotal>
            <Discount>-5.00</Discount>
            <ShippingCosts Tax="1.25">7.50</ShippingCosts>
            <Tax>5.05</Tax>
          </ShoppingCart>
          <Price>25.30</Price>
          <BillingAddr Mode="ReadOnly">
            <Name Gender="M" Birthday="1990-01-31">John Doe</Name>
            <Street>Main street 1</Street>
            <Zip>1010</Zip>
            <City>Vienna</City>
            <Country Code="AT"/>
            <Email>[email protected]</Email>
            <Phone>+4368012345678</Phone>
          </BillingAddr>
          <URL>
            <Success>http://www.hotelmuster.at/succ.php</Success>
            <Error>http://www.hotelmuster.at/err.php</Error>
            <Confirmation>http://www.hotelmuster.at/conf.php</Confirmation>
          </URL>
        </Order>
      </mdxi>
    </etp:SelectPayment>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
mpay24.selectPayment({
  clientIP: '208.67.222.222',
  tid: '90021',
  shoppingCart: {
    description: 'Example shopping cart',
    item: [{
      ProductNr: '001',
      description: 'Test product A',
      quantity: 2,
      itemPrice: {
        '@': {
          tax: '1.00',
        },
        '#': '6.00',
      },
    }],
    subTotal: '22.80',
    discount: '-5.00',
    shippingCosts: '7.50',
    tax: '5.05',
  },
  price: '6.00',
  billingAddr: {
    '@': {
      mode: 'ReadOnly',
    },
    name: {
      '@': {
        gender: 'M',
        birthday: '1990-01-31',
      },
      '#': 'John Doe',
    },
    street: 'Main street 1',
    zip: '1010',
    city: 'Vienna',
    country: {
      '@': {
        code: 'AT',
      },
    },
    email: '[email protected]',
    phone: '+4368012345678',
  },
  URL: {
    success: 'http://www.hotelmuster.at/succ.php',
    error: 'http://www.hotelmuster.at/err.php',
    confirmation: 'http://www.hotelmuster.at/conf.php',
  },
}).then(data => {
  console.log(data);
}).catch(err => {
  console.error(err);
});