### Magento Setup Commands

Source: https://developer.moneris.com/en/Documentation/NA/Shopping%20Carts/CED%20Commerce

These commands are used to upgrade and deploy static content for Magento after installing a new extension. Ensure you are in the Magento root directory when executing these commands.

```shell
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy
```

--------------------------------

### Setting Billing using Hash Table Example

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/~/~/~/~/~/~/~/~/link__id=A0B708AB8BE045FEB5F1B4C55FF94DF7&_z=z

A practical example of setting billing information using a JavaScript object as a hash table. It shows the structure and keys required for the billing data.

```javascript
var billing = {
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Widgets Inc.",
  "address": "123 Main St",
  "city": "Anytown",
  "province": "ON",
  "postal_code": "A1A 1A1",
  "country": "CA",
  "phone": "555-123-4567",
  "fax": "555-987-6543",
  "tax1": "10.00",
  "tax2": "5.00",
  "tax3": "1.00",
  "shipping_cost": "15.00"
};
customer.setBilling(billing);
```

--------------------------------

### Setting Shipping using Hash Table Example

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/~/~/~/~/~/~/~/~/link__id=A0B708AB8BE045FEB5F1B4C55FF94DF7&_z=z

An example demonstrating how to set shipping information using a JavaScript object as a hash table. This illustrates the expected keys and format for shipping data.

```javascript
var shipping = {
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Widgets Inc.",
  "address": "123 Main St",
  "city": "Anytown",
  "province": "ON",
  "postal_code": "A1A 1A1",
  "country": "CA",
  "phone": "555-123-4567",
  "fax": "555-987-6543",
  "tax1": "0.00",
  "tax2": "0.00",
  "tax3": "0.00",
  "shipping_cost": "15.00"
};
customer.setShipping(shipping);
```

--------------------------------

### Recurring Billing Setup

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/~/~/~/~/~/~/link__id=F7132403C57F4AB2A0BB625BB79F64BC&_z=z

This API allows for the setup of recurring billing transactions. It defines the billing frequency, amount, and start date for future transactions.

```APIDOC
## POST /recurring/billing

### Description
Sets up recurring billing transactions for future charges. This endpoint requires details about the billing cycle, amount, and start date.

### Method
POST

### Endpoint
`/recurring/billing`

### Parameters
#### Query Parameters
- **recur_unit** (String) - Required - The unit for the recurrence interval (day, week, month, or eom).
- **period** (String) - Required - The number of `recur_unit`s that must pass between recurring billings (1-999).
- **start_now** (String) - Required - If set to 'true', the first charge is made immediately. If 'false', the billing starts on `start_date`.
- **start_date** (String) - Required - The date of the first future recurring billing transaction in 'YYYY/MM/DD' format. Must be a future date if `start_now` is 'false'.
- **num_recurs** (String) - Required - The total number of times the transaction must recur (1-99).
- **recur_amount** (String) - Required - The amount of the recurring transaction (e.g., '0.01' to '9999999.99'). Must contain at least three digits, with two decimal places.
- **payment_information** (String) - Optional - Describes whether the transaction is the first or subsequent in the series (e.g., '0' for first, '2' for subsequent).

### Request Example
(No specific request example provided in the source text, but parameters are listed above)

### Response
#### Success Response (200)
- **RecurSuccess** (Boolean) - Indicates whether the recurring billing transaction has been successfully set up for future billing.

#### Response Example
(No specific response example provided in the source text, but the success field is listed above)

### Error Handling
Specific error codes and messages will be returned based on validation failures or processing errors.
```

--------------------------------

### Moving To Production With 3-D Secure 2.2

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Instructions on how to transition your 3-D Secure 2.2 integration from testing to a production environment with Moneris.

```APIDOC
## Moving To Production With 3-D Secure 2.2

### Description
This section outlines the steps required to move your 3-D Secure 2.2 integration into the production environment.

### Steps
1. **Use Production URL**: For your production requests, use the production URL as the Host: `www3.moneris.com`.
2. **Production Credentials for CardLookUp**: In all `CardLookUp` requests, ensure you use the production versions of your **store ID** and **API token**.
```

--------------------------------

### Recurring Billing Setup Parameters

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/~/~/link__id=5938A27CEB4E41CF9E1551727B0589D4&_z=z

Defines the mandatory parameters for setting up recurring billing transactions. These include the recurrence unit, whether to start immediately, the start date, the number of recurrences, the period between recurrences, and the recurring amount.

```text
Recur unit: day, week, month or eom
Start Now: true/false
Start Date: YYYY/MM/DD format
Number of Recurs: numeric 1-99
Period: numeric 1-999
Recurring Amount: 9-character decimal 0.01-9999999.99
```

--------------------------------

### Moving To Production With 3-D Secure 2.2

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Instructions for transitioning your 3-D Secure 2.2 integration from the testing environment to production with Moneris.

```APIDOC
## Production Environment Configuration

### Description
Once your 3-D Secure 2.2 integration has been thoroughly tested and validated, follow these instructions to seamlessly move your integration to the production environment.

### Production Steps
1.  **Host URL**: Switch to the production Host URL: `www3.moneris.com` for all your requests.
2.  **Credentials**: In all **CardLookUp** requests, ensure you are using the production versions of your Store ID and API Token.
```

--------------------------------

### Google Pay Transaction Request Variables (Java Example)

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Google%20Pay/On%20The%20Web

Example of setting required fields for a Google Pay™ transaction request using Java. Demonstrates setting transaction type, order ID, payment data, and amount.

```java
.setTransactionType(Constants.TransactionCode.PURCHASE)
.setOrderId("GooglePayTest-"+new Date().getTime())
.setPaymentData(data)
.setAmount (PaymentsUtil.microsToString (mBikeItem.getPriceMicros ()+mShippingCost))
```

--------------------------------

### Example: Setting Shipping using Hash Table (Conceptual)

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/link__id=A0B708AB8BE045FEB5F1B4C55FF94DF7&_z=z

Illustrates the conceptual process of setting shipping information via a hash table, including instantiation and populating the table.

```javascript
// Instantiate a CustInfo object (if not already done)
const customer = new CustInfo();

// Instantiate a Hashtable object for shipping
const shippingTable = new Hashtable();

// Build the hashtable using put methods
shippingTable.put("first_name", "Jane");
shippingTable.put("last_name", "Smith");
shippingTable.put("address", "456 Oak Ave");
// ... (add all other mandatory shipping fields)

// Call the CustInfo object's setShipping() method
customer.setShipping(shippingTable);

// Assuming 'transaction' is an instance of a transaction object
// transaction.setCustInfo(customer);
```

--------------------------------

### Example: Setting Billing using Hash Table (Conceptual)

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/link__id=A0B708AB8BE045FEB5F1B4C55FF94DF7&_z=z

Illustrates the conceptual process of setting billing information via a hash table, including instantiation and populating the table.

```javascript
// Instantiate a CustInfo object
const customer = new CustInfo();

// Instantiate a Hashtable object for billing
const billingTable = new Hashtable();

// Build the hashtable using put methods
billingTable.put("first_name", "John");
billingTable.put("last_name", "Doe");
billingTable.put("address", "123 Main St");
// ... (add all other mandatory billing fields)

// Call the CustInfo object's setBilling() method
customer.setBilling(billingTable);

// Assuming 'transaction' is an instance of a transaction object
// transaction.setCustInfo(customer);
```

--------------------------------

### Get Rate Validity Start Time

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/Response%20Fields

Retrieves the Unix UTC timestamp indicating when the rate becomes valid. This is a 10-character numeric string.

```java
receipt.getRateValidityStartTime();
```

--------------------------------

### Production Environment Configuration

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Instructions for moving your 3-D Secure 2.2 integration to a production environment. This involves using the production URL and production credentials.

```APIDOC
## Moving To Production With 3-D Secure 2.2

### Description
Once your 3D Secure 2.2 integration has been successfully tested, follow these steps to transition to the production environment:

1.  **Production URL**: Use `www3.moneris.com` as the Host for your requests.
2.  **Production Credentials**: For all `CardLookUp` requests, ensure you are using the production versions of your `store ID` and `API token`.

### Method
N/A (Configuration Guide)

### Endpoint
N/A (Configuration Guide)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Get Rate Inquiry Start Time

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/Response%20Fields

Retrieves the local time when the rate was requested, formatted according to ISO 8601. This is a 24-character alphanumeric string.

```java
receipt.getRateInqStartTime();
```

--------------------------------

### Testing Environment Configuration

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Instructions for configuring your environment to test 3-D Secure 2.2 integrations with Moneris. This includes using specific testing URLs and credentials.

```APIDOC
## Testing 3-D Secure 2.2 Integration

### Description
To test your 3-D Secure 2.2 integration, follow these steps:

1.  **Testing URL**: Use `esqa.moneris.com` as the Host for your requests.
2.  **Testing Credentials**: For all `CardLookUp`, `threeDSAuthentication`, and `CavvLookup` requests, ensure you are using the testing versions of your `store ID` and `API token`.

### Method
N/A (Configuration Guide)

### Endpoint
N/A (Configuration Guide)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Getting a Temporary Token

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/link__id=A8335F81F39543C68B50E2B746C9D570&_z=z

Instructions and example for obtaining a temporary token using an IFrame request to the Moneris Gateway. This token is used for subsequent financial transaction processing.

```APIDOC
## Getting a Temporary Token

### Description
To obtain a temporary token, you need to send a request to Moneris from within an IFrame. The Profile ID and the source/postMessage URL must be correctly configured.

### Method
GET (within an IFrame)

### Endpoint
**QA Environment:** `https://esqa.moneris.com/HPPtoken/index.php`
**Production Environment:** `https://www3.moneris.com/HPPtoken/index.php`

### Parameters
#### Query Parameters
- **Profile ID** (string) - Required - Your unique Moneris Hosted Tokenization Profile ID.

### Request Example
```html
<iframe
  src="https://esqa.moneris.com/HPPtoken/index.php?Profile_ID=YOUR_PROFILE_ID"
  width="400" height="300"
  frameborder="0"
  scrolling="no"
></iframe>
```
*Note: Replace `YOUR_PROFILE_ID` with your actual Profile ID. Update the `src` URL to the appropriate QA or production URL as needed.*

### Response
#### Success Response (via `postMessage` from IFrame)
- **token** (string) - A temporary token representing the credit card number.

#### Response Example (from `postMessage` event)
```json
{
  "token": "TEMPORARY_CARD_TOKEN_HERE"
}
```
```

--------------------------------

### 3-D Secure 2.2 Integration Guide

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

This section outlines the steps required to build and integrate your 3-D Secure 2.2 solution with Moneris.

```APIDOC
## 3-D Secure 2.2 Integration

### Description
This guide details the process of integrating with the Moneris 3-D Secure 2.2 API, including activation and transaction flows.

### Activation
To activate Visa Secure, MasterCard Identity Check, and/or American Express SafeKey, contact Moneris Sales Support at 1-855-465-4980.

### Transaction Flow - Browser Channel

**Step 1-2 (Optional): Card Lookup for Fingerprinting**

*   **Purpose**: Initiate cardholder browser fingerprinting and determine the card's supported 3DS version.
*   **Process**: The merchant website collects device information and sends it to Moneris via a `card_lookup` request.
*   **Moneris Response**: Returns `card_lookup` response containing supported 3DS version, ACS URL, and 3DS Method Data.
*   **Merchant Browser Action**: Submits an HTTP POST to the ACS URL with the method data.

**Step 3-4 (Required): 3DS Authentication Request**

*   **Purpose**: Initiate validating the cardholder identity and perform an initial risk assessment.
*   **Request**: Merchant website calls `threeDSAuthentication`.
*   **Moneris Communication**: Moneris communicates with the 3DS Directory and ACS system.
*   **Moneris Response (`threeDSAuthentication` response)**: Contains `TransStatus` indicating the next action:
    *   `Y` or `A`: Frictionless flow. Proceed to financial transaction with provided CAVV value.
    *   `C`: Challenge flow. POST a `<form>` with `creq` (containing ChallengeData) to the `ChallengeURL`.
    *   `D`: Decoupled Authentication. Refer to Decoupled Authentication documentation.

**Step 5-10 (Challenge Flow Only): Handling Challenges**

*   **Purpose**: Complete the cardholder authentication challenge and obtain CAVV/ECI values.
*   **Step 5**: Merchant website sends HTTP POST to `ChallengeURL` with `CREQ` value.
*   **Step 6**: ACS system presents challenge to cardholder. Merchant website receives `CRES` value via HTTP POST response.
*   **Step 7-8**: ACS supplies results to 3DS Directory, which forwards to Moneris.
*   **Step 9**: Merchant website sends `cavv_lookup` request to Moneris, including the `CRES` value.
*   **Moneris Response (`cavv_lookup` response)**: Provides necessary ECI and CAVV values.
*   **Final Step**: Proceed to the financial transaction with the obtained 3DS authentication details.

### Version Compatibility

*   All API developments must support the addition of new fields and error conditions in responses.
*   Changes affecting backwards compatibility will be communicated with advance notice.
*   It is recommended to validate for success states and handle errors separately, including a catch for unexpected errors.
```

--------------------------------

### Get Core Response Fields in PHP

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/E-Fraud/3DSecure

Retrieves core transaction response fields like Message, Receipt ID, and ECI using the Moneris SDK in PHP. Ensure you have the Moneris SDK installed and initialized.

```php
echo $receipt->GetMessage();

echo $receipt->GetReceiptId();

echo $receipt->GetMpiEci();
```

--------------------------------

### Example: Setting Billing using Hash Table (Conceptual)

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/Pre-Authorization

Illustrates the conceptual steps for setting billing information using a hash table. This involves instantiating objects, populating the hash table, and then associating it with the customer object.

```javascript
// 1. Instantiate CustInfo object
// var customer = new CustInfo();

// 2. Instantiate Hashtable object for billing
// var billing_hash = new Hashtable();

// 3. Build the hashtable using put methods
// billing_hash.put("first_name", "John");
// billing_hash.put("last_name", "Doe");
// billing_hash.put("address", "123 Main St");
// ... other billing fields

// 4. Call the CustInfo object's setBilling() method
// customer.setBilling(billing_hash);

// 5. Call the transaction object's setCustInfo() method
// transaction.setCustInfo(customer);
```

--------------------------------

### Purchase with 3-D Secure and Recurring Billing

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Illustrates a Purchase transaction with 3-D Secure when also sending the Recurring Billing Info object. This example uses C# code to demonstrate the setup.

```APIDOC
## Purchase with 3-D Secure and Recurring Billing

### Description
This endpoint facilitates a purchase transaction that incorporates both 3-D Secure authentication and recurring billing details. The provided example demonstrates how to construct the request using C#.

### Method
POST

### Endpoint
`/purchase` (Note: This is a hypothetical endpoint based on context)

### Parameters
#### Request Body Fields
- **order_id** (_String_) - Unique identifier for the order.
- **cust_id** (_String_) - Customer identifier.
- **amount** (_String_) - Transaction amount.
- **pan** (_String_) - Primary Account Number (credit card number).
- **expdate** (_String_) - Expiry date in YYMM format.
- **cavv** (_String_) - Cardholder Authentication Verification Value.
- **crypt_type** (_String_) - Cryptogram type. Mandatory for AMEX cards.
- **dynamic_descriptor** (_String_) - Optional descriptor for the transaction.
- **ThreeDSVersion** (_String_) - Version of 3-D Secure. Mandatory for financial transactions using 3rd Party 3-D Secure services.
- **ThreeDSServerTransId** (_String_) - Transaction ID from the 3-D Secure server. Mandatory for financial transactions using 3rd Party 3-D Secure services.
- **DsTransId** (_String_) - Optional DS Transaction ID for 3rd party 3ds service.
- **Network** (_String_) - Set only for Interac e-commerce.
- **DataType** (_String_) - Set only for Interac e-commerce.
- **WalletIndicator** (_String_) - Set only for wallet transactions (e.g., APPLE PAY).
- **Recur** (_Object_) - Object containing recurring billing details:
  - **recur_unit** (_String_): e.g., "month"
  - **start_now** (_String_): `true` or `false`
  - **start_date** (_String_): Date in YYYY/MM/DD format.
  - **num_recurs** (_String_): Number of recurrences.
  - **period** (_String_): Billing period.
  - **recur_amount** (_String_): Recurring amount.
- **CofInfo** (_Object_): Object containing Card on File information:
  - **PaymentIndicator** (_String_): e.g., "R"
  - **PaymentInformation** (_String_): e.g., "2"
  - **IssuerId** (_String_): Issuer ID.

### Request Example
```json
{
  "order_id": "Test20231027103000",
  "cust_id": "CUS887H67",
  "amount": "10.42",
  "pan": "4242424242424242",
  "expdate": "1901",
  "cavv": "AAABBJg0VhI0VniQEjRWAAAAAAA=",
  "crypt_type": "5",
  "dynamic_descriptor": "123456",
  "ThreeDSVersion": "2.2.0",
  "ThreeDSServerTransId": "e11d4985-8d25-40ed-99d6-c3803fe5e68f",
  "Recur": {
    "recur_unit": "month",
    "start_now": "true",
    "start_date": "2018/02/25",
    "num_recurs": "12",
    "period": "1",
    "recur_amount": "30.00"
  },
  "CofInfo": {
    "PaymentIndicator": "R",
    "PaymentInformation": "2",
    "IssuerId": "168451306048014"
  }
}
```

### Response
#### Success Response (200)
- **transaction_id** (_String_) - Unique identifier for the transaction.
- **message** (_String_) - Confirmation message.

#### Response Example
```json
{
  "transaction_id": "txn987654321",
  "message": "Purchase with 3-D Secure and recurring billing successful."
}
```

#### Error Handling
- **400 Bad Request**: Invalid input parameters or missing mandatory fields.
- **401 Unauthorized**: Authentication failure.
- **500 Internal Server Error**: Server error during processing.
```

--------------------------------

### Hosted Tokenization Setup

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/link__id=A8335F81F39543C68B50E2B746C9D570&_z=z

Steps required to set up and configure the Moneris Hosted Tokenization feature within the Moneris Gateway Merchant Resource Centre.

```APIDOC
## Moneris Hosted Tokenization Setup

### Description
This section outlines the steps to configure Hosted Tokenization within the Moneris Gateway Merchant Resource Centre (MRC).

### Method
N/A (Configuration steps)

### Endpoint
N/A (Configuration steps)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Setup Steps:
1. Login to your Moneris Gateway Merchant Resource Centre.
2. Navigate to 'Admin' on the menu.
3. Select 'Hosted Tokenization' from the sub-menu.
4. Enter the source domain page (the main page that sends the transaction to Moneris).
5. Click 'Create Profile'.
6. Record the generated Profile ID. This ID is crucial for your HTML iFrame code.
7. Proceed with the required development as outlined in the documentation.
8. Test your solution in the designated test environment.
9. Activate your production store.
10. Create and configure your product Hosted Tokenization store in the production Merchant Resource Centre.
11. Implement the necessary changes to transition your solution from the test environment to production.
```

--------------------------------

### Testing 3-D Secure 2.2 Integration

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

Guidelines for testing your 3-D Secure 2.2 integration with Moneris, including specific URLs and credentials for testing environments.

```APIDOC
## Testing 3-D Secure 2.2 Integration

### Description
This section provides instructions for testing your 3-D Secure 2.2 integration with the Moneris platform.

### Steps
1. **Use Testing URL**: For your requests, use the testing URL as the Host: `esqa.moneris.com`.
2. **Testing Credentials for CardLookUp**: In all `CardLookUp` requests, ensure you use the testing versions of your **store ID** and **API token**.
3. **Testing Credentials for threeDSAuthentication**: In all `threeDSAuthentication` requests, ensure you use the testing versions of your **store ID** and **API token**.
4. **Testing Credentials for CavvLookup**: In all `CavvLookup` requests, ensure you use the testing versions of your **store ID** and **API token**.
```

--------------------------------

### Setting Order ID in JavaScript

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Google%20Pay/On%20The%20Web

Example of how to set a unique order ID for Google Pay transactions in JavaScript. It includes a timestamp to ensure uniqueness.

```javascript
setOrderId("GooglePayTest-" + new Date().getTime());
```

--------------------------------

### osCommerce: Embedding PHP Include for Order Addon

Source: https://developer.moneris.com/en/Documentation/NA/Shopping%20Carts/osCommerce

This code snippet demonstrates how to include an external PHP file (`orders_addon_campg.php`) into the `orders.php` file of an osCommerce installation. This is part of the Moneris Gateway integration setup.

```php
<?php include ("orders_addon_campg.php") ?>
```

--------------------------------

### 3-D Secure 2.2 Integration Guide

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

This section outlines the process of integrating with the 3-D Secure 2.2 API, including activation and transaction flows.

```APIDOC
## Activating 3-D Secure Functionality

To activate Visa Secure, MasterCard Identity Check, and/or American Express SafeKey transaction functionality, contact Moneris Sales Support at 1-855-465-4980.

## Transaction Flow for 3-D Secure - Browser channel

The 3DS 2.2 API is used when a customer initiates checkout. The process involves an optional card lookup for browser fingerprinting, followed by transmitting transactional information for risk assessment. The flow can result in either a "frictionless" (invisible to cardholder) or "challenge" (requires cardholder interaction) authentication.

### Steps 1 – 2 (Optional Card Lookup)

1.  **Merchant Website** collects device information and sends a `card_lookup` request to Moneris.
2.  **Moneris** submits data to the 3DS Directory Server and returns a `card_lookup` response with the card's supported 3DS version, ACS URL, and 3DS Method Data.
3.  **Merchant Browser** submits an HTTP POST to the ACS URL with the method data.

### Steps 3 – 4 (Required 3DS Authentication)

1.  **Merchant Website** initiates the `threeDSAuthentication` request to validate the cardholder identity.
2.  **Moneris** communicates with the 3DS Directory and ACS system for risk assessment.
3.  **Moneris** returns a `threeDSAuthentication` response with a `TransStatus` indicating the next action:
    *   `TransStatus = "Y"` or `"A"`: Frictionless flow. Proceed to financial transaction with provided CAVV value.
    *   `TransStatus = "C"`: Challenge flow. POST a form with a `creq` field (containing `ChallengeData`) to the `ChallengeURL`.
    *   `TransStatus = "D"`: Decoupled Authentication. Requires a challenge via a separate flow.

### Steps 5 – 10 (Challenge Flow Only)

1.  **Merchant Website** sends an HTTP POST to the `ChallengeURL` with `ChallengeData` as a `"CREQ"` value.
2.  **ACS System** presents a challenge to the cardholder.
3.  **Merchant Website** receives a `"CRES"` value from the ACS via HTTP POST response.
4.  **ACS** supplies results to the 3DS Directory, which forwards them to Moneris.
5.  **Merchant Website** sends a `cavv_lookup` request to Moneris, including the `"CRES"` value.
6.  **Moneris** responds with `cavv_lookup` response containing ECI and CAVV values, allowing progression to the financial transaction.
```

--------------------------------

### Recurring Billing Setup

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/API/~/~/~/~/~/~/~/~/link__id=5938A27CEB4E41CF9E1551727B0589D4&_z=z

This section details the parameters required to set up a recurring billing transaction. It includes details on recurrence units, start dates, number of recurrences, period between recurrences, and the recurring amount.

```APIDOC
## POST /api/recurring_billing

### Description
Sets up a recurring billing transaction for future charges.

### Method
POST

### Endpoint
/api/recurring_billing

### Parameters
#### Request Body
- **recur_unit** (String) - Required - Unit to be used as a basis for the interval. Can be set as 'day', 'week', 'month', or 'eom' (end of month).
- **start_now** (String) - Optional - If set to 'true', a single charge is made immediately. If 'false', billing starts in the future.
- **start_date** (String) - Required if start_now is false - Date of the first future recurring billing transaction in 'YYYY/MM/DD' format. Must be a future date.
- **num_recurs** (String) - Optional - The number of times the transaction must recur (numeric 1-99).
- **period** (String) - Required - Number of recur units that must pass between recurring billings (numeric 1-999).
- **recur_amount** (String) - Required - Amount of the recurring transaction. Format: 9-character decimal, e.g., '0.01' to '9999999.99'.

### Request Example
```json
{
  "recur_unit": "month",
  "start_now": "false",
  "start_date": "2024/12/01",
  "num_recurs": "12",
  "period": "1",
  "recur_amount": "25.50"
}
```

### Response
#### Success Response (200)
- **recurring_billing_success** (Boolean) - Indicates whether the recurring billing transaction has been successfully set up.
```

--------------------------------

### Purchase with 3-D Secure and Recurring Billing

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Level%202%203/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

This section demonstrates how to perform a purchase transaction that includes 3-D Secure authentication and recurring billing information. It provides a C# code example illustrating the setup of various objects and parameters.

```APIDOC
## Purchase with 3-D Secure and Recurring Billing

### Description
This endpoint facilitates a purchase transaction incorporating both 3-D Secure for enhanced security and recurring billing for subscription-based services. The provided example illustrates the construction of the transaction request in C#.

### Method
POST

### Endpoint
/purchase

### Parameters
#### Request Body
- **store_id** (String) - Your unique store ID.
- **api_token** (String) - Your API access token.
- **order_id** (String) - A unique identifier for the order.
- **cust_id** (String) - A unique identifier for the customer.
- **amount** (String) - The transaction amount.
- **pan** (String) - The Primary Account Number (PAN) of the card.
- **expdate** (String) - The expiry date of the card in YYMM format.
- **cavv** (String) - The Cardholder Authentication Verification Value, obtained from 3-D Secure authentication.
- **crypt_type** (String) - The encryption type, mandatory for AMEX cards.
- **dynamic_descriptor** (String) - Optional descriptor for the transaction.
- **ThreeDSVersion** (String) - The version of the 3-D Secure protocol used. Mandatory for financial transactions using 3rd Party 3-D Secure services.
- **ThreeDSServerTransId** (String) - The transaction ID generated by the 3-D Secure server. Mandatory for financial transactions using 3rd Party 3-D Secure services.
- **DsTransId** (String) - Optional Transaction ID from the Discover Services (DS) system.
- **Network** (String) - Set only for Interac e-commerce transactions.
- **DataType** (String) - Set only for Interac e-commerce transactions.
- **WalletIndicator** (String) - Set only for wallet transactions (e.g., Apple Pay).
- **Recur** (Object) - An object containing recurring billing details:
  - **recur_unit** (String) - The unit for recurrence (e.g., 'month', 'eom').
  - **start_now** (String) - Indicates if the recurring billing starts immediately ('true' or 'false').
  - **start_date** (String) - The start date for recurring billing (YYYY/MM/DD).
  - **num_recurs** (String) - The total number of recurring transactions.
  - **period** (String) - The billing period.
  - **recur_amount** (String) - The amount for each recurring transaction.
- **CofInfo** (Object) - Card on File information:
  - **payment_indicator** (String) - Indicates the type of payment.
  - **payment_information** (String) - Details about the payment.
  - **issuer_id** (String) - The ID of the issuer.
- **processing_country_code** (String) - The country code for processing.
- **status_check** (Boolean) - A flag to indicate if a status check is required.

### Request Example
```csharp
namespace Moneris
{
 using System;
 using System.Collections;
 
 public class TestCanadaCavvPurchase
 {
  public static void Main(string[] args)
  {
    string store_id = "store5";
    string api_token = "yesguy";
    string order_id = "Test" + DateTime.Now.ToString("yyyyMMddhhmmss");
    string cust_id = "CUS887H67";
    string amount = "10.42";
    string pan = "4242424242424242";
    string expdate = "1901"; //YYMM
    string cavv = "AAABBJg0VhI0VniQEjRWAAAAAAA=";
    string dynamic_descriptor = "123456";
    string wallet_indicator = "APP";
    string processing_country_code = "CA";
    string crypt_type = "5";
    bool status_check = false;
/************************* Recur Variables **********************************/
    string recur_unit = "month"; //eom = end of month
    string start_now = "true";
    string start_date = "2018/02/25";
    string num_recurs = "12";
    string period = "1";
    string recur_amount = "30.00";
/************************* Recur Object Option1 ******************************/
    Recur recurring_cycle = new Recur(recur_unit, start_now, start_date,
    num_recurs, period, recur_amount);
/************************* Recur Object Option2 ******************************/
    Hashtable recur_hash = new Hashtable();
    recur_hash.Add("recur_unit", recur_unit);
    recur_hash.Add("start_now", start_now);
    recur_hash.Add("start_date", start_date);
    recur_hash.Add("num_recurs", num_recurs);
    recur_hash.Add("period", period);
    recur_hash.Add("recur_amount", recur_amount);
    Recur recurring_cycle2 = new Recur(recur_hash);
    CofInfo cof = new CofInfo();
    cof.SetPaymentIndicator("R");
    cof.SetPaymentInformation("2");
    cof.SetIssuerId("168451306048014");
    CavvPurchase cavvPurchase = new CavvPurchase();
    cavvPurchase.SetOrderId(order_id);
    cavvPurchase.SetCustId(cust_id);
    cavvPurchase.SetAmount(amount);
    cavvPurchase.SetPan(pan);
    cavvPurchase.SetExpDate(expdate);
    cavvPurchase.SetCavv(cavv);
    cavvPurchase.SetCryptType(crypt_type); //Mandatory for AMEX cards only
    cavvPurchase.SetDynamicDescriptor(dynamic_descriptor);
    cavvPurchase.SetThreeDSVersion("2.2.0"); //Mandatory for financial transactions using 3rd
    Party 3-D Secure services.
    cavvPurchase.SetThreeDSServerTransId("e11d4985-8d25-40ed-99d6-c3803fe5e68f"); //Mandatory for
    financial transactions using 3rd Party 3-D Secure services - obtained from MpiCavvLookup or
    MpiThreeDSAuthentication
    //cavvPurchase.SetDsTransId("12345"); //Optional - to be used only if you are using 3rd party
    3ds service
    //cavvPurchase.SetNetwork("Interac"); //set only for Interac e-commerce
    //cavvPurchase.SetDataType("3DSecure"); //set only for Interac e-commerce
    //cavvPurchase.SetWalletIndicator(wallet_indicator); //set only wallet transactions e.g.
    APPLE PAY
    cavvPurchase.SetRecur(recurring_cycle);
    cavvPurchase.SetCofInfo(cof);
    HttpsPostRequest mpgReq = new HttpsPostRequest();
    mpgReq.SetProcCountryCode(processing_country_code);
    mpgReq.SetTestMode(true); //false for production transactions
    mpgReq.SetStoreId(store_id);
    mpgReq.SetApiToken(api_token);
    mpgReq.SetTransaction(cavvPurchase);
    mpgReq.SetStatusCheck(status_check);
  }
 }
}
```

### Response
#### Success Response (200)
- **message** (String) - A success message indicating the purchase was processed.

#### Response Example
```json
{
  "message": "Purchase successful."
}
```
```

--------------------------------

### 3-D Secure 2.2 Integration Overview

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/~/~/~/~/~/link__id=AC98C9C58C524ECF93C971E3D74FC6DB&_z=z

This section details the process of integrating with the 3-D Secure 2.2 API, including activation and transaction flows.

```APIDOC
## Activating 3-D Secure Functionality

To activate Visa Secure, MasterCard Identity Check and/or American Express SafeKey transaction functionality, contact Moneris Sales Support at 1-855-465-4980 to enroll and enable the functionality on your account.

## Transaction Flow for 3-D Secure - Browser Channel

The 3DS 2.2 API is called during customer checkout. An optional card lookup request can initiate cardholder browser fingerprinting. After fingerprinting (or as a first step), transactional information is sent to the 3DS 2.2 service for risk assessment. The flow can be "frictionless" (invisible to cardholder, resulting in authentication success with CAVV) or "challenge" (cardholder is redirected for authentication, then back to the merchant site for a server-to-server request to obtain CAVV).

### Steps 1 – 2 (Optional): Card Lookup and Fingerprinting

An optional card lookup request is performed by the merchant website, collecting device information and sending it to Moneris via the `card_lookup` request (1.1). Moneris responds with the card's supported 3DS version, an ACS URL, and 3DS Method Data for fingerprinting (2.2). The merchant browser then POSTs this data to the ACS URL (2.3).

### Steps 3 – 4 (Required): Transaction Authentication Request

The `threeDSAuthentication` request is initiated by the merchant website to validate cardholder identity. Moneris communicates with the 3DS Directory and ACS for initial risk assessment (3.2-4.2). Moneris returns a `threeDSAuthentication` response with a `TransStatus` indicating the next action:

*   **TransStatus = "Y" or "A"**: Proceed immediately to financial transaction with provided CAVV value (frictionless flow).
*   **TransStatus = "C"**: Cardholder must be presented a challenge. POST a form with a `creq` field (containing `ChallengeData`) to the `ChallengeURL`.
*   **TransStatus = "D"**: Cardholder must be presented a challenge via Decoupled Authentication.

### Steps 5 – 10 (Challenge Only): Handling Challenge Response

If a challenge is required, the merchant website POSTs an HTTP request to the `ChallengeURL` with `ChallengeData` as a `CREQ` value (5). The ACS system presents the challenge to the cardholder. The merchant website receives a `CRES` value from the ACS via HTTP POST response (6). The ACS sends results to the 3DS Directory, which forwards them to Moneris (7-8). The merchant website then sends a `cavv_lookup` request to Moneris including the `CRES` value (9). Moneris responds with the `cavv_lookup` response containing necessary ECI and CAVV values, allowing the financial transaction to proceed (10).
```

--------------------------------

### Moneris Recurring Billing Response Field Example

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/~/~/~/~/link__id=5938A27CEB4E41CF9E1551727B0589D4&_z=z

Illustrates how to retrieve the success status of a recurring billing transaction setup. The `receipt.getRecurSuccess()` method returns a boolean value indicating if the recurring billing was successfully configured.

```java
boolean recurSuccess = receipt.getRecurSuccess();
```

--------------------------------

### Setting Billing & Shipping using Hash Tables

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/link__id=A0B708AB8BE045FEB5F1B4C55FF94DF7&_z=z

Details the process of configuring billing and shipping information using hash tables, including instantiation, population, and linking to the CustInfo object.

```APIDOC
## Setting Billing & Shipping using Hash Tables

### Description
This section describes how to set billing or shipping information by using hash tables. This involves creating a hash table, populating it with customer data, and then passing it to the `CustInfo` object.

### Method
N/A (Procedural steps)

### Endpoint
N/A (Procedural steps)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### Billing & Shipping Mandatory Values (Hash Table Keys)
- **Value**: `First Name` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"first_name"`
- **Description**: Customer first name.

- **Value**: `Last Name` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"last_name"`
- **Description**: Customer last name.

- **Value**: `Company Name` (String)
- **Limits**: 50-character alphanumeric
- **Variable/Hash Table Key**: `"company_name"`
- **Description**: Customer's company name.

- **Value**: `Address` (String)
- **Limits**: 70-character alphanumeric
- **Variable/Hash Table Key**: `"address"`
- **Description**: Customer's address.

- **Value**: `City` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"city"`
- **Description**: Customer's city.

- **Value**: `Province / State` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"province"`
- **Description**: Customer's province or state.

- **Value**: `Postal / Zip Code` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"postal_code"`
- **Description**: Customer's postal or zip code.

- **Value**: `Country` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"country"`
- **Description**: Customer's country.

- **Value**: `Phone Number` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"phone"`
- **Description**: Customer's phone number.

- **Value**: `Fax Number` (String)
- **Limits**: 30-character alphanumeric
- **Variable/Hash Table Key**: `"fax"`
- **Description**: Customer's fax number.

- **Value**: `Federal Tax` (String)
- **Limits**: 10-character alphanumeric
- **Variable/Hash Table Key**: `"tax1"`
- **Description**: Federal tax amount. Amount is not used for calculating total amount.

- **Value**: `Provincial / State Tax` (String)
- **Limits**: 10-character alphanumeric
- **Variable/Hash Table Key**: `"tax2"`
- **Description**: Provincial or state tax amount. Amount is not used for calculating total amount.

- **Value**: `Country / Local / Specialty Tax` (String)
- **Limits**: 10-character alphanumeric
- **Variable/Hash Table Key**: `"tax3"`
- **Description**: County, local or specialty tax amount. Amount is not used for calculating total amount.

- **Value**: `Shipping Cost` (String)
- **Limits**: 10-character alphanumeric
- **Variable/Hash Table Key**: `"shipping_cost"`
- **Description**: Shipping cost. Amount is not used for calculating total amount.

### Procedural Steps
1. Instantiate a `CustInfo` object.
2. Instantiate a `Hashtable` object.
3. Build the `Hashtable` using `put` methods with the keys defined above.
4. Call the `CustInfo` object's `setBilling()`/`setShipping()` method, passing the populated `Hashtable`.
5. Call the transaction object's `setCustInfo()` method to save the `CustInfo` object (with billing/shipping information) to the transaction.

### Request Example
```java
// Assuming 'customer' is a CustInfo object and 'transaction' is a transaction object

Hashtable billingInfo = new Hashtable();
billingInfo.put("first_name", "John");
billingInfo.put("last_name", "Doe");
billingInfo.put("company_name", "Widget Corp");
billingInfo.put("address", "123 Main St");
billingInfo.put("city", "Anytown");
billingInfo.put("province", "ON");
billingInfo.put("postal_code", "L1L 1L1");
billingInfo.put("country", "CA");
billingInfo.put("phone", "555-123-4567");
billingInfo.put("fax", "555-987-6543");
billingInfo.put("tax1", "0.00");
billingInfo.put("tax2", "13.00");
billingInfo.put("tax3", "0.00");
billingInfo.put("shipping_cost", "10.00");

customer.setBilling(billingInfo);

transaction.setCustInfo(customer);
```

### Response
#### Success Response (200)
N/A (Procedural execution)

#### Response Example
N/A (Procedural execution)
```

--------------------------------

### Recurring Billing Setup

Source: https://developer.moneris.com/en/Documentation/NA/E-Commerce%20Solutions/Hosted%20Solutions/~/~/~/~/~/link__id=5938A27CEB4E41CF9E1551727B0589D4&_z=z

This section details the mandatory and optional parameters required to set up a recurring billing transaction. It covers defining the recurrence unit, start date, number of recurrences, period, and the recurring amount.

```APIDOC
## POST /api/recurring/setup

### Description
Sets up a new recurring billing transaction for a customer.

### Method
POST

### Endpoint
/api/recurring/setup

### Parameters
#### Request Body
- **recur_unit** (string) - Required - Unit to be used as a basis for the interval (day, week, month, or eom).
- **start_now** (boolean) - Optional - If true, a single charge is made immediately. If false, billing starts in the future.
- **start_date** (string) - Required (if start_now is false) - Date of the first future recurring billing transaction (YYYY/MM/DD format).
- **num_recurs** (integer) - Optional - The number of times the transaction must recur (1-99).
- **period** (integer) - Optional - Number of recur units that must pass between recurring billings (1-999).
- **recur_amount** (decimal) - Required - Amount of the recurring transaction (9-character decimal, 0.01-9999999.99).

### Request Example
```json
{
  "recur_unit": "month",
  "start_now": false,
  "start_date": "2024/12/01",
  "num_recurs": 12,
  "period": 1,
  "recur_amount": "19.99"
}
```

### Response
#### Success Response (200)
- **receipt.getRecurSuccess()** (boolean) - Indicates whether the recurring billing transaction has been successfully set up.
```