> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecrypt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Terminal

ECRYPT's Cloud EMV solution allows you to accept in-person card payments through pre-certified payment terminals that are fully managed via API. Unlike traditional terminal integrations, there is no local SDK to install, no drivers to configure, and no dependency on a specific operating system or workstation. Terminals communicate directly with ECRYPT's cloud infrastructure, and your application controls the entire payment flow through standard REST API calls.

All card data is encrypted at the point of interaction using Point-to-Point Encryption (P2PE) and transmitted over TLS 1.2, keeping your environment out of PCI scope.

***

## How Card-Present Transactions Work

When a customer is ready to pay, your application sends an API request to ECRYPT to initiate a transaction on a specific terminal. ECRYPT's cloud platform "lights up" the terminal -- prompting the customer to present their card. The terminal handles all card reading, encryption, and EMV processing locally, then passes the encrypted payload back to ECRYPT for authorization. Your application receives the result in the API response.

The full flow looks like this:

1. **Initiate** -- Your server sends a `POST` request to the ECRYPT terminal API, specifying the terminal ID, transaction amount, and any additional parameters (tip, tax, etc.).
2. **Customer interaction** -- The terminal activates and prompts the customer to tap, insert, or swipe their card.
3. **Encryption** -- The terminal encrypts the card data using P2PE before it ever leaves the device.
4. **Authorization** -- ECRYPT sends the encrypted payload to the card network for authorization.
5. **Response** -- ECRYPT returns the authorization result to your application. The terminal displays the outcome to the customer.
6. **Receipt** -- Your application can trigger a digital or printed receipt based on the response.

No sensitive card data touches your servers at any point in this flow.

***

## Activating Terminals

Once a terminal arrives, it needs to be registered to your ECRYPT account before it can process transactions. See [Order Devices](/order-devices) to learn about available models and ordering your first terminal.

**Step 1: Connect the terminal**

For Ethernet devices (Lane 3000, 5000, 7000), connect the terminal to your local network using the provided cable. For the Link2500, connect to your Wi-Fi network using the terminal's on-screen setup.

Once the device successfully establishes a network connection, a 6-character alphanumeric registration code will appear on the terminal's display. This code is used to pair the device to your ECRYPT account and merchant ID (MID).

> **Note:** The registration code rotates every 3 minutes. If the code expires before you complete registration, simply use the new code displayed on the screen.

**Step 2: Register the device**

Pass the registration code along with your account details in a `POST` request to the terminal registration endpoint:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/terminals
```

```json theme={null} theme={null}
{
  "registration_code": "ABC123",
  "nickname": "Front Counter - Register 1"
}
```

| Parameter           | Type   | Required | Description                                                                                             |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `registration_code` | string | Yes      | The 6-character code displayed on the terminal screen                                                   |
| `nickname`          | string | Yes      | A name for the terminal (1-20 characters). Displayed on the terminal and in the console                 |
| `device_id`         | string | No       | The 8-character device identifier printed on the back of the terminal. Required for Canadian processing |
| `configuration`     | object | No       | Optional configuration settings for the terminal. See fields below                                      |

**Configuration object fields:**

| Field                        | Type             | Description                                                                                                                                          |
| ---------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt_tip`                 | boolean          | Displays tip options at time of sale. If your account does not support tipping, this setting is ignored. If set to `true`, `tip_amounts` is required |
| `tip_amounts`                | array of doubles | Tip amounts in dollar format (e.g., `[2.00, 5.00, 10.00]`). Terminals support 3 or 4 amounts depending on the model -- any extra values are ignored  |
| `prompt_cvv`                 | boolean          | Forces the customer to enter their CVV/CVC, overriding the default card verification requirement                                                     |
| `prompt_postal_code`         | boolean          | Prompts the customer to enter their billing postal code                                                                                              |
| `prompt_amount_confirmation` | boolean          | Requires the customer to confirm the transaction amount before proceeding                                                                            |
| `prompt_signature`           | boolean          | Displays the signature screen on compatible terminals (Lane 5000, Lane 7000)                                                                         |
| `key_card`                   | boolean          | Allows card details to be entered manually via the keypad instead of tap, insert, or swipe                                                           |

Example with configuration:

```json theme={null} theme={null}
{
  "registration_code": "ABC123",
  "nickname": "Front Counter - Register 1",
  "configuration": {
    "prompt_tip": true,
    "tip_amounts": [2.00, 5.00, 10.00, 20.00],
    "prompt_amount_confirmation": true,
    "prompt_signature": false
  }
}
```

A successful response returns a `terminal_id` that you will use to target this device in all future API requests. The terminal is now paired to your account and MID.

**Step 3: Confirm activation**

Once registered, ECRYPT establishes a persistent connection with the device. You can verify the terminal's status at any time:

```http theme={null} theme={null}
GET /v1/terminals/{terminal_id}
```

The `status` field in the response will show `online` when the terminal is connected and ready to accept transactions.

***

## Accept Card-Present Payments

Card-present transactions are initiated by calling the standard transaction endpoints -- the same ones used for card-not-present payments -- with a `terminal` object included in the `payment` field. When ECRYPT receives a request with a terminal object, it routes the sale to that device and lights it up to collect payment from the customer.

The most common card-present transaction type is a sale. To initiate one, send a `POST` request to the sale endpoint with the `terminal` object populated with your terminal's ID:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/sale
```

**Request:**

```json theme={null} theme={null}
{
  "payment": {
    "terminal": {
      "id": "{{terminal_id}}"
    }
  },
  "amount": {
    "currency": "USD",
    "value": 29.99
  }
}
```

The terminal ID is the `terminal_id` returned when you registered the device. Once the request is received, the terminal activates and prompts the customer to tap, insert, or swipe their card. The request holds open until the customer completes the interaction.

**Response:**

```json theme={null} theme={null}
{
  "transaction_id": "467810101",
  "auth_code": "123456",
  "response_code": "APPROVED",
  "response_text": "Approved",
  "latency": 1331,
  "avs": {
    "code": "",
    "text": ""
  },
  "cvv": {
    "code": "",
    "text": ""
  },
  "amount": 29.99,
  "metadata": {
    "credit_card_network": "visa",
    "credit_card_number": "4xxxxxxxxxxx1111",
    "credit_card_expires": "1229",
    "order_tax": 0,
    "order_tip": 0
  },
  "request_id": "0HNJOGLAUCVML00000026"
}
```

### Terminal Object Options

The terminal object also accepts the same configuration fields available at registration, allowing you to override terminal behavior on a per-transaction basis:

| Field                        | Type             | Description                                                                                                                     |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | string           | Required. The terminal ID (8-64 characters), found in your ECRYPT dashboard                                                     |
| `prompt_tip`                 | boolean          | Displays tip options at time of sale. Ignored if your account does not support tipping. Requires `tip_amounts` if set to `true` |
| `tip_amounts`                | array of doubles | Tip amounts in dollar format. Terminals support 3 or 4 values depending on the model -- extra values are ignored                |
| `prompt_cvv`                 | boolean          | Forces CVV/CVC entry, overriding the default card verification requirement                                                      |
| `prompt_postal_code`         | boolean          | Prompts the customer to enter their billing postal code                                                                         |
| `prompt_amount_confirmation` | boolean          | Requires the customer to confirm the transaction amount before proceeding                                                       |
| `prompt_signature`           | boolean          | Displays the signature screen on compatible terminals (Lane 5000, Lane 7000)                                                    |
| `key_card`                   | boolean          | Allows card details to be entered manually via the keypad                                                                       |

### Authorization Hold (Pre-Auth)

To place an authorization hold without capturing immediately -- common for restaurants or hotels -- use the authorize endpoint with the terminal object populated the same way:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/authorize
```

The response returns a `transaction_id`. When you are ready to capture, pass that `transaction_id` along with a final amount that is equal to or less than the originally authorized amount:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/capture
```

```json theme={null} theme={null}
{
  "transaction_id": "{{transaction_id}}",
  "amount": 29.99
}
```

***

## Manage Transactions

Once a card-present transaction has been created, all follow-up operations use the standard transaction endpoints with the `transaction_id` returned in the sale response. There is nothing terminal-specific about these calls.

### Void a Transaction

A transaction can be voided before the batch is settled:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/void
```

### Refund a Transaction

To refund a settled transaction, issue a refund against the original transaction ID:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/refund
```

Partial refunds are supported by specifying an amount less than the original transaction amount.

### Capture a Transaction

To capture a previously authorized transaction:

```http theme={null} theme={null}
POST https://api.ecrypt.com/v1/transactions/capture
```

See the \[Transactions guide] for full request parameters and response details for each of these endpoints.

***

## Managing Devices

You can manage your terminal devices programmatically through the API. The Terminals endpoints allow you to list all registered devices, register new terminals using their registration code, retrieve details for a specific device, and remove devices from your account. For full endpoint details, parameters, and response schemas, see the [Terminals API Reference](/reference/get_v1-terminals).

***

## Testing

ECRYPT provides two ways to test your terminal integration without processing live transactions: a physical test terminal provisioned by ECRYPT, or a Virtual Payment Terminal (VPT) that simulates the full card-present flow without any hardware.

Rather than using specific test card numbers, terminal test responses are triggered by the transaction amount. For example, charging less than \$1.00 will trigger a decline. See the \[Testing guide] for the full list of amount-based triggers and expected responses.

All test transactions are isolated from your live data and do not trigger payouts or settlements.