Two-Step Payment
(Preauth & Completion)

Accepting payment via Moneris API allows for a two-step process splitting payment into its components. In the first step, a preauthorization verifies a customer’s card and reserves funds. When the merchant is ready to finalize the transaction, they proceed with the second step, the completion request that captures funds for deposit to the merchant’s bank account.

Businesses use the two-step preauthorization

1.Collect Cardholder Data

Before you can send the server-to-server API call for the payment, you will need to collect credit card details from the cardholder to populate your transaction. Two options are available:

  • Hosted Tokenization : This Moneris service embeds a box for card data input on your website hosted on Moneris systems and returns a temporary token for use in the payment instead. This protects your website from handling sensitive card data directly and avoids burdens of certification to Payment Card Industry (PCI) compliance.

  • Merchant Collection : You can collect credit card numbers, expiry dates, and card verification details directly from the cardholder on your website and handle that data throughout the payment process. Doing so requires PCI compliance to ensure the security of the data.

  • Payment Method On-file : If you have stored a payment method for this cardholder previously, such as a permanent token in the Moneris Vault service or as a Payment Method via our API, you no longer need to collect it again on subsequent transactions and can proceed with next steps. During the API call, you can use these stored methods in place of cardholder input.

2. 3-D Secure Authentication 

If you already have 3-D Secure features enabled on your merchant account, see here for steps on implementing it before the payment transaction flow. Link to 3DS overview here.

3DS - Browser Channel 3DS - Requestor Initiated

Moneris recommends performing 3-D Secure Authentication before initiating the payment transaction. This eFraud feature is designed to reduce card not present fraud by making a risk assessment based on transaction and device data while also supporting further risk minimization measures such as a challenge to the cardholder. In some cases, a liability shift takes effect for certain card-not-present fraud-related chargebacks enabling the merchant to provide goods and services with confidence.

3. Create Payment

Your server sends a payment request to Moneris via an API call. This call uses the POST /payment endpoint and with the following parameter to perform both authorization and settlement (purchase).   

“AutomaticCapture” = “false”

This parameter controls if the payment will settle automatically. Using a value of “false” reserved for the pre-authorization & completion flow instead.

An important factor in forming the request is specifying the Payment Method used to pay for the transaction. Depending on the scenario and payment method, you may need to include or omit fields from the API call. Below is a list of scenarios and how they change the required fields:

If you wish to store this payment method for use in subsequent transactions, include “storePaymentMethod” = “CARDHOLDER_INITIATED” or “storePaymentMethod” = “MERCHANT_INITIATED” in the main body of the call. You will receive the “paymentMethodID” for the stored method in the transaction response.

More information about Credential on File

Go to Credential on File

If you are using a stored Payment Method from the Moneris API and the transaction is merchant initiated, include a “paymentMethodID” for it within the main body of the request. The “paymentMethod” object is omitted. 

  • Include the “credentialOnFileInformation” object with appropriate values for the matching merchant-initiated subsequent transaction scenario/

If you are using a stored Payment Method from the Moneris API and the transaction is cardholder initiated, include a “paymentMethodID” for it within the main body . 

  • If the cardholder is using a credit card (“paymentMethodType” = “CARD”), you will need to collect the Card Verification Digits (CVD) again at time of transaction. This data is not stored within the Payment Method entity. Include both the “PaymentMethodID” and the “paymentMethod” object; in the object, include the “cvd” field and value but omit the rest. 

  • Otherwise, use of the “paymentMethodID” to reference a stored Payment Method means you must omit the “paymentMethod” object. 

  • In either case, include the “credentialOnFileInformation” object with the appropriate cardholder-initiated subsequent transaction scenario. 

For a payment method obtained at the time of the transaction, include a “paymentMethod” object within the main body of the /payment API call. Inside its “PaymentMethodData” object, include the matching “paymentMethodType” indicating what kind of method it is.

Ensure the “credentialOnFileInformation” object is included with appropriate values for a first transaction. Storing a permanent payment method requires notifying the card brand on the intended use-case for the credential; for more information, consult Credential on File. 

Moneris returns a response to your server with data on the success or failure of the request. The HTTP response status code and the contents of the “transactionDetails” object in the response body will inform you on the results of the transaction.

Locate your Response Code and learn more about what it means
Access Response Code

POST /payments for basic preauthorization.

Samples

4. Complete Payment

When you are ready to finalize the transaction, usually after an internal order management and shipping process reach its last stage, you can send a completion request to Moneris. This call uses the POST /payments/id/complete endpoint, with the payments ID referencing the “paymentID” from the prior response.

Sample

Additional Information

Learn more with the API Definitions

Peruse the endpoints, request/response formats, and authentication methods covered in this scenario.

API References