Skip to main content

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.

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 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: 
POST https://api.ecrypt.com/v1/terminals

{
  "registration_code": "ABC123",
  "nickname": "Front Counter - Register 1"
}
ParameterTypeRequiredDescription
registration_codestringYesThe 6-character code displayed on the terminal screen
nicknamestringYesA name for the terminal (1-20 characters). Displayed on the terminal and in the console
device_idstringNoThe 8-character device identifier printed on the back of the terminal. Required for Canadian processing
configurationobjectNoOptional configuration settings for the terminal. See fields below
Configuration object fields:
FieldTypeDescription
prompt_tipbooleanDisplays 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_amountsarray of doublesTip 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_cvvbooleanForces the customer to enter their CVV/CVC, overriding the default card verification requirement
prompt_postal_codebooleanPrompts the customer to enter their billing postal code
prompt_amount_confirmationbooleanRequires the customer to confirm the transaction amount before proceeding
prompt_signaturebooleanDisplays the signature screen on compatible terminals (Lane 5000, Lane 7000)
key_cardbooleanAllows card details to be entered manually via the keypad instead of tap, insert, or swipe
Example with configuration: 
{
  "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: 
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: 
POST https://api.ecrypt.com/v1/transactions/sale
Request: 
{
  "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: 
{
  "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:
FieldTypeDescription
idstringRequired. The terminal ID (8-64 characters), found in your ECRYPT dashboard
prompt_tipbooleanDisplays tip options at time of sale. Ignored if your account does not support tipping. Requires tip_amounts if set to true
tip_amountsarray of doublesTip amounts in dollar format. Terminals support 3 or 4 values depending on the model — extra values are ignored
prompt_cvvbooleanForces CVV/CVC entry, overriding the default card verification requirement
prompt_postal_codebooleanPrompts the customer to enter their billing postal code
prompt_amount_confirmationbooleanRequires the customer to confirm the transaction amount before proceeding
prompt_signaturebooleanDisplays the signature screen on compatible terminals (Lane 5000, Lane 7000)
key_cardbooleanAllows 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: 
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: 
POST https://api.ecrypt.com/v1/transactions/capture

{
  "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: 
POST https://api.ecrypt.com/v1/transactions/void

​
Refund a Transaction

To refund a settled transaction, issue a refund against the original transaction ID: 
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: 
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.

​
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.