Guides
Platform StatusSupportContact us

Clearing

capture a reservation

Transactions in state RESERVED have to be billed in an additional step: the clearing. It is possible to clear an amount smaller than the original authorized amount. It is only possible to clear a transaction once.

🚧

Not all payment systems support this operation, please see chapter Payment systems for more details about specific payment systems.

📘

In the merchant portal the clearing option can be changed to automatically clear transactions. If set, the transactions are cleared after the authorization automatically. It is always the full authorized amount cleared.

📘

The merchant can clear transactions over the merchant interface or using the ManualClear operation. The transaction status change can be received via the push method (see Payment notification).
More information about clearing via the merchant portal can be found in the Merchant interface manual.

List not cleared transactions

Transactions, which are not cleared yet (currently residing in the status RESERVED), can be listed with the ListNotCleared call. The result can be restricted and sorted by the merchant upon request.

Operation: ListNotCleared

📘

Maximal 500 transactions can be listed at once.

For example the transactions can be sorted by the field MPAYTID descending.

<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:ListNotCleared>
      <merchantID>90000</merchantID>
      <sortField>MPAYTID</sortField>
      <sortType>DESC</sortField>
    </etp:ListNotCleared>
  </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:ListNotClearedResponse>
      <status>OK</status>
      <returnCode>OK</returnCode>
      <transactionDetails xsi:type="etp:TransactionDetails">
        <mpayTID>1679838</mpayTID>
        <tStatus>RESERVED</tStatus>
        <tid>e73104</tid>
        <orderDescription>90000*3149*EUR</orderDescription>
        <pType>CC</pType>
        <brand>MASTERCARD_3DS</brand>
        <amount>3149</amount>
        <currency>EUR</currency>
        <bifStatus>-test-</bifStatus>
      </transactionDetails>
      <transactionDetails xsi:type="etp:TransactionDetails">
        <mpayTID>1679832</mpayTID>
        <tStatus>RESERVED</tStatus>
        <tid>966003</tid>
        <orderDescription>90000*1439*EUR</orderDescription>
        <pType>CC</pType>
        <brand>VISA</brand>
        <amount>1439</amount>
        <currency>EUR</currency>
        <bifStatus>-test-</bifStatus>
      </transactionDetails>
      <all>2</all>
    </etp:ListNotClearedResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As result a list with all uncleared transactions and their details is returned in descending order.

To clear a transaction the merchant needs to know the mpayTID of the transaction and if the transaction state is RESERVED. Both can be received by the ListNotCleared operation.

Clear one transaction

Transactions can be cleared with the ManualClear operation. It is possible to clear more than one transaction at the same time and also to clear less than the authorized amount. All transactions should be in state RESERVED. Use the ListNotCleared call to determine such transactions.

Operation: ManualClear

📘

Only equal or less than the authorized amount can be cleared.

A transaction can be cleared by providing the mpayTID within a clearingDetail element. If no additional amount element is given, the full amount of the transaction is cleared.

<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:ManualClear>
      <merchantID>90000</merchantID>
      <clearingDetails>
        <mpayTID>1679838</mpayTID>
      </clearingDetails>
    </etp:ManualClear>
  </soapenv:Body>
</soapenv: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:ManualClearResponse>
      <status>OK</status>
      <returnCode>OK</returnCode>
      <transaction>
        <mpayTID>1679838</mpayTID>
        <tStatus>BILLED</tStatus>
        <tid>e73104</tid>
      </transaction>
    </etp:ManualClearResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As response the cleared transaction is listed with its current state.

📘

Additional to the status and returnCode, the result of the Confirmation Interface should be checked to determine if the operation was successful.

Clear several transactions

To clear more than one transaction within the same request, additional clearingDetail elements with mpayTID should be provided.

Operation: ManualClear

In the following example two transactions are cleared with an amount less than the authorization amount.

📘

The amount element is provided as cent amount.

<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:ManualClear>
      <merchantID>90000</merchantID>
      <clearingDetails>
        <mpayTID>1679832</mpayTID>
        <amount>1000</amount>
      </clearingDetails>
      <clearingDetails>
        <mpayTID>1679726</mpayTID>
        <amount>1540</amount>
      </clearingDetails>
    </etp:ManualClear>
  </soapenv:Body>
</soapenv: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:ManualClearResponse>
      <status>OK</status>
      <returnCode>OK</returnCode>
      <transaction>
        <mpayTID>1679832</mpayTID>
        <tStatus>BILLED</tStatus>
        <tid>966003</tid>
      </transaction>
      <transaction>
        <mpayTID>1679726</mpayTID>
        <tStatus>BILLED</tStatus>
        <tid>15</tid>
      </transaction>
    </etp:ManualClearResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As response each cleared transaction is listed with its current state.

📘

Additional to the status and returnCode, the result of the Confirmation Interface should be checked to determine if the operation was successful.

Multiple clearings of a reserved amount

🚧

Not all payment systems support this operation, please see chapter Payment systems for more details about specific payment systems.

The multiple clearing features enables the merchant to clear transactions more than once. To clear a transaction multiple times, the partly clearings must not exceed the transaction reserved amount.

If the merchant initiates a partly clearing, the requested amount of the transaction is cleared and the remaining amount is reserved again. This process is done automatically and the merchant does not have to initiate it.

📘

Also, the merchant can multiple clear transactions manually over the merchant portal. The transaction status changed can be received via the push method (see Payment notification).

Operation: ManualClear

To clear a transaction more than once, the ManualClear call is used multiple times with an amount less than the authorization amount. The total amount of all clearings can not exceed the authorized amount.

📘

The amount element is provided as cent amount.

<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:ManualClear>
      <merchantID>90000</merchantID>
      <clearingDetails>
        <mpayTID>193603</mpayTID>
        <amount>1000</amount>
      </clearingDetails>
    </etp:ManualClear>
  </soapenv:Body>
</soapenv: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:ManualClearResponse>
      <status>OK</status>
      <returnCode>OK</returnCode>
      <transaction>
        <mpayTID>193603</mpayTID>
        <tStatus>BILLED</tStatus>
        <stateID>13029</stateID>
        <tid>160530-093423</tid>
      </transaction>
    </etp:ManualClearResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As response the cleared transaction is listed with its current state and a state id.

📘

Additional to the status and returnCode, the result of the Confirmation Interface should be checked to determine if the operation was successful.

📘

When using multiple clearings, the stateID is needed when a clearing has to be refunded.

Updated about 7 years ago