Pre-Authorization

Overview

The pre-authorization command temporarily places a hold on a specific amount on a credit card before the final amount is known. Once the final amount is determined, you can submit a pre-authorization completion request using that amount and the transactionId of the original pre-authorization. To learn how to execute a pre-authorization completion request, visit Pre-Authorization Completion Command.

Pre-Authorization Command

📘
NOTE:
Pre-authorization is not supported on Interac.

Request Structure

Direct and App-to-app

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
istConfigCode	String	Moneris provided integration configuration code	V25	Required
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
request	Array	Contains data applicable to transaction request	—	—
orderId	String	Order ID from Purchase	V50	Required
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
linkId	String	Id used to group related transactions	V50	Optional
terminalId	String	Destination Terminal ID	F8	Optional
userName	String	Unique identifier for clerk / user	V30	Optional
customIdData	String	Custom field	V50	Optional
action	String	"preAuthorization"	V50	Required
totalAmount	String	Total transaction amount	V9	Required
remainingAmount	String	Amount for partial authorization transactions. See remainingAmount for details	V5	Optional
dynamicDescriptor	String	Merchant-defined description	V20	Optional
progressStatus	String	If value is set to "True", terminal will return progress to POS. Note: This feature is only available on Direct Integration.	V5	Optional
modifier	String	Enum which further classifies transaction	V24	Optional
language	String	Valid values "EN" and "FR". If value is not provided, the payment app will use the language from TMS	F2	Optional
subtotalAmount	String	Amount without taxes or fees	V9	Optional
taxes	Array	Maximum of 5 tax objects	—	—
taxName	String	Name to be displayed on receipt (hst, gst etc)	V15	Optional
taxAmount	String	Corresponding amount	V9	Conditional

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "orderId": "example_orderId",
        "idempotencyKey": "example_idempotencyKey",
        "action": "preAuthorization",
        "totalAmount": "example_totalAmount"
      }
    ]
  }
}

Cloud

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
apiToken	String	Moneris assigne identifier	V50	Optional
storeId	String	Store ID of requestor	V50	Required
istConfigCode	String	Moneris provided integration configuration code	V25	Required
postBackUrl	String	This field is required for postback and combined integration	V2000	Conditional
polling	String	This field is required for combined integration	V5	Conditional
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
request	Array	Contains data applicable to transaction request	—	—
orderId	String	Order ID from Purchase	V50	Required
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
linkId	String	Id used to group related transactions	V50	Optional
userName	String	Unique identifier for clerk / user	V30	Optional
customIdData	String	Custom field	V50	Optional
action	String	"preAuthorization"	V50	Required
totalAmount	String	Total transaction amount	V9	Required
remainingAmount	String	Amount for partial authorization transactions. See remainingAmount for details.	V9	Optional
safAllowed	String	Toggle for SAF. Note: SAF is currently not supported. (Future Release)	V5	Optional
dynamicDescriptor	String	Merchant-defined description	V20	Optional
modifier	String	Enum which further classifies transaction	V24	Optional
terminalId	String	Destination TerminalID	F8	Required
language	String	Valid values "EN" and "FR". If value is not provided, the payment app will use the language from TMS	F2	Optional
subtotalAmount	String	Amount without taxes or fees	V9	Optional
taxes	Array	Maximum of 5 tax objects	—	—
taxName	String	Name to be displayed on receipt (hst, gst etc)	V15	Optional
taxAmount	String	Corresponding amount	V9	Conditional

Request example

{
  "apiVersion": "3.0",
  "apiToken": "example_apiToken",
  "storeId": "example_storeId",
  "istConfigCode": "example_istConfigCode",
  "polling": "true",
  "postBackUrl": "https://example.client.url",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "orderId": "example_orderId",
        "idempotencyKey": "example_idempotencyKey",
        "terminalId": "example_terminalId",
        "action": "preAuthorization",
        "totalAmount": "1110"
      }
    ]
  }
}

Response Structure

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
statusCode	String	Status code for the overall transaction request	V4	Required
status	String	Description of the statusCode	V4	Required
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
response	Array	Contains data applicable to transaction request	—	—
orderId	String	Terminal will either return the orderId from the request or generate a new unique orderId if no orderId was present in the request	V50	Required
transactionId	String	Unique identifier for this request	V50	Required
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
linkId	String	Id used to group related transactions	V50	Optional
action	String	"preAuthorization"	V50	Required
statusCode	String	Status code for individual request	V4	Required
status	String	Description of the individual statusCode	V50	Required
totalAmount	String	Echo of the Total transaction amount from the request	V9	Required
approvedAmount	String	Payment amount received / approved	V9	Conditional
tenderType	String	Payment Type: Credit, Debit, Gift etc	V50	Required
cardType	String	Card Type: V, M, P, AX etc	V2	Conditional
cardName	String	Card Name: Visa, MasterCard, Interac, Amex etc	V25	Conditional
sequenceNum	String	Sequence Number	V18	Conditional
realTimeUniqueId	String	Real Time Moneris Transaction Unique Identifier	F15	Conditional
responseCode	String	Moneris Host Response Code	V3	Conditional
iso	String	ISO response Code	V2	Conditional
authCode	String	Authorization code returned from the issuing institution.	V8	Conditional
formFactor	String	EMV Specific Data	F2	Conditional
maskedPan	String	Masked Primary Account Number (PAN)	V21	Conditional
completed	String	"true" or "false"	V5	Required
receipt	String	Financial receipt data sent using ISO-8895-1 encoding	V4000	Conditional
receiptChoice	String	The choices of how the receipt is being returned to the cardholder at the time of transaction. Valid values include: PRINT (Default Option), EMAIL, SMS, NONE.	V10	Conditional
terminalId	String	Destination Terminal ID	F8	Required
dccOptIn	String	This field indicates a Dynamic Currency Conversion (DCC) transaction.	V5	Optional
installmentOptIn	String	This field indicates an Installment by Visa transaction	V5	Optional
receiptExtension	String	DCC transaction data for compact format receipts	V275	Conditional

Response example

{
  "apiVersion": "3.0",
  "statusCode": "example_statusCode",
  "status": "example_status",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "response": [
      {
        "orderId": "example_orderId",
        "transactionId": "example_transactionId",
        "statusCode": "example_statusCode",
        "status": "example_status",
        "idempotencyKey": "example_idempotencyKey",
        "completed": "true",
        "responseCode": "example_responseCode",
        "iso": "example_iso",
        "approvedAmount": "example_approvedAmount",
        "totalAmount": "example_totalAmount",
        "tenderType": "example_tenderType",
        "cardType": "example_cardType",
        "sequenceNum": "example_sequenceNum",
        "realTimeUniqueId": "example_realTimeUniqueId",
        "authCode": "example_authCode",
        "formFactor": "example_formFactor",
        "maskedPan": "example_maskedPan",
        "action": "preAuthorization",
        "receipt": "example_receipt",
        "receiptChoice": "PRINT",
        "terminalId": "example_terminalId"
      }
    ]
  }
}

Element	Type	Description	Size	Required
receipt	Object	Contains the response data message	—	—
apiVersion	String	API version number	V20	Required
statusCode	String	Status code for the overall transaction request	V4	Required
status	String	Description of the statusCode	V4	Required
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
response	Array	Contains data applicable to transaction request	—	—
orderId	String	Unique identifier for this request	V50	Required
transactionId	String	Unique identifier for this request	V50	Required
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
linkId	String	Id used to group related transactions	V50	Optional
action	String	"preAuthorization"	V50	Required
statusCode	String	Status code for individual request	V4	Required
status	String	Description of the individual statusCode	V50	Required
saf	String	Identifier for SAF Transaction	V5	Required
approvedAmount	String	Payment amount received / approved	V9	Required
totalAmount	String	Echo of the Total transaction amount from the request	V9	Required
tenderType	String	Payment Type: Credit, Debit, Gift etc	V50	Required
cardType	String	Card Type: V, M, P, AX etc	V2	Conditional
cardName	String	Card Name: Visa, MasterCard, Interac, Amex etc	V25	Conditional
sequenceNum	String	Sequence Number	V18	Conditional
realTimeUniqueId	String	Real Time Moneris Transaction Unique Identifier	F15	Conditional
responseCode	String	Moneris Host Response Code	V3	Conditional
iso	String	ISO response Code	V2	Conditional
authCode	String	Authorization code returned from the issuing institution.	V8	Conditional
formFactor	String	EMV Specific Data	F2	Conditional
maskedPan	String	Masked Primary Account Number (PAN)	V21	Conditional
completed	String	"true" or "false"	V5	Required
cloudTicket	String	This is the unique reference id of the cloud request	V100	Required
receipt	String	Financial receipt data sent using ISO-8895-1 encoding	V4000	Conditional
receiptChoice	String	The choices of how the receipt is being returned to the cardholder at the time of transaction. Valid values include: PRINT (Default Option), EMAIL, SMS, NONE.	V10	Conditional
terminalId	String	Destination Terminal ID	F8	Required
dccOptIn	String	This field indicates a Dynamic Currency Conversion (DCC) transaction (opted in or not). Note: This field is present for DCC transactions only	V5	Optional
installmentOptIn	String	This field indicates an Installment by Visa transaction (opted in or not). Note: This field is present for Intallment by Visa transactions only	V5	Optional
receiptExtension	String	DCC transaction data for compact format receipts	V275	Conditional

Response example

{
  "receipt": {
    "apiVersion": "3.0",
    "statusCode": "example_statusCode",
    "status": "example_status",
    "dataId": "example_dataId",
    "dataTimestamp": "1969-12-31 23:59:59",
    "data": {
      "response": [
        {
          "orderId": "example_orderId",
          "transactionId": "example_transactionId",
          "linkId": "example_linkId",
          "statusCode": "example_statusCode",
          "status": "example_status",
          "idempotencyKey": "example_idempotencyKey",
          "terminalId": "example_terminalId",
          "cloudTicket": "example_cloudTicket",
          "completed": "true",
          "responseCode": "example_responseCode",
          "iso": "example_iso",
          "approvedAmount": "1300",
          "tenderType": "example_tenderType",
          "cardType": "example_cardType",
          "sequenceNum": "example_sequenceNum",
          "realTimeUniqueId": "example_realTimeUniqueId",
          "authCode": "example_authCode",
          "formFactor": "example_formFactor",
          "maskedPan": "example_maskedPan",
          "action": "preAuthorization",
          "receipt": "example_receipt",
          "receiptChoice": "PRINT"
        }
      ]
    }
  }
}

Errors

If your response contains errors, visit the Errors page for a detailed description of each one.