Preauthorization management

Pre-Authorization, often referred to as a Reservation, is a two-step process used to secure funds on a customer's card without immediately finalizing the payment. This guarantees that the necessary amount is available and reserves it for a defined period, delaying the final capture of funds until goods or services are delivered.

1. Customer Flow and Use Cases

This method is ideal for merchants where the final transaction amount is not known at the time of the initial service agreement, or where a temporary hold is required as collateral:

Use Case Step 1: Open Pre-Authorization Step 2: Capture/Completion
Hotels Reserve the room rate plus an estimated security deposit for incidentals. Capture the final room rate plus minibar charges upon check-out.
Car Rentals Place a hold on the estimated rental cost plus a damage deposit. Capture the final rental charge once the vehicle is returned.
Restaurants/Bars Confirm the card is valid with a small initial authorization (or the meal cost). Capture the full amount, including the final calculated tip.

Pre-Authorization is executed using the standard PaymentRequest , with the specific transaction stage defined by the PaymentType field in the request body.

1. Open a Pre-Authorization

This stage places an initial hold on the required funds.

Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

Body

A Preauthorization Request is handled by sending a standard Payment Request body, but with PaymentType set as FirstReservation. 

Preauthorization Request example JSON

Preauthorisation is triggered by Payment Request as well, you have to specify proper PaymentType (FirstReservation)

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "PayOnSite",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "102"
  },
  "PaymentRequest": {
    "PaymentData": {
      "PaymentType": "FirstReservation"
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "NOK",
        "RequestedAmount": 123
      }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "OperatorLanguage": "EN",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-30T00:04:40.567",
        "TransactionID": "12345"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

Preauthorization Request example XML

Preauthorisation is triggered by Payment Request as well, you have to specify proper PaymentType (FirstReservation)

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest 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">
	<MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="9260" SaleID="WeDeal123" POIID="WeDeal456"></MessageHeader>
	<PaymentRequest>
		<SaleData OperatorID="666" SaleReferenceID="123">
			<SaleTransactionID TransactionID="123" TimeStamp="2025-11-04T08:34:46Z"></SaleTransactionID>
		</SaleData>
		<PaymentTransaction>
			<AmountsReq Currency="EUR" RequestedAmount="120.00"></AmountsReq>
		</PaymentTransaction>
		<PaymentData PaymentType="FirstReservation"></PaymentData>
		<MarketpayPaymentExtensions></MarketpayPaymentExtensions>
	</PaymentRequest>
</SaleToPOIRequest>

Review the full schema on the API specification page for required fields.

Response:

The terminal responds with a standard successful PaymentResponse containing the original SaleTransactionID, which must be stored.

2. Capture the Funds

This stage finalizes the payment, capturing the reserved funds. 

It can also be done online on Market Pay Hub

Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

Body

A Preauthorization Request is handled by sending a standard Payment Request body, but with PaymentType set as Completion. You also have to include the original transaction's reference ID in SaleData.SaleReferenceID.

You must include the total amount being captured in PaymentTransaction.AmountsReq. This amount can be the same as, or less than, the original FirstReservation amount.

Note: If the final amount is zero, you must send a Reversal Request instead of a Completion.

Preauthorisation Completion Request example JSON

Preauthorisation Completion is triggered by Payment Request as well, you have to specify proper PaymentType and specify saleReferenceID

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "102"
  },
  "PaymentRequest": {
    "PaymentData": {
      "PaymentType": "Completion"
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "EUR",
        "RequestedAmount": 123
      }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "OperatorLanguage": "EN",
      "SaleReferenceID": "19",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-30T00:09:59.383",
        "TransactionID": "12345"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

Preauthorisation Completion Request example XML

Preauthorisation Completion is triggered by Payment Request as well, you have to specify proper PaymentType and specify saleReferenceID. In this example, completion is 100€ when it was opened for 120€

<SaleToPOIRequest 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">
	<MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="9261" SaleID="WeDeal123" POIID="WeDeal456"></MessageHeader>
	<PaymentRequest>
		<SaleData OperatorID="666" SaleReferenceID="1">
			<SaleTransactionID TransactionID="123" TimeStamp="2025-11-04T08:35:53Z"></SaleTransactionID>
		</SaleData>
		<PaymentTransaction>
			<AmountsReq Currency="EUR" RequestedAmount="100.00"></AmountsReq>
		</PaymentTransaction>
		<PaymentData PaymentType="Completion"></PaymentData>
		<MarketpayPaymentExtensions></MarketpayPaymentExtensions>
	</PaymentRequest>
</SaleToPOIRequest>

Review the full schema on the API specification page for required fields.

Response

The terminal responds with a standard successful PaymentResponse containing the original SaleTransactionID, which must be stored.