# Cancel Customer Subscription Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/cancel-customer-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json delete /v1/customers/{Customer}/subscriptions/{Subscription} Cancel a customer subscription # Create Customer Subscription Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/create-customer-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/customers/{Customer}/subscriptions Create a customer subscription for a customer. # Get Customer Subscription Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/get-customer-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers/{Customer}/subscriptions/{Subscription} Pull a Customer Subscription by customer id and customer subscription id # List Customer Subscriptions Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/list-customer-subscriptions https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers/{Customer}/subscriptions /// Get the customer and a list of subscriptions. The default sort order is `created date descending`. # Modify Customer Subscriptions Price Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/modify-customer-subscriptions-price https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json put /v1/customers/{Customer}/subscriptions/{Subscription} Update a customer subscription to pause it. # Resume Customer Subscriptions Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/resume-customer-subscriptions https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json put /v1/customers/{Customer}/subscriptions/{Subscription}/resume Update a customer subscription to pause it. # Suspend Customer Subscription Source: https://docs.ecrypt.com/api-reference/gateway/customers-subscription/suspend-customer-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json put /v1/customers/{Customer}/subscriptions/{Subscription}/suspend Updates a customer subscription to pause it. # Create Customer Wallet Payment Method Source: https://docs.ecrypt.com/api-reference/gateway/customers-wallet/create-customer-wallet-payment-method https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/customers/{Customer}/wallet # Delete Customer Wallet Payment Method Source: https://docs.ecrypt.com/api-reference/gateway/customers-wallet/delete-customer-wallet-payment-method https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json delete /v1/customers/{Customer}/wallet/{Wallet} # Get Customer Wallet Payment Method Source: https://docs.ecrypt.com/api-reference/gateway/customers-wallet/get-customer-wallet-payment-method https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers/{Customer}/wallet/{Wallet} # List Customer Wallet Source: https://docs.ecrypt.com/api-reference/gateway/customers-wallet/list-customer-wallet https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers/{Customer}/wallet # Update Customers default payment method Source: https://docs.ecrypt.com/api-reference/gateway/customers-wallet/update-customers-default-payment-method https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json put /v1/customers/{Customer}/wallet/{Wallet} # Create Customer Source: https://docs.ecrypt.com/api-reference/gateway/customers/create-customer https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/customers Create a new customer in your vault. # Delete Customer Source: https://docs.ecrypt.com/api-reference/gateway/customers/delete-customer https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json delete /v1/customers/{Customer} Delete the customer from your customer vault. # Get Customer Source: https://docs.ecrypt.com/api-reference/gateway/customers/get-customer https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers/{Customer} Get the specified customer. # List Customers Source: https://docs.ecrypt.com/api-reference/gateway/customers/list-customers https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/customers Returns a list of `ACTIVE` customers from your vault. The default sort order is `CREATED DATE DESCENDING`. # Create Dynamic Checkout Source: https://docs.ecrypt.com/api-reference/gateway/dynamic-checkout/create-dynamic-checkout https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/dynamiccheckout # Create Subscription Source: https://docs.ecrypt.com/api-reference/gateway/subscriptions/create-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/subscriptions Create a new merchant subscription template. # Delete Subscription Plan Source: https://docs.ecrypt.com/api-reference/gateway/subscriptions/delete-subscription-plan https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json delete /v1/subscriptions/{Subscription} Delete the subscription plan. All customer subscriptions associated with this subscription plan must be canceled before you can delete the plan. # Get Subscription Source: https://docs.ecrypt.com/api-reference/gateway/subscriptions/get-subscription https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/subscriptions/{Subscription} Get the specified subscription. # List Subscriptions Source: https://docs.ecrypt.com/api-reference/gateway/subscriptions/list-subscriptions https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/subscriptions Get a list of `ACTIVE` subscription plans. The default sort order is `CREATED DATE DESCENDING`. # Create Source: https://docs.ecrypt.com/api-reference/gateway/terminals/create https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/terminals Create a new terminal. Sample request: POST v1/terminals/ { "nickname":"NICKNAME", "registration_code":"******" } # Delete Source: https://docs.ecrypt.com/api-reference/gateway/terminals/delete https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json delete /v1/terminals/{Terminal} Delete the specified terminal. # Get Source: https://docs.ecrypt.com/api-reference/gateway/terminals/get https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/terminals/{Terminal} Get the specified terminal. # List Source: https://docs.ecrypt.com/api-reference/gateway/terminals/list https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/terminals Get a list of terminals. # Create Token Source: https://docs.ecrypt.com/api-reference/gateway/tokens/create-token https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/tokens Payment Tokens support credit card's and ACH bank account information. Tokens, can be for one time use, or stored and saved to a customers profile. # Authorize Source: https://docs.ecrypt.com/api-reference/gateway/transactions/authorize https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/authorize Authorization only endpoint. Merchants will need to ensure they capture the transaction. ***Supported Payment Methods*** - `Credit Card` - `Terminal/Cloud EMV` - `Check/ACH` - `Customer` - `Wallet` # Capture Source: https://docs.ecrypt.com/api-reference/gateway/transactions/capture https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/capture `CAPTURE` a previous 'AUTHORIZTION'. Capture for up to the amount authorized. Specific merchants with tip at time of sale or tip adjust enabled can capture over the authorization amount. # Credit Source: https://docs.ecrypt.com/api-reference/gateway/transactions/credit https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/credit Credit or blind credit will return the specified amount to the payment method. This service must be enabled on your merchant account. ***Supported Payment Methods*** - `Credit Card` - `Terminal/Cloud EMV` - `Check/ACH` - `Customer` - `Wallet` # Get a Transaction Source: https://docs.ecrypt.com/api-reference/gateway/transactions/get-a-transaction https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/transactions/{id} # List Transactions Source: https://docs.ecrypt.com/api-reference/gateway/transactions/list-transactions https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json get /v1/transactions Get a list of transactions. The default sort order is `CREATED DATE DESCENDING`. # Refund Source: https://docs.ecrypt.com/api-reference/gateway/transactions/refund https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/refund `REFUND` a settled transaction. Refund amount cannot exceed settled amount. # Sale Source: https://docs.ecrypt.com/api-reference/gateway/transactions/sale https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/sale Sale combines 'AUTHORIZATION' and 'CAPTURE' into a single endpoint. ***Supported Payment Methods*** - `Credit Card` - `Terminal/Cloud EMV` - `Check/ACH` - `Customer` - `Wallet` # Validate Source: https://docs.ecrypt.com/api-reference/gateway/transactions/validate https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/validate Validate that a payment method is valid and supported. ***Supported Payment Methods*** - `Credit Card` - `Terminal/Cloud EMV` - `Check/ACH` - `Customer` - `Wallet` # Void Source: https://docs.ecrypt.com/api-reference/gateway/transactions/void https://cdn.ecrypt.dev/swagger/gateway-swagger-v31.json post /v1/transactions/void `VOID` an unsettled transaction. # Get Batch Source: https://docs.ecrypt.com/api-reference/reporting/batch-detail/get-batch https://cdn.ecrypt.dev/swagger/reporting-v6-swagger.json post /api/BatchDetail Get Batch with paginated transactions. # List Batches Source: https://docs.ecrypt.com/api-reference/reporting/batch/list-batches https://cdn.ecrypt.dev/swagger/reporting-v6-swagger.json post /api/Batch List Batches using the specified filter. # Get Transaction Source: https://docs.ecrypt.com/api-reference/reporting/transactions/get-transaction https://cdn.ecrypt.dev/swagger/reporting-v6-swagger.json get /api/Transactions/{TransactionID} Get the specified transaction based on the provided TransactionID. # List Transactions Source: https://docs.ecrypt.com/api-reference/reporting/transactions/list-transactions https://cdn.ecrypt.dev/swagger/reporting-v6-swagger.json post /api/Transactions Get the paginated list of transactions using the provided filter criteria. # Adobe Commerce (Magento) Source: https://docs.ecrypt.com/dashboard/adobe-commerce Accept credit and debit card payments in your Adobe Commerce store with the ECRYPT module. ECRYPT's Adobe Commerce module lets you accept credit and debit card payments directly in your store. It supports online payments, native refunds, and a secure vault for storing cards on file. Available on the Adobe Commerce Marketplace. ## Requirements | Requirement | Details | | ----------------------- | -------------------------------------------------------- | | ECRYPT account | Sandbox account for testing, live account for production | | Active merchant account | Required to process real transactions | ## Installation 1. Place your order for the ECRYPT module on the Adobe Commerce Marketplace. 2. Open a terminal in your Adobe Commerce directory and install the module: ```bash theme={null} composer require ecrypt/payment-gateway ``` 3. Run the setup commands: ```bash theme={null} php bin/magento setup:upgrade php bin/magento cache:flush php bin/magento cache:clean ``` 4. If your store runs in production mode, also run: ```bash theme={null} php bin/magento setup:di:compile php bin/magento setup:static-content:deploy ``` ## Configuration 1. In the admin panel, go to **Store > Configuration > Sales > Payment Methods > Other Methods > ECRYPT**. 2. In your ECRYPT dashboard, go to **Settings > Developer Tools > API/Security Keys** and copy your private and public keys. 3. Paste both keys into the ECRYPT payment method configuration panel and save. ## Testing To test your integration before going live, use your ECRYPT sandbox API keys in the configuration panel. If you do not have sandbox credentials, contact support. See the [Testing](/testing) page for a full list of test card numbers and expected responses. ## Features **Card vault.** Customers can save their payment method at checkout for future purchases. To enable this, turn on the **Card Saving (Vault)** option in the ECRYPT configuration panel. You can manage and delete stored payment methods under **Stored Payment Methods**. **Native refunds.** Refunds are handled directly in Adobe Commerce. Go to **Sales > Invoices**, select the invoice, and issue a refund. ## Limitations Multishipping is not currently supported with the ECRYPT module. # Allow IP (Authorize IP) Source: https://docs.ecrypt.com/dashboard/allow-ip The **Authorized IP** page lets a merchant restrict access to their Ecrypt account by IP address. When enabled, only requests originating from IPs on the allowlist can reach the dashboard and/or the API — every other source is blocked. This is one of the strongest controls Ecrypt offers, because it removes most of the attack surface entirely: a stolen password, a leaked API key, or a card-testing bot operating from any random internet IP simply cannot reach the gateway if that IP isn't on the list. **Path:** Settings → Fraud Prevention → IP Allowed > **What is IP allowlisting?**
An allowlist (sometimes called a whitelist) is the opposite of a blocklist: instead of listing the IPs you want to deny, you list the IPs you want to permit. Anything not on the list is denied by default. This default-deny posture is significantly more secure than trying to enumerate every bad actor in the world. *** ## Page Layout ### Header * **Title:** Authorized IP * **Description:** "Here, you can manage the list of authorized IP addresses for your account. By adding specific IP addresses to this list, you can control access to your resources and services, ensuring only trusted IPs can interact with your applications." ### Master Toggle * **Enable Authorized IP** — a single switch that turns enforcement on or off for the active MID. * Help text under the toggle: "Once Enabled, All requests originating from the IP addresses listed in the 'IP's Authorized Table' filter will be granted access to your services and resources. The rest will be **BLOCKED**." > The toggle is the kill switch. While it's off, the allowlist is informational only. The moment it's on, every request from an IP not on the list is rejected — including yours, if you forgot to add it. ### Add a New IP Address (Form) | Field | Type | Description | | ------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Label** | Text | A human-readable name for the entry (e.g., "Main Office", "Retail POS Subnet", "Production API Server"). | | **IP Address** | Text | The IPv4 address to authorize. The label above the field shows your current source IP as a hint (e.g., `Your IP: 172.30.50.167`) so you can quickly add yourself. | | **ALLOWED TO USE THE PLATFORM** | Checkbox | Permits this IP to access the Ecrypt dashboard (web UI / login). | | **ALLOWED TO USE THE API** | Checkpoint | Permits this IP to make REST API calls against the gateway. | | **ADD IP ADDRESS** | Button | Saves the entry to the IP's Authorized Table. | You can grant **platform**, **API**, or **both** for each entry. A dashboard-only entry is appropriate for back-office staff browsing reports; an API-only entry is appropriate for a production server that submits payments programmatically. ### IP's Authorized Table The list of currently configured entries: | Column | Description | | -------------- | -------------------------------------------------- | | **IP Address** | The IP authorized. | | **Label** | The human-readable name set when adding. | | **Status** | Which scopes are granted (Platform, API, or both). | | **Action** | Per-row controls to edit or delete the entry. | If no entries exist, the table shows **No results found**. *** ## Configuring the Allowlist ### Recommended order of operations The safest way to turn this on for the first time is to **add yourself first, then enable the toggle, then expand the list**. If you enable enforcement before you're on the list, you'll lock yourself out and need your account representative to restore access. 1. Go to Settings → Fraud Prevention → IP Allowed. 2. Confirm your current IP from the `Your IP:` hint above the IP Address field. 3. Add an entry for yourself with **ALLOWED TO USE THE PLATFORM** checked. 4. Add entries for every other user, office, server, and integration that needs access: * Office locations (use the office's public WAN IP, not internal LAN IPs). * Each ecommerce / production server that calls the API — check **ALLOWED TO USE THE API**. * Static-IP VPN gateways used by remote staff. 5. Once the list is complete and verified, flip **Enable Authorized IP** to ON. ### Adding an entry 1. Type a clear **Label** (you'll thank yourself later when reviewing the list months from now). 2. Type the IPv4 address to permit. 3. Check **ALLOWED TO USE THE PLATFORM** and/or **ALLOWED TO USE THE API** based on intended use. 4. Click **ADD IP ADDRESS**. The entry appears in the IP's Authorized Table. ### Editing or removing an entry Use the per-row **Action** controls in the IP's Authorized Table to edit a label / scopes, or delete an entry that's no longer needed (decommissioned server, former office, departed contractor). *** ## How It Works With the Rest of Ecrypt * **Platform vs. API scopes are independent.** An entry with only "API" checked will be blocked from logging into the dashboard from that IP, and vice versa. * **Scope is per MID.** If you operate multiple MIDs, you must configure the allowlist on each one. Use the location switcher (top-left) to switch MIDs and configure each independently. * **API keys still apply.** IP allowlisting layers on top of API key authentication — even if a private key is leaked, the attacker also needs to be on the allowlist. * **Pairs naturally with the Velocity Filter.** Allowlisting prevents most unauthorized traffic from reaching the gateway at all; the velocity filter contains anything that slips through (or originates from an authorized source). *** ## Use Cases * **Single-location retail.** Allow only the office WAN IP. Card-testing bots running anywhere in the world are blocked outright. * **Ecommerce with a known production stack.** Allow your production server IPs for API access; allow internal staff IPs for platform access. Disable everything else. * **Mixed B2B / call-center.** Allow your office IPs for the dashboard and your billing-server IP for the API. Field staff who need mobile access either go without (and use a kiosk/iPad on a static-IP network) or VPN in through an allowlisted gateway. * **Tightening after a security incident.** If you suspect credential or API-key compromise, turning on IP allowlisting immediately blunts the attacker's access while you investigate and rotate keys. *** ## Tips & Best Practices * **Always add yourself first.** The dashboard does not have a "do you really want to lock yourself out?" confirmation — be careful with the master toggle. * **Use labels generously.** "Marketing laptop - Sarah" is much more useful than just `73.221.x.x` six months from now. * **Use static public IPs.** Allowlisting against dynamic residential IPs is fragile — the entry can stop working overnight when the ISP rotates the address. For remote workers, a static-IP VPN or a fixed-IP business internet line is the right pattern. * **Avoid allowing entire ISPs or large subnets.** The narrower the allowlist, the better the protection. Allow individual server IPs rather than `/16` blocks unless you specifically need them. * **Review the list quarterly.** Remove entries for retired servers, closed offices, and former employees. Stale allowlist entries become attack surface. * **Keep API-only entries separate from platform entries.** A web server should not need dashboard access; an analyst should not need API access. Granting the minimum required scope per entry follows the principle of least privilege. * **Document your allowlist outside Ecrypt.** Keep a record (in your IT documentation or password manager) of which entries correspond to which systems, so a new admin can audit the list without guesswork. * **If you get locked out**, contact your Ecrypt account representative — they can disable enforcement so you can recover, but they cannot remotely add an IP for you to bypass the lock. * **Combine with reCAPTCHA, velocity filtering, and proper API key hygiene.** Defense in depth: IP allowlisting prevents most attacks from ever starting, while the other controls handle the rest. # API Keys Source: https://docs.ecrypt.com/dashboard/api-keys ## Overview API keys are the credentials that allow external software to communicate securely with your ECRYPT account. Any time a third-party application or custom integration needs to send payment requests, retrieve transaction data, or interact with your account programmatically, it authenticates using an API key you generate here. Navigate to **Settings → Developer Tools → API/Security Keys** to manage your keys. ## When You Need an API Key You need an API key whenever you are connecting ECRYPT to another system. Common examples include: * **E-commerce platforms** such as WooCommerce, Magento, or other shopping cart software that need to process payments through ECRYPT * **Custom-built integrations** where your development team is building a direct connection to the ECRYPT API * **Third-party tools** that pull transaction or reporting data from your account You can create as many API keys as you need. A good practice is to create a separate key for each integration or application — this way, if one key ever needs to be revoked, the rest of your integrations are unaffected. ## Key Types ECRYPT offers three types of API keys, each with a different level of access: | Key Type | What It Does | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Public Key** | Used on the client side (e.g., in a checkout form or front-end application) to initiate payment requests. Safe to expose in browser-facing code. | | **Private Key** | Used on the server side for sensitive operations. Should never be exposed in client-side code or shared publicly. | | **Reporting Key** | Provides read-only access to transaction and reporting data. Use this when an integration only needs to pull reports without the ability to process payments. | ## Creating a Key 1. Navigate to **Settings → Developer Tools → API/Security Keys** 2. Enter a **Description** to identify what the key is for (e.g., "WooCommerce Production" or "Custom Checkout") 3. Select the **Key Type** — Private Key, Reporting Key, or Public Key 4. Click **Generate New Key** The key appears in the **Key's Table** below. Use the copy icon next to any key to copy it to your clipboard. To remove a key, click **Delete** next to it. ## Custom Integrations If you are building a custom integration using the ECRYPT API, visit the [Developer Guides Quickstart](/guides-quickstart) for full documentation on getting started, authentication, environments, and available endpoints. # Customer Vault Source: https://docs.ecrypt.com/dashboard/customer-vault ## Overview The Customer Vault is Ecrypt's secure, centralized database of saved customer profiles and payment methods. Think of it as a digital Rolodex of your customers — each record stores a customer's contact information, one or more saved payment methods (credit card or ACH bank account), billing/shipping addresses, and a full transaction history. Storing customers in the vault lets you: * Run future charges without re-entering card details * Create subscriptions linked to a saved profile * Send invoices that customers can pay with a stored method * Track all transactions associated with a specific customer in one place *** ## Navigating to the Customer Vault From the left sidebar, under **APPS**, click **Customer Vault**. *** ## The Customer List (List View) By default the Customer Vault opens in **List View**, showing a paginated table of all customers. ### Table Columns | Column | Description | | ------------------------ | ---------------------------------------------------------------------------------- | | **Ecrypt Public ID** | A system-generated UUID that uniquely identifies the customer in Ecrypt's platform | | **First Name** | Customer's first name | | **Last Name** | Customer's last name | | **Phone** | Customer's phone number (shows "N/A" if not provided) | | **Email** | Customer's email address | | **Account Data** | Masked primary payment method (e.g., `411111******1111 VISA`) | | **Merchant Customer ID** | Your internal customer identifier (set when the customer was created) | ### Sorting Click any column header to sort the list by that column. Click again to reverse the sort order. ### Pagination Use the **Rows per page** dropdown (bottom right) to show 10, 25, or 50 customers per page. Use the arrow buttons to navigate between pages. *** ## Grid View Click **Grid View** (top right) to switch to a card-based layout. Each card shows the Customer ID badge, full name, email, phone, and primary payment method. Click **List View** to switch back. *** ## Credit Card Filters At the top right you'll find three tabs: | Filter | What it shows | | ----------------- | ------------------------------------------------------------ | | **All** | All customers regardless of card status | | **Expiring Soon** | Customers whose primary card expires within the next 30 days | | **Expired** | Customers whose primary card has already expired | These are useful for proactive outreach before subscription or recurring payments fail. *** ## Filtering Customers Click **Filters** to open the filter panel. You can filter by: * **Ecrypt Public ID** — exact match on the system UUID * **First Name** * **Last Name** * **Phone** * **Email** * **Account Data** — partial match on the masked card number * **Merchant Customer ID** — your internal ID * **Date Created** — date range the customer was added to the vault For each filter, select a **Filter Type** (equals, contains, starts with, etc.) and enter a **Value**. Click **+ Add Filter** to stack multiple filters, **Apply Filters** to run the search, or **Clear Filters** to reset. *** ## Adding a New Customer Click **Add Customer** in the left sidebar under **ACTIONS** from any page. ### The "Add to Customer Vault" Form **Personal Information** | Field | Required | Notes | | ------------ | ----------- | ------------------------------ | | Full Name | Yes | Customer's full name | | Company Name | No | Optional business name | | Email | Recommended | Used for receipts and invoices | | Phone Number | No | Customer's phone number | **Customer Wallet** — select Credit Card or ACH: *Credit Card* | Field | Required | Notes | | ------------------ | -------- | ------------------------------------------------ | | Name On Card | Yes | Exactly as it appears on the card | | Credit Card Number | Yes | Full card number — stored securely and tokenized | | Expiration Date | Yes | MM/YY format | | Street Address | No | Billing address for AVS verification | | City / State / Zip | No | | *ACH (Bank Account)* | Field | Required | Notes | | ----------------------------------- | -------- | -------------------------- | | Name On Account | Yes | Account holder name | | Account Number | Yes | Bank account number | | Routing Number | Yes | 9-digit ABA routing number | | Street Address / City / State / Zip | No | | The **"My billing address is the same as my shipping address"** checkbox is pre-checked. Uncheck it to enter a separate shipping address. **Extra Info** | Field | Notes | | -------------- | ---------------------------------------------------------------------------- | | Customer ID | Your internal customer identifier (e.g., from your CRM or e-commerce system) | | Customer Notes | Free-text field for any additional context or instructions | Click **ADD CUSTOMER** to save. The customer will immediately appear in the vault list. *** ## Viewing a Customer Profile Click any row (or card in Grid View) to open the customer's profile panel. ### Profile Header * Full name and **Customer ID** badge * Phone, email, and company name * **Ecrypt Public ID** (the system UUID) ### Action Buttons | Button | What it does | | ----------------- | --------------------------------------------------------------- | | **+ Actions** | Dropdown: **New Transaction**, **New Subscription**, **Delete** | | **Add To Wallet** | Adds a new payment method to this customer | | **Edit Customer** | Opens the customer edit form | ### Customer Wallet Displays all saved payment methods as card tiles. Each tile shows: * Cardholder name and masked card number * Expiration date and card brand logo (Visa, Mastercard, Discover, etc.) * **DEFAULT** badge on the primary payment method * **EXPIRED** or **EXPIRING SOON** badge when applicable * An **UPDATE** button to modify or remove the method ### Billing & Shipping Address The customer's saved billing address and default shipping address (if different from billing). ### Customer Notes Free-text notes associated with the customer record. ### Customer Transaction History A full table of all transactions linked to this customer — ID, Date, Amount, Type, Account Data, and Status. Click any row to open the full transaction detail. *** ## Editing a Customer From the customer profile, click **Edit Customer**. **Editable fields:** * Full Name, Company Name, Email, Phone Number * Shipping Address (Street, City, State, Zip) * Merchant Customer ID * Customer Notes Click **CONFIRM** to save, or **GO BACK** to cancel. *** ## Managing Payment Methods ### Adding a New Payment Method Click **Add To Wallet** from the customer profile. Select **Credit Card** or **ACH**, fill in the payment details, check **Make Default** if this should be the primary method, and click **CONFIRM**. ### Updating an Existing Payment Method Click **UPDATE** on any card tile. The form pre-fills with the current card's details. Update the expiration date, name, or billing address as needed, then click **CONFIRM**. ### Deleting a Payment Method From the card UPDATE form, click **DELETE WALLET** (shown in red) to permanently remove that payment method. > **Note:** Deleting a payment method cannot be undone. If this is the customer's only saved method, their wallet will be empty afterward. *** ## Running a Transaction for a Customer From the customer profile, click **+ Actions → New Transaction**. A payment form opens pre-filled with the customer's saved payment method, so you can charge them without re-entering card details. *** ## Creating a Subscription for a Customer From the customer profile, click **+ Actions → New Subscription**. The subscription creation flow launches with this customer pre-selected. *** ## Deleting a Customer From the customer profile, click **+ Actions → Delete**. > **Warning:** Deleting a customer permanently removes their profile and payment methods from the vault. Historical transaction records are retained in Reporting. This action cannot be undone. *** ## Tips & Best Practices * **Always enter an email address** — it enables invoice delivery and payment receipts. * **Use Merchant Customer ID** to link Ecrypt records to your own system (CRM, e-commerce platform, etc.). * **Monitor "Expiring Soon"** regularly — proactively contact customers to update cards before subscriptions or recurring charges fail. * **Add Customer Notes** for billing instructions, account flags, or any team-facing context. * **Set a Default payment method** when a customer has multiple cards on file, to ensure the correct card is charged for new transactions and subscriptions. # Hosted Payments Source: https://docs.ecrypt.com/dashboard/hosted-payments ## Overview Hosted Payments gives you everything you need to accept payments online without building your own checkout page. ECRYPT hosts the payment experience for you — you configure it, brand it to match your business, and share it with customers as a button on your website or a payment link they can open from any device. The Hosted Payments section lives in the left sidebar under **Hosted Payments** and contains four areas: **Create Button**, **Buy Now**, **Appearance**, and **URL Details**. ## Create Button **Create Button** is where you build a new Buy Now button or payment link. Navigate to **Hosted Payments → Create Button** to open the form. ### Pricing | Field | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | Price Entry Method | **Set fixed price** charges a set amount. **Allow buyer to input price** lets the customer enter the amount | | Amount | The fixed price for the payment | | Tax (Exclusive) | An optional tax percentage added on top of the amount | | Surcharge Type | How the surcharge is calculated (Percentage) | | Surcharge | The surcharge rate to apply (up to 3.00%) | ### Settings | Field | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Invoice Number | Check **Allow customer to enter invoice number** to let the customer provide a reference number at checkout | | Payment Methods | Choose **Allow Credit Card** and/or **Allow ACH** | | Expiration | **Never** keeps the link active indefinitely. **One time payment** deactivates the link after the first successful payment. **At specific date/time** sets a hard expiry date | | Expiration Date | The date the link stops accepting payments (when using At specific date/time) | ### Design Customize how the Buy Now button looks on your website. A live **Preview** updates as you make changes. | Field | Description | | ----------------- | ------------------------------------------------- | | Button Text | The label on the button (default: "Buy Now") | | Font Size | Button text size in pixels | | Button Text Color | Hex color for the button label | | Google Font | Choose a Google Font for the button text | | Background Color | The button fill color | | Border Radius | Rounds the button corners (in pixels) | | Border Color | The color of the button border | | Font Type | Text style (Normal, Italic, etc.) | | Font Weight | Text weight (e.g., 400 for regular, 700 for bold) | Click **Generate Button** to create the button and payment link — it will appear in your **Buy Now** list. Click **Cancel** to discard. ## Buy Now **Buy Now** is your library of all the buttons and payment links you have created. Navigate to **Hosted Payments → Buy Now** to see the full list. Each row shows the **Date Created** and the **Amount** for that button. The **Action** column gives you four options: | Icon | Action | | ------------- | ----------------------------------------------------------- | | Eye | Preview the hosted checkout page as a customer would see it | | Code brackets | Get the embed code to place the button on your website | | Link | Copy the direct payment link URL to share with customers | | Trash | Delete the button and payment link permanently | Use **Filters** to search or narrow the list, and **Clear Filters** to reset. The **Rows per page** dropdown and page arrows let you navigate through larger lists. ## Appearance **Appearance** controls how your hosted checkout page looks to customers. Changes here apply to all of your Buy Now buttons and payment links. Navigate to **Hosted Payments → Appearance**. The page has three content tabs — **Invoice**, **Form**, and **Mobile** — each with its own color settings. A live preview on the right updates as you make changes, with **Desktop**, **Tablet**, and **Mobile** preview tabs. ### Invoice tab Controls the invoice/order summary panel on the left side of the checkout page. | Setting | Description | | ------------------------------- | --------------------------------------- | | Invoice Background Color | Background of the invoice panel | | Invoice Text Color | Body text color | | Invoice Accent Color | Hyperlinks and highlighted elements | | Invoice Border Color | Divider and border lines | | Invoice Button Background Color | Action button color on the invoice side | | Invoice Button Text Color | Text color on the invoice button | | Invoice Icon Theme | Icon style: Dark or Light | ### Form tab Controls the payment form on the right side of the checkout page where customers enter their card details. | Setting | Description | | ---------------------------- | ---------------------------------- | | Form Background Color | Payment form background | | Form Text Color | Body text in the form | | Form Title Color | Section heading color | | Form Accent Color | Active states and checked elements | | Form Border Color | Input field borders | | Form Button Background Color | Submit/Continue button background | | Form Button Text Color | Submit/Continue button text | | Form Input Text Color | Text inside input fields | | Form Label Color | Field label text | | Form Input Background Color | Input field background | | Alert Color | Error and alert message color | ### Mobile tab Controls the checkout appearance on mobile devices, where the layout shifts to a single-column card view. The same types of color settings apply, optimized for mobile screens. Click **Save** at the bottom of the preview panel to apply all changes across all three tabs. Each color field also has a reset icon to revert that individual setting to its default. ## URL Details **URL Details** sets two global URLs that apply to every hosted checkout and payment link on your account. Navigate to **Hosted Payments → URL Details**. | Field | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Finish URL | The page customers are redirected to after a successful payment — typically a Thank You or order confirmation page on your website | | Terms And Conditions URL | A link to your terms and conditions or refund policy, shown on the checkout form so customers can review it before paying | Click **Save** to apply the changes. ## Tips and Best Practices **Set your URL Details first.** Before sharing any payment links, configure your Finish URL and Terms and Conditions URL so every checkout ends cleanly and professionally. **Brand before you share.** Set up your Appearance to match your business before generating buttons. A consistent, branded checkout builds trust with customers. **Use One time payment for single-use links.** Set Expiration to One time payment when sending a specific payment request — the link deactivates after the first successful payment and cannot be reused. **Use Allow buyer to input price for flexible amounts.** Ideal for donations, deposits, or any situation where the amount varies by customer. **Embed vs. link.** Use the embed code (code brackets icon) to add a Buy Now button on your website. Use the link icon to copy a URL you can paste into an email, text, or social media post. **Keep your Buy Now list tidy.** Delete buttons and links you are no longer using to prevent confusion if old links are found or shared. # Invoicing Source: https://docs.ecrypt.com/dashboard/invoicing ## Overview The Invoices module lets you generate branded payment requests and send them directly to customers via a hosted payment link. Unlike a standard credit card charge, an invoice gives the customer a professional document with itemized line items, a pricing summary, and a self-service "Pay Now" page they can open from any device. Key capabilities: * Create invoices tied to existing Customer Vault records * Add one-time line items or pull from a saved product catalog * Choose between **requesting payment** (the customer pays on their own) or **charging the customer directly** from a saved card * Track invoice status in real time (Paid, Pending, Past Due, Overdue, Canceled) * Customize the look of the invoice and payment form to match your brand * Set a post-payment redirect URL and a Terms & Conditions link *** ## Navigation Invoices lives in the left sidebar under **APPS → Invoices**, which expands to four sub-sections: | Sub-section | Path | Purpose | | ------------------ | ------------------------------------------------- | ------------------------------------- | | **Dashboard** | `/invoices/dashboard` | View and manage all invoices | | **Create Invoice** | `/invoices/create-invoice` | Build and send a new invoice | | **Branding** | `/invoices/branding` | Customize invoice and form appearance | | **URL Details** | `/invoices/dashboard?actions=url-details-invoice` | Set redirect and T\&C URLs | *** ## Invoices Dashboard The Dashboard is the main invoice list. It opens automatically when you click **Invoices** in the sidebar. ### Status Filter Tabs Six tabs across the top filter the list by invoice status: | Tab | Description | | ------------ | ---------------------------------------------------------------------- | | **All** | Every invoice regardless of status | | **Paid** | Invoices with full payment received | | **Past due** | Invoices where the due date has passed with no payment | | **Overdue** | Invoices flagged as overdue (may differ from past due by system logic) | | **Pending** | Invoices sent but not yet paid | | **Canceled** | Voided / canceled invoices | ### Invoice List Columns | Column | Description | | ---------------------- | ---------------------------------------------------------------------- | | **Issued Date** | Date the invoice was created | | **Due Date** | Payment deadline set on the invoice | | **Status** | Color-coded badge: green = Paid, gold/amber = Past due, red = Canceled | | **Total Amount** | Full invoice value (line items + tax + surcharge) | | **Paid Amount** | Amount collected so far | | **Outstanding Amount** | Remaining balance due | | **Customer** | Customer name from the vault | Pagination controls at the bottom-right let you change **Rows per page** (dropdown) and page through results with **‹** / **›** arrows. The list shows "X–Y of Z" total records. ### CREATE INVOICE Button The blue **CREATE INVOICE** button in the top-right corner of the dashboard navigates directly to the Create Invoice form. ### Filter Panel Click the **FILTERS** toggle to expand a filter bar above the invoice table. Click **CLEAR FILTERS** to reset. **Filter By** options (dropdown): | Filter Field | Type | | ------------------ | ----------------------- | | Issued Date | Date range / comparison | | Due Date | Date range / comparison | | Status | Value match | | Total Amount | Numeric comparison | | Paid Amount | Numeric comparison | | Outstanding Amount | Numeric comparison | | Customer | Text search | **Filter Type** options adjust the comparison operator (equals, greater than, contains, etc.) based on the chosen field. After setting Field + Type + Value, click **+ ADD FILTER** to stack multiple conditions, then **APPLY FILTERS** to execute. *** ## Viewing an Invoice (Invoice Information Panel) Clicking any row opens the **Invoice Information** side panel (the list dims in the background). ### Panel Header | Element | Description | | -------------------- | ------------------------------------------------------------------------------------------ | | **Status badge** | Color-coded pill: PAID (green), PAST DUE (amber), CANCELED (red), etc. | | **Timestamp** | Date and time the invoice was created | | **Merchant** | The merchant account the invoice belongs to | | **Initiated By** | The user who created the invoice | | **Invoice title** | "Ecrypt Invoice #\[ID]" | | **Due date badge** | Blue chip showing "DUE ON \[DATE]" | | **Transaction link** | If paid, a clickable "Transaction #XXXXXXXXX" link to the transaction record | | **Invoice Link** | Hosted payment page URL (clickable + copy icon) — this is what you share with the customer | ### Invoice Body | Field | Description | | --------------------------- | ------------------------------------------------- | | **Payment Amount** | Total amount due | | **Customer Name** | Full name from the vault | | **Customer Email** | Email on file | | **Customer Invoice Number** | Your custom invoice number (e.g., INV-2026052004) | ### Left Panel — MENU & ACTIONS The left sidebar of the Invoice Information panel changes based on invoice status: **MENU** * **Invoice Information** — the current view (always present) **ACTIONS (vary by status)** | Action | Available When | Description | | ------------------ | ----------------------------------- | ------------------------------------------ | | **Copy Invoice** | Always | Duplicates this invoice as a new draft | | **Cancel Invoice** | Unpaid invoices (Pending, Past Due) | Voids the invoice; sets status to Canceled | | **Send Again** | Unpaid invoices (Pending, Past Due) | Re-sends the invoice email to the customer | > **Note:** Paid and Canceled invoices only show **Copy Invoice**. Unpaid invoices show all three actions. *** ## Create Invoice Navigate to **Invoices → Create Invoice** (or click the **CREATE INVOICE** button on the Dashboard). ### Step 1 — Add Customer Type in the **Search for existing customer** field to find a Customer Vault record by name. The autocomplete dropdown shows: * **+ Add a New Customer** — creates a new vault record inline * Matching existing customers (shown as "FIRST LAST") Select a customer to populate the invoice. The selected customer appears below the field with a red **Delete** (trash) icon to remove them. ### Step 2 — Add Line Items After selecting a customer, type in the **Find or Add Line Item** field to search your saved product catalog or create a one-time item. **Dropdown options:** * **+ Add a New Item** — opens the inline line item form * Matching saved products (if any exist) #### Add New Line Item Form Clicking **+ Add a New Item** expands a mini-form: | Field | Required | Notes | | ------------------------- | -------- | --------------------------------------- | | **Line Item Name** | Yes | Name shown on the invoice | | **Line Item Description** | No | Optional detail text | | **Price** | Yes | Unit price in dollars (default: \$0.00) | | **Quantity** | Yes | Number of units (default: 1) | Buttons: **CANCEL** (discards the item) · **ADD NEW LINE ITEM** (adds it to the invoice and updates the preview) You can add multiple line items. Each appears in the live **Invoice Preview** on the right as you build. ### Step 3 — Payment Collection Info | Field / Option | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------- | | **Add Invoice Number** | Optional custom invoice reference number. If left blank, Ecrypt auto-generates one. | | **Request payment**\*(radio)\* | Sends the invoice as a payment request with an optional due date. The customer pays via the hosted link. | | **Charge Customer**\*(radio)\* | Generates an invoice receipt that charges the customer's saved card now or later. | ### Step 4 — Additional Payment Info | Field | Required | Notes | | ------------------- | -------- | ---------------------------------------------------------------------------------- | | **Tax (Exclusive)** | No | Percentage entered as a number (e.g., `8` for 8%). Applied on top of the subtotal. | ### Step 5 — Invoice Details | Field | Required | Notes | | --------------- | -------- | -------------------------------------------------------------------------------------------------------- | | **Footer Text** | No | Custom text that appears at the bottom of the invoice PDF/page (e.g., payment terms, thank-you message). | ### Invoice Preview The right-hand panel shows a live preview of the invoice as you fill in the form. It displays: * Ecrypt logo (or your custom logo if configured in Branding) * Invoice Date (today's date) * Bill To (customer name + email) * Line items with price and quantity * **Pricing Summary:** Subtotal · Estimated tax · Surcharge · **Amount Due** ### Form Actions | Button | Action | | ------------------ | -------------------------------------------------------------- | | **CREATE INVOICE** | Saves and sends the invoice; generates the hosted payment link | | **CANCEL INVOICE** | Discards the form and returns to the Dashboard | *** ## Invoice Branding Navigate to **Invoices → Branding**. The page title is **"Appearance"** and contains three content tabs and a preview panel. ### Content Tabs | Tab | Controls | | ----------- | ----------------------------------------------------- | | **Invoice** | Colors for the PDF/invoice portion of the hosted page | | **Form** | Colors for the payment collection form | | **Mobile** | Colors for the mobile-optimized layout | ### Preview Panel (Top Right) Three device tabs let you preview how the invoice looks on different screens: | Preview Tab | Shows | | ----------- | ------------------------------------------ | | **Desktop** | Side-by-side invoice + payment form layout | | **Tablet** | Tablet-sized responsive view | | **Mobile** | Single-column mobile card view | ### Invoice Tab — Color Settings | Setting | Default | Description | | ------------------------------- | --------- | --------------------------------------- | | Invoice Background Color | `#F0F1F2` | Background of the invoice document | | Invoice Text Color | `#333333` | Body text color | | Invoice Accent Color | `#4a9fd7` | Hyperlinks and highlight elements | | Invoice Border Color | `#c4c4c4` | Divider/border lines | | Invoice Button Background Color | `#0f2859` | Pay button background | | Invoice Button Text Color | `#ffffff` | Pay button text | | Invoice Icon Theme | Dark | Icon set style (dropdown: Dark / Light) | ### Form Tab — Color Settings | Setting | Default | Description | | ---------------------------- | --------- | --------------------------------------- | | Form Background Color | `#ffffff` | Payment form background | | Form Text Color | `#333333` | Form body text | | Form Title Color | `#A4A9AF` | Section heading color | | Form Accent Color | `#4a9fd7` | Checked states, active elements | | Form Border Color | `#333333` | Input field borders | | Form Button Background Color | `#0f2859` | Submit button background | | Form Button Text Color | `#ffffff` | Submit button text | | Form Input Text Color | `#333333` | Text inside input fields | | Form Label Color | `#A4A9AF` | Field label text | | Form Input Background Color | `#ffffff` | Input field background | | Alert Color | `#d32f2f` | Error/alert messages | | Success Color | `#333333` | Success state indicators | | Active Tab Color | `#0f2859` | Currently selected tab | | Inactive Tab Color | `#6b6b6b` | Unselected tabs | | Form Icon Theme | Dark | Icon set style (dropdown: Dark / Light) | ### Mobile Tab — Color Settings | Setting | Default | Description | | ------------------------------- | --------- | --------------------------------------- | | Mobile Background Color | `#ffffff` | Mobile page background | | Invoice Mobile Background Color | `#F0F1F2` | Invoice card background on mobile | | Invoice Mobile Text Color | `#333333` | Invoice text on mobile | | Mobile Text Color | `#333333` | General mobile text | | Mobile Button Background Color | `#0f2859` | PAY NOW button background | | Mobile Button Text Color | `#ffffff` | PAY NOW button text | | Mobile Input Text Color | `#333333` | Input text on mobile | | Mobile Input Background Color | `#ffffff` | Input field background on mobile | | Mobile Input Border Color | `#333333` | Input field borders on mobile | | Mobile Label Color | `#A4A9AF` | Field labels on mobile | | Mobile Title Color | `#A4A9AF` | Section titles on mobile | | Mobile Icon Theme | Dark | Icon set style (dropdown: Dark / Light) | ### Saving Branding Changes Click the **Save** button (bottom-right of the preview panel) to apply all three tabs at once. Each color field also has a circular **reset** icon (↺) that reverts that individual field to its default value. *** ## Invoice URL Details Navigate to **Invoices → URL Details** (opens as a modal overlay on the Dashboard). This section lets you configure two post-payment URLs that apply to all invoices globally. | Field | Required | Notes | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | **Finish URL** | No | The URL customers are redirected to after successfully completing payment (e.g., your "Thank You" page) | | **Terms And Conditions URL** | No | A link to your T\&C or refund policy page; displayed on the invoice payment form | Click **SAVE** to apply the changes. *** ## Tips & Best Practices **Invoice Number Preference.** Leave the invoice number blank to use Ecrypt's auto-generated sequential IDs, or enter your own format (e.g., `INV-2026-001`) for consistency with your accounting system. **Request Payment vs. Charge Customer.** Use *Request payment* when you want to send a link the customer clicks themselves. Use *Charge Customer* when you've already have the customer's payment method on file and want to charge it directly without requiring customer action. **Line Item Descriptions.** Adding descriptions to line items improves transparency for the customer and reduces disputes. Descriptions appear on both the invoice PDF and the hosted payment page. **Tax Field.** The Tax (Exclusive) field adds tax on top of the subtotal. "Exclusive" means the tax is not included in the item prices — it's calculated separately. For example, a $100 item at 8% tax results in a $108 total. **Footer Text.** Use the footer to add payment terms (e.g., "Net 30"), a thank-you note, or return policy information. This text appears at the bottom of every invoice. **Resending Invoices.** If a customer hasn't paid and the due date is approaching, use **Send Again** from the Invoice Information panel to re-send the email without creating a duplicate invoice. **Copying Invoices.** Use **Copy Invoice** to quickly generate a new invoice pre-filled with the same line items and customer — ideal for recurring billing that doesn't need a subscription. **Branding Consistency.** Match the Invoice Accent Color and Button Background Color to your brand's primary color. The preview panel updates in real time so you can see the result before saving. **Finish URL.** Always set a Finish URL so customers have a clear next step after paying. A simple "Thank you, your payment was received" page reduces customer support inquiries. **Overdue vs. Past Due.** Both statuses indicate an unpaid invoice whose due date has passed. Use the status filter tabs to quickly isolate and follow up on all outstanding balances. # Manage Locations Source: https://docs.ecrypt.com/dashboard/manage-locations Location Management is built for merchants who operate multiple MIDs (Merchant IDs) under a single Ecrypt login. From one set of credentials, a user can: * Switch into any individual MID to run transactions, manage customers, send invoices, etc. * Select multiple MIDs at once for **consolidated reporting** across locations. * Choose which MID is their **default location** — the one Ecrypt automatically loads when they log in. This guide covers both the **Location Management settings page** (where the default location is configured) and the **Merchant Accounts switcher** in the top-left of the dashboard (where users move between locations day-to-day). > **Single-location vs. multi-location mode**
Most actions in Ecrypt — running a transaction, creating a customer, building an invoice, pairing a terminal, configuring webhooks, etc. — are MID-scoped and require exactly **one** location to be active. If multiple locations are checked in the switcher, the dashboard enters consolidated **reporting-only** mode and transactional actions are unavailable until the user narrows the selection back to a single MID. *** ## The Merchant Accounts Switcher (Top-Left) The button immediately under the Ecrypt logo shows the current scope: | Mode | Button label example | | ------------------------- | ------------------------------ | | Single location active | `Reporting on [Location Name]` | | Multiple locations active | `Reporting on N locations` | Clicking the button opens the **Your Merchant Accounts** panel. ### Panel Elements * **Search field** — `Search for a merchant account`. Filters the list as you type. * **All Merchants** — master checkbox that selects every MID at once (use cautiously on accounts with many MIDs). * **Merchant list** — scrollable list of every MID the user has access to. Each row shows: * The merchant/location name * A status badge such as `Demo` or `TEST` (production MIDs have no badge) * A checkbox on the left * **APPLY** — commits the selection and reloads the dashboard in that scope. * **Clear all** — unchecks every selection in the panel. * **X (top right)** — closes the panel without applying changes. ### How to Switch Into a Single Location 1. Click the location button in the top-left. 2. Click **Clear all** (if multiple are currently selected). 3. Check the box next to the location you want to work in. 4. Click **APPLY**. The dashboard reloads scoped to that MID and the button now reads `Reporting on [Location Name]`. All transactional features become available. ### How to Run Consolidated Reports Across Multiple Locations 1. Click the location button in the top-left. 2. Check every location you want included in the consolidated view (or use **All Merchants**). 3. Click **APPLY**. The button now reads `Reporting on N locations`. Reporting and transaction-list pages aggregate across the selected MIDs. > While multiple locations are selected, the dashboard is in reporting-only mode. You cannot run a transaction, create or edit customers, send invoices, build subscriptions, or change MID-level settings until you re-select a single location. Pages that require a single MID either redirect or display a prompt to narrow your selection. *** ## Location Management Page **Path:** Settings → Account Settings → Location Management This page is where the user picks which MID Ecrypt should open by default each time they log in. ### Layout A simple two-column table: | Column | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Locations** | Every MID the user has access to (same list as the switcher). The currently selected default is highlighted. | | **Set as default location** | A toggle switch per row. Exactly one row should be toggled on. | A **SAVE** button sits below the list. ### Setting a Default Location 1. Navigate to Settings → Account Settings → Location Management. 2. Find the desired MID in the list (the list is alphabetical and may scroll). 3. Toggle on **Set as default location** for that row. 4. Click **SAVE**. Next login, the dashboard opens already scoped to that MID. The user can still switch into any other MID at any time via the top-left switcher. > Setting a default location is a **per-user** preference. Each team member chooses their own default — useful for staff who primarily work out of a specific store, region, or business unit. *** ## Typical Use Cases * **Multi-store retailer.** A regional manager defaults to the flagship store but switches into individual store MIDs throughout the day to spot-check transactions. * **Franchise operator.** Each franchise location is its own MID. The owner runs end-of-week consolidated reporting by selecting all locations, then narrows back to one MID to issue a refund. * **Holding company.** Multiple business entities share one Ecrypt login. Each entity has its own MID with separate processing, deposits, and statements; consolidated reporting gives a portfolio view. * **Test + production side-by-side.** TEST MIDs let developers and admins verify integrations without affecting live processing. The TEST badge in the switcher makes it obvious which environment is active. *** ## Tips & Best Practices * **Default to your most-used MID.** If you spend 90% of your time in one location, set it as default to skip the switcher on every login. * **Always confirm your scope before transacting.** Glance at the top-left button before running a payment or issuing a refund — it tells you exactly which MID the action will hit. * **Use consolidated mode for reporting only.** When you need to take action on a specific transaction or customer, re-select that single MID first. * **Search before scrolling.** On accounts with many MIDs, the search field in the switcher is faster than scrolling the list. * **TEST MIDs are clearly badged.** If you see a `TEST` tag in the switcher or location list, transactions in that MID will not settle real funds — useful for training new staff or validating new integrations. * **Permissions still apply per MID.** Even though one login spans multiple locations, a user's permissions (Transactions, Customer Vault, etc.) are configured per MID under User Management. Access to a location in the switcher does not imply the same permissions in every location. # Manage Terminals Source: https://docs.ecrypt.com/dashboard/manage-terminals The Terminal Settings module under Settings is where you configure the operational rules that drive in-person and terminal-based payments. It's split into three sub-pages: **Set Tax Amount** for regional tax rates that auto-apply to transactions, **Device Management** for pairing and configuring cloud-based card terminals, and **Defined Fields** for adding custom data-capture fields to your payment workflows. This guide covers each sub-page in detail, including how Ecrypt's cloud terminals pair with your dashboard. *** ## Navigation From the left sidebar: **Settings → Terminal Settings**, then expand to reveal: * Set Tax Amount * Device Management * Defined Fields *** ## Set Tax Amount A library of tax rates that can be attached to transactions by region. Each tax record is region-tagged so you can apply the right rate based on where the customer is located. ### Tax Rate List | Column | Notes | | ------------ | ---------------------------------------------------------------------------------------- | | Region | Free-text region label (e.g., OR, CA, FL, BOZEMAN). | | Rate | Percentage rate and whether it's Exclusive or Inclusive. | | Type | Sales (sales tax) or Vat (value-added tax). | | Date Created | Date the tax record was added. | | Action | **Delete** only — tax rates can't be edited after creation; delete and re-add to change. | Top toolbar: * **+TAX** button — opens the Add Tax Rate panel. * **FILTERS** / **CLEAR FILTERS** — filter the list. * **Rows per page** with pagination. ### Add Tax Rate | Field | Required | Notes | | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Region | Yes | Free-text label for the geography this rate applies to. | | Type | Yes | Dropdown: **Sales Tax** (default), **VAT**. | | Rate | Yes | Percentage (e.g., `2.5` for 2.5%). | | Rate Type | Yes | Dropdown: **Exclusive** (default — tax added on top of the subtotal) or **Inclusive** (tax is already baked into the displayed price). | | Description | No | Free-text notes describing the rate. | Click **ADD TAX RATE** to save. **Tip:** Use **Exclusive** rates when you want the customer to see "Subtotal + Tax = Total" math on receipts (typical for U.S. sales tax). Use **Inclusive** when the displayed price already contains the tax, and you just need Ecrypt to report the tax portion separately (typical for VAT/GST-style regions). *** ## Device Management This is where you pair, configure, and manage Ecrypt's cloud-based card terminals. Once paired, a terminal accepts card-present payments triggered from the **POS** quick action in the sidebar. ### How Ecrypt Cloud Terminals Work Ecrypt terminals are cloud-based. After powering on the device and connecting it to either ethernet or WiFi, the terminal displays a **6-digit registration code** on its screen. You enter that code into the Ecrypt dashboard when pairing a new device — that's how the physical terminal is linked to your merchant account in the cloud. Once a terminal is paired, you use the **POS** button in the sidebar (under ACTIONS) to push card-present transactions to that device. The terminal prompts the customer to tap, dip, or swipe — and the resulting transaction flows back into the dashboard like any other payment. ### Device List | Column | Notes | | ---------- | -------------------------------------------------------------------------------------- | | Nickname | The friendly name you gave the device when pairing (e.g., MONDAY TEST, THURSDAY TEST). | | ID | System-generated UUID for the device. | | Model | Device model (e.g., IPP320). | | Date Added | When the device was paired. | | Action | **Edit** and **Delete**. | Top right: **+TERMINAL** button — opens the New Terminal pairing panel. ### New Terminal (Pairing a Device) Header text: "Please have the terminal in front of you to complete this process." | Field | Notes | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Device Nickname | Friendly name for this terminal. Used throughout the dashboard. | | Device Registration Code | The 6-digit code currently displayed on the terminal screen. The terminal must be powered on and connected to a network before this code will display. | **Device Default Configuration** — checkboxes that govern how the terminal behaves out of the box. These can be edited later: | Toggle | What it does | | ----------------------------------------------------- | ------------------------------------------------------------------------------------- | | Default Signature Capture on (Supported devices only) | Prompts for a signature on the terminal after the transaction. | | Default Prompt CVV on | Asks the customer to enter the card's CVV/security code. | | Default Amount Confirmation on | Shows the customer the amount and asks them to confirm before processing. | | Default Enter Postal Code on | Prompts for the customer's billing ZIP/postal code (used for AVS). | | Default Key Card on | Allows manual key entry on the terminal in addition to tap/dip/swipe. | | Default Tip at Time of Sale on | Prompts the customer to add a tip on the terminal screen before payment is finalized. | **Enter Tip Amount to Display on Terminal (Converted to dollar amount)** — four percentage suggestion buttons that the customer sees if Tip at Time of Sale is enabled: | Field | Notes | | -------------- | ---------------------------------------------------------------------------------------------------------------- | | Tip Amount 1–4 | Percentage values (e.g., 15, 18, 20, 25). The terminal converts each to a dollar amount based on the sale total. | Click **ADD TERMINAL** to complete pairing. Once added, the terminal is ready to accept card-present transactions from the POS quick action. ### Edit Terminal The Edit panel has the same default configuration toggles and tip amount fields as the New Terminal panel. Differences: * The **Terminal Name** is shown as read-only at the top — you can't rename a terminal after pairing. * There's no Device Registration Code field — pairing is one-time. * The save button reads **UPDATE TERMINAL**. ### Deleting a Terminal Click **Delete** in the Action column to unpair a device. After deletion, the terminal stops responding to POS pushes from your account. To use the device again, power-cycle it, retrieve a fresh 6-digit code, and pair it as a new terminal. *** ## Defined Fields Defined Fields let you add custom data-capture inputs to your payment flows — useful for collecting things like invoice numbers, slip numbers, order types, dock locations, or any other custom information that isn't part of the standard payment form. Once defined, these fields show up wherever payments are taken. ### Field List | Column | Notes | | ------ | ---------------------------------------------------------------- | | Name | The field's display label (e.g., Invoice#, Slip #, Dock Number). | | Type | The input type: Text, Checkbox, Radio, or Select. | | Action | **Edit** and **Delete**. | The **Add Field** form sits to the right of the list and dynamically changes based on the Field Type you pick. ### Add Field — Common Inputs | Field | Notes | | ------------- | ------------------------------------------------------------------ | | Name of Field | The label customers/staff will see. | | Field Type | Dropdown: **Text** (default), **Checkbox**, **Radio**, **Select**. | ### Field Type Behaviors **Text** Adds a free-text input. Shows a **Validation Rule** dropdown that controls what's accepted: | Validation Rule | Notes | | --------------- | ------------------------------------- | | Max/Min length | Enforce a character length range. | | Phone Number | Validates phone-number formatting. | | URL | Validates URL formatting. | | Date | Validates date formatting. | | Alphabetic only | Letters only — no numbers or symbols. | | Numeric only | Digits only. | | Currency | Validates currency formatting. | | Percent | Validates percentage formatting. | | None | No validation. | **Checkbox** Replaces Validation Rule with a **Checkbox fields** input where you type labels for each checkbox. Helper text: "You can add up to a maximum of 10 checkbox fields." **Radio** Replaces Validation Rule with a **Radio fields** input where you type labels for each radio option. Helper text: "You can add up to a maximum of 10 radio fields." **Select** Replaces Validation Rule with a **Select option fields** textarea. Helper text: "To add multiple entries, separate each word with a comma. You can add up to a maximum of 50 options." Click **ADD FIELD** to save the new field, which then appears in your payment workflows. *** ## Tips & Best Practices Tax rates can't be edited after creation — only deleted. If you need to change a rate, delete the old one and add a new one with the corrected value. Existing transactions that already used the old rate keep their historical tax record intact. Keep the **Region** label short and consistent (state abbreviations work well) so your staff can quickly pick the right rate at the point of sale. For the cloud-terminal pairing flow, the order matters: power on the terminal first, let it connect to your network, then start the +TERMINAL panel in the dashboard. The 6-digit code is short-lived — if the terminal sits idle on the code screen too long it may refresh, so don't start the pairing dialog until the code is on the screen in front of you. Be deliberate about the **Default Configuration** toggles when pairing a terminal. Turning on **Default Amount Confirmation** and **Default Enter Postal Code** improves fraud signals (better AVS coverage) but adds friction to every transaction. For high-volume environments (restaurants, retail counters), you may prefer to leave those off and rely on tap/EMV liability shift instead. **Default Tip at Time of Sale** is essential for service businesses but should be off for retail. The tip percentages you enter for Tip Amount 1–4 are the suggestions the customer sees on the terminal screen. Industry-typical values are 15 / 18 / 20 / 25, but tune these to your business — quick-service often uses 10 / 15 / 20 / 25, while fine dining might use 18 / 20 / 22 / 25. The terminal converts each percent into the equivalent dollar amount for the specific sale. For Defined Fields, pick the field type that minimizes data entry errors. Use **Select** or **Radio** whenever the answer comes from a known set of options (e.g., department, dock number, route) so staff aren't free-typing values that won't aggregate cleanly in reports. Reserve **Text** with validation rules (especially Numeric only, Currency, Phone Number) for cases where the value is genuinely free-form. **Checkbox** is best for multi-select tags like "Curbside / Tip Included / Customer Pickup." Once a terminal is paired and Defined Fields are set up, in-person sales become a tight workflow: open **POS** from the sidebar, enter the amount, fill any defined fields, push to the terminal, and let the customer complete payment on the device. The transaction lands in **Credit Cards → Transactions** like any other payment, with its full audit trail. # Manage Transactions Source: https://docs.ecrypt.com/dashboard/manage-transactions The Manage Transactions module is where you view, search, and act on every payment that flows through your merchant account — both card and bank account (ACH/Check) transactions. From this area you can drill into an individual transaction to see its full payment story, take per-transaction actions like void, refund, or charge again, or use the bulk-processing pages to handle refunds, voids, captures, and tip adjustments in batches. This guide covers the **Credit Cards** module, the **Check** (ACH) module, and the universal **Transaction Detail Slide-Out** that opens when you click any transaction row. *** ## Navigation From the left sidebar: * **Credit Cards** (expand): Transactions, Refunds, Voids, Captures, Tip Adjust, L2/L3 * **Check** (expand): Transactions, Refunds, Voids The two modules mirror each other in layout. Credit Cards has additional sub-pages (Captures, Tip Adjust, L2/L3) that don't apply to ACH. Every sub-page shares the same toolbar: * **Filter By** chip — defaults to the current Transaction Date range (e.g., last 7 days) * **FILTERS** — opens advanced filter panel * **CLEAR FILTERS** — resets filters to default * **Rows per page** — 10 / 25 / 50 / 100 * **Pagination arrows** at the bottom right *** ## Credit Cards ### Transactions Read-only ledger of every card transaction (sales, authorizations, credits, refunds, validations, and their resulting statuses). | Column | Notes | | ---------------- | ---------------------------------------------------------------------- | | ID | Unique transaction ID. Click to open the Transaction Detail Slide-Out. | | Transaction Date | Date and time the transaction was created. | | Amount | Settled amount. Refunds show in parentheses and red. | | Type | Sale, Refund, Authorize, Credit, Validate. | | Account Data | Masked card number with brand icon. | | Customer | Linked customer name (if attached). | | Status | Approved, Settled, Declined, Voided. | **Tip:** Status colors give you a quick read — green for Settled, blue for Approved (not yet captured/settled), red for Declined. ### Refunds A bulk-refund workspace listing transactions eligible for refund (typically Settled sales). | Column | Notes | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | ☐ | Checkbox to include the row in the bulk refund batch. | | ID | Transaction ID. | | Transaction Date | Original transaction date. | | Amount | Original transaction amount (the maximum refundable). | | Refund Amount | Editable input. Placeholder: \$999,999,999.99. Enter the amount you want to refund per row (can be partial). | | Account Data | Masked card with brand. | | Customer | Linked customer name. | Top right: **Process Refunds** button — submits all checked rows with their entered Refund Amounts in a single batch. ### Voids A bulk-void workspace listing transactions eligible for void — i.e., authorized/approved but **not yet settled**. Once a transaction settles, it can only be refunded, not voided. | Column | Notes | | ------------------------------------------------------------------ | --------------------------------------------------- | | ☐ | Checkbox to include the row in the bulk void batch. | | ID, Transaction Date, Amount, Type, Account Data, Customer, Status | Standard transaction columns. | Top right: **Process Voids** button — voids all checked rows at once. ### Captures A bulk-capture workspace for converting Authorize-only transactions into Sales. Empty for merchants who only process Sale transactions. | Column | Notes | | ---------------------------- | -------------------------------------------------------------------------------------- | | ☐ | Checkbox to include the row. | | ID, Transaction Date, Amount | Standard transaction details. | | Captured Amount | Editable — the amount you intend to capture (must be ≤ the original Authorize amount). | | Account Data, Customer | Standard columns. | Top right: **Process Captures** button. ### Tip Adjust A bulk-adjust workspace for adding or modifying tip amounts on transactions after the original sale (commonly used by restaurants and service businesses). | Column | Notes | | ---------------------------- | ----------------------------------- | | ☐ | Checkbox to include the row. | | ID, Transaction Date, Amount | Standard transaction details. | | Tip Amount | Editable — the tip you want to add. | | Account Data, Customer | Standard columns. | Top right: **Process Tip Adjust** button. ### L2/L3 Read-only listing of transactions with Level 2 / Level 3 enhanced commercial card data attached (typically applicable to B2B and government card payments). | Column | Notes | | ------------------------------------------------------------------ | ---------------------------------------------- | | ID, Transaction Date, Amount, Type, Account Data, Customer, Status | Standard transaction columns — no bulk action. | *** ## Check (ACH) ### Transactions The ACH ledger mirrors Credit Cards → Transactions. | Column | Notes | | ---------------- | ----------------------------------------------------------- | | ID | Click to open the Transaction Detail Slide-Out. | | Transaction Date | Date and time of the transaction. | | Amount | Transaction amount. Refunds display in parentheses and red. | | Type | Sale, Refund, Credit. | | Account Data | Masked account number with bank icon. | | Customer | Linked customer name. | | Status | Approved, Settled, Declined. | ### Refunds Same bulk layout as Credit Cards → Refunds, but for ACH transactions. | Column | Notes | | ---------------------------------------------------------------------- | ---------------------------------- | | ☐, ID, Transaction Date, Amount, Refund Amount, Account Data, Customer | Refund Amount is editable per row. | Top right: **Process Refunds** button. ### Voids Bulk-void of ACH transactions that haven't settled. | Column | Notes | | --------------------------------------------------------------------- | ------------------------------------ | | ☐, ID, Transaction Date, Amount, Type, Account Data, Customer, Status | Same layout as Credit Cards → Voids. | Top right: **Process Voids** button. *** ## Transaction Detail Slide-Out Click any row in any Transactions/Refunds/Voids list to open the slide-out. This is the central place to inspect a single payment and take per-transaction actions. ### Header * **Status badge** — APPROVED, SETTLED, DECLINED, VOIDED * **Timestamp** — date and time the transaction was created * **Merchant** — the merchant account that processed it (e.g., MIAMI) * **Initiated By** — source of the transaction (e.g., API KEY (06FA91), a username, or HOSTED PAYMENT) * **Transaction #** — the transaction ID * If the transaction is part of a subscription: **BILLED \[cycle]** chip and **NEXT PAYMENT DATE: \[date]** chip * **Subscription ID** — clickable link to the parent subscription (subscription transactions only) * **Response chips:** RESPONSE (e.g., APPROVED, TRANSACTION PROCESSED.), APPROVAL CODE, CURRENCY (USD), ENTRY MODE (KEYED, SWIPED, etc.) ### Payment Card Visual * **Credit card transactions:** Cardholder name, Payment Amount, masked card number, expiration, brand logo (Visa, Mastercard, Discover, Amex) * **ACH transactions:** Account holder name, Payment Amount, masked Account Number, masked Routing Number ### Billing & Shipping Addresses Displayed below the card visual. Shows the address fields submitted with the transaction, or N/A if none were captured. ### More Info | Field | Notes | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Subtotal | Amount before tax and surcharge. | | Tax | Tax portion of the transaction. | | Surcharge | Surcharge portion (if applicable). | | AVS Status | Address Verification result code. Hover the info icon for the plain-English meaning (e.g., **Z = "Postal code match only"**). | | CVV Status | CVV result code. Hover the info icon for the meaning (e.g., **Unavailable = "CVV not available"**). For ACH, this is always Unavailable. | ### Subscription Info Appears only when the transaction belongs to a subscription. | Field | Notes | | ------------- | ------------------------------------------------------------- | | Billing Cycle | Daily, Weekly, Monthly, etc. | | Installments | Total installments (or N/A for open-ended subscriptions). | | Send Receipts | Yes / No — whether receipts are auto-emailed to the customer. | ### Order Information Displays line items / order metadata if captured. Otherwise N/A. *** ## Left-Panel Menu The left side of the slide-out is split into **MENU**, **ACTIONS**, and (for subscriptions) **ACTIONS FOR SUBSCRIPTIONS**. ### MENU * **Payment Information** — the default view described above. * **Transaction History** — chronological list of every event tied to this transaction (Sale, Void, Refund attempts, etc.) with type, status, timestamp, and amount. ### ACTIONS (per-transaction) What appears here depends on the transaction's status and type: **For APPROVED transactions (not yet settled):** * **Void Transaction** * View Receipt * Charge Again * Add to customer vault *(if not already linked to a customer)* * View Customer *(if linked)* **For SETTLED transactions:** * **Refund Transaction** (replaces Void Transaction once settled) * View Receipt * Charge Again * Add to customer vault *(if not already linked)* * View Customer *(if linked)* **For DECLINED transactions:** * View Receipt * Charge Again ### ACTIONS FOR SUBSCRIPTIONS Shown when the transaction is a subscription payment: * Subscription History * Pay Early * Cancel Subscription * Pause Subscription * Edit Subscription These actions affect the parent subscription, not just this one transaction. *** ## Action Panels (Right-Side Drawers) Clicking an item in ACTIONS opens a secondary panel that slides in from the right. ### Void Transaction Available on Approved (unsettled) transactions. Cancels the transaction before it settles, so no funds move. * Read-only summary: Amount, Card/Account Number, Date, brand/bank logo * Description: "Voiding a transaction refers to the act of canceling or reversing a previously processed transaction." * **CONFIRM** button — submits the void ### Refund Transaction Available on Settled transactions. Returns funds to the customer. * Read-only summary: Payment Amount, Card/Account Number, Date, brand/bank logo * Description: "Refunding a transaction refers to the act of refunding a previously processed transaction." * **Refund Amount** field — pre-filled with the full transaction amount; editable for partial refunds * Helper text: "Amount CANNOT exceed \$\[original amount]" * **CONFIRM** button — submits the refund **Tip:** For partial refunds, change the amount before confirming. You can issue multiple partial refunds until the cumulative refunded total reaches the original amount. ### Charge Again Re-runs a payment using the same payment method on file — useful for repeat purchases or retrying a declined charge. | Field | Notes | | -------------------------------- | --------------------------------------------------------------------------------------- | | Transaction Type | Default Sale. Same options as Manual Payment Entry (Sale, Authorize, Credit, Validate). | | Amount | Pre-fills from the original; editable. | | Tax (Exclusive) | Optional. | | Saved card / bank | Read-only — displays the original payment method. | | Billing address same as shipping | Checkbox, checked by default. Uncheck to enter a separate shipping address. | | Pricing Summary | Sidebar showing the calculated totals. | Click **SUBMIT PAYMENT** to process the new transaction. ### View Receipt Opens the printable / emailable receipt for the transaction. ### Add to customer vault Available on any transaction not yet linked to a Customer Vault record. Saves the payment method (and contact info) to a new or existing customer profile for future use without re-entering card/bank details. ### View Customer Available when the transaction is linked to a vaulted customer. Jumps to that customer's profile in the Customer Vault. ### Subscription History Lists every billing cycle that has run (or been skipped) for the parent subscription, with date, status, and amount per cycle. ### Pay Early Triggers the next scheduled subscription payment immediately, ahead of its normal billing date. ### Cancel Subscription Permanently cancels the subscription. No further automatic charges will run. ### Pause Subscription Temporarily suspends billing without canceling. You can resume it later. ### Edit Subscription Opens the subscription editor where you can change cycle, amount, end date, send-receipt setting, and more. *** ## Tips & Best Practices When something looks off on a card transaction, the **AVS Status** and **CVV Status** info-tooltips are the fastest way to understand why — they translate raw response codes into plain English ("Postal code match only", "CVV not available", etc.). For non-settled transactions, prefer **Void** over **Refund** whenever possible. Voids reverse the authorization before any funds move, so the customer never sees the charge on their statement and you avoid the processing fees associated with a refund. Use the bulk **Refunds**, **Voids**, **Captures**, and **Tip Adjust** pages when you have many transactions to process at once — for example, end-of-day tip adjustments at a restaurant or batch refunds after a chargeback investigation. Always double-check the editable Amount fields before clicking the Process button at the top right; there is no per-row confirmation in the bulk flow. The **L2/L3** sub-page is read-only and exists primarily as a record of which transactions had enhanced commercial card data attached. If you process B2B or government cards, including L2/L3 data typically qualifies your transactions for lower interchange rates. For Check (ACH) transactions, remember that AVS and CVV are always **Unavailable** — these checks don't apply to bank account payments. Decisions about ACH transaction risk should rely on customer history, account verification, and your own fraud rules rather than card-style verification codes. When a transaction is part of a subscription, the slide-out gives you two layers of control: the **ACTIONS** section affects just the one payment (void, refund, charge again), while **ACTIONS FOR SUBSCRIPTIONS** affects the recurring schedule itself. Choose carefully — refunding a single subscription payment is very different from canceling the whole subscription. # Mange Users Source: https://docs.ecrypt.com/dashboard/manage-users The User Management module under Settings → Account Settings is where you onboard team members, control which merchant accounts they can access, and define exactly what they can do inside Ecrypt. Users can range from a single-merchant employee who only processes sales, to an administrator with reporting, configuration, and fraud-prevention authority across every merchant in your portfolio. This guide covers the user list, the Add/Edit Account flow, the full permissions matrix, and the lifecycle actions (reset password, delete) you can take on existing users. *** ## Navigation From the left sidebar: **Settings → Account Settings → User Management** The page lists every user currently provisioned in your portfolio. *** ## User List | Column | Notes | | ---------- | ------------------------------------------------------------------------------------------------- | | Username | The user's login handle. Click the column header to sort ascending/descending. | | First Name | First name from the user's profile. | | Last Name | Last name from the user's profile. | | Email | Email address used for login notifications and password resets. | | Action | Per-row buttons: **Edit** (opens the Edit Account panel) and **Delete** (opens a confirm dialog). | Top toolbar: * **+USER** button (top right) — opens the Add Account flow. * **FILTERS** — opens the Table Filters panel. * **CLEAR FILTERS** — resets any active filter. * **Rows per page** — 10 / 25 / 50 / 100, with pagination arrows at the bottom right. ### Filters Click **FILTERS** to open the Table Filters panel: | Field | Notes | | ----------- | ----------------------------------------- | | Filter By | Username, First Name, Last Name, Email. | | Filter Type | Contains, Equals, Starts With, Ends With. | | Value | Free-text input for the search string. | Click **+ ADD FILTER** to stack multiple filter rows, then **APPLY FILTERS** to run them. *** ## Add Account (+USER) A two-step slide-out for provisioning a new user. ### Step 1 — User Information & Merchants Header text: "Streamlined onboarding for new team members simplifies user setup and access control, effectively granting them the necessary access and defining their capabilities." **User Information** | Field | Required | Notes | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | Username | Yes | Unique login handle. | | User Type | Yes | Dropdown: **Employee** (default), **Manager**, **Administrator**. Sets the baseline of what the user can do. | | First Name | Yes | | | Last Name | Yes | | | Mobile Number | No | Used for SMS authentication. | | Phone Number | No | General contact number. | | Email Address | Yes | Used for login, password reset, and notifications. | **Merchants** A searchable checkbox list of every merchant account in your portfolio. Check the merchants this user is allowed to access. Use the **All** checkbox at the top to grant access to every merchant at once. Use the search box ("Search for a merchant") to narrow the list. Click **NEXT** to continue, or **CANCEL** to discard. Validation errors ("This field is required") appear in red beneath any missing required field. ### Step 2 — Permissions The second step grants granular per-feature permissions. Every checkbox here corresponds to a specific capability inside Ecrypt. **Copy Permissions from Another Employee** A dropdown at the top of the panel that lets you select an existing user and clone their entire permission set onto the new user. Tooltip text: "The functionality allows users to replicate or duplicate the access permissions of another employee by selecting their name from a dropdown menu." This is the fastest way to provision a user who needs the same access as an existing teammate. **Permission Groups** | Group | Permissions | | ----------------- | ------------------------------------------------------------------------------------------------- | | Transactions | Authorize, Sale, Credit, Capture, Void, Reporting, Invoicing | | Customer Vault | Create Customers, Delete Customers, Charge Again | | Fraud Prevention | Manage Security Settings, Manage Velocity Filter, Manage IP Allowed | | Developer Tools | Manage Security Keys, Manage Webhooks, Manage Hosted Payments, Manage Buy Now | | Terminal Settings | Manage Taxes, Manage Devices, Manage Merchant Defined Fields, Manage Subscriptions | | Account Settings | Manage Receipts, Manage Look and Feel, Manage Company Information, Manage Locations, Manage Users | | Notifications | Receive Settlement Summaries, Receive Recurring Reports, Account Updates, Receive Notifications | The Notifications section is tagged: "If email address is provided" — they only fire if Step 1 captured a valid email. **User Information (Preview)** At the bottom of Step 2 you'll see a read-only preview card summarizing the user that's about to be created: Username, Email Address, Full Name, Phone Number, Mobile Phone Number. Click **SAVE USER** to create the account, or **BACK** to return to Step 1 and edit details. **Tip:** Granting **Manage Users** under Account Settings effectively makes the user an administrator of other users — they can create, edit, and delete teammates. Reserve this for owners and trusted leads. *** ## Edit Account Click **Edit** on any row to open the Edit Account slide-out. The layout mirrors Add Account but with a few differences: * **Username** is displayed as read-only text — usernames cannot be changed after creation. * **Mobile Number** is read-only with the note: *"Mobile number is linked to SMS authentication and can only be updated by the user through their own profile to re-verify their number."* * **Reset Password** link appears in the top-right of Step 1. * **User Type, First Name, Last Name, Email Address, Phone Number, and Merchants** are all editable. * Step 2 lets you re-tune any permission checkbox. Click **NEXT** to advance to Permissions, then **SAVE USER** to apply changes, or **BACK** to return to Step 1. ### Reset Password Clicking the **Reset Password** link opens a confirmation dialog: > Are you sure you want to reset this user's password? User will receive an email with instructions to reset their password. Buttons: **YES** / **CANCEL**. The user will get an email with a reset link — you never see or set their password directly. *** ## Delete User Clicking the red **Delete** action on a user row opens a confirmation dialog: > Are you sure you want to delete this account? Buttons: **DELETE** / **CANCEL**. Deletion is immediate and removes the user's ability to log in. Historical transactions and audit entries created by the user remain in the system under their old username for reporting purposes. *** ## Tips & Best Practices Use the **User Type** field as a coarse-grained label (Employee, Manager, Administrator) and the **Permissions** checkboxes for the actual access logic. The User Type doesn't auto-grant permissions on its own — every capability still needs to be explicitly checked in Step 2. The **Copy Permissions from Another Employee** dropdown is a huge time-saver when onboarding multiple people for the same role. Set up one "template" user with the exact permission profile you want (e.g., "Front Desk", "Bookkeeper", "Owner"), then clone from that user every time you add a new teammate in the same role. Be deliberate about which **Merchants** you assign in Step 1. A user with broad permissions but only access to one merchant can't accidentally touch transactions or settings in other merchants. This is the primary mechanism for multi-merchant isolation. When in doubt, follow the principle of least privilege: start a user as **Employee** with the minimal Transactions permissions (e.g., just Sale and Reporting) and expand from there as they demonstrate need. Granting **Delete Customers**, **Manage Security Keys**, **Manage IP Allowed**, or **Manage Users** to a wide audience increases your exposure to mistakes and insider risk. Mobile numbers can only be updated by the user themselves because they're tied to SMS-based authentication. If a user changes phones, they'll need to log into **My Profile** to re-verify the new number rather than asking an admin to update it for them. Use the **Reset Password** flow rather than asking users to share credentials — it sends them an email-based reset link and never exposes the password to anyone. # Manual Payment Entry (KEY & ACH) Source: https://docs.ecrypt.com/dashboard/manual-key-entry ## Overview Manual Payment Entry is the fastest way to run a one-off charge from inside the dashboard without involving terminal hardware or a hosted page. There are two manual entry surfaces: **KEY** for keyed credit card transactions and **ACH** for bank-account transactions. Both are launched from the **ACTIONS** group in the left sidebar, both render in the same right-side slide-over with a live Pricing Summary, and both submit a single transaction immediately. Use these flows for phone orders, mail-order, walk-up payments where no card reader is available, and any other "I'm going to type the payment in by hand" scenario. > **Note:** Manual entry transactions are **keyed entry** for processor and interchange purposes. They carry higher interchange than card-present transactions and the AVS/CVV results matter more for fraud control. Use POS instead when the cardholder is physically present with a card. ## Navigation Both flows are launched from the sidebar **ACTIONS** group: | Action | URL parameter | Opens | | ------ | -------------- | ---------------------------------------- | | KEY | `?actions=key` | Keyed credit card payment slide-over | | ACH | `?actions=ach` | Bank-account (echeck) payment slide-over | The slide-overs can be opened on top of any dashboard page — the parameter just appends to the current URL. Close with the **X** in the top right of the panel. *** ## KEY — Manual Credit Card Entry A single-screen form that takes the operator from "I have a card and an amount" to a settled transaction. ### Transaction Type A dropdown at the top of the form. Choose before entering payment data — it determines what the rest of the form does. | Type | Use it for | | --------- | ------------------------------------------------------------------------------ | | Sale | Standard charge — authorizes and captures in one step (the default) | | Authorize | Holds funds without capturing; capture later from the transaction detail panel | | Credit | Money out — pushes a credit to the card without referencing a prior sale | | Validate | \$0 verification that the card is good without charging anything | ### Amount & Tax | Field | Required | Notes | | --------------- | -------- | -------------------------------------------------------------------------- | | Amount | Yes | Dollar amount to charge (or credit) | | Tax (Exclusive) | No | % applied on top of Amount — shows in the Pricing Summary as Estimated tax | ### Card Information | Field | Required | Notes | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------- | | Name On Card | Yes | Cardholder name exactly as on the card | | Credit Card Number | Yes | Full PAN; the card-brand icon appears once you start typing | | Expiration Date | Yes | MM/YY | | Security Code | Yes | CVV — 3 digits for Visa/Mastercard/Discover, 4 for Amex. Tooltip: "Enter Security Code on back of card" | ### Billing Address | Field | Required | Notes | | -------------- | -------- | ------------------------------------ | | Street Address | Yes | Address line 1 — drives AVS matching | | City | Yes | Billing city | | State | Yes | Billing state | | Zip code | Yes | Billing ZIP — drives AVS matching | ### Shipping Address A checkbox **My billing address is the same as my shipping address** is checked by default. Uncheck it to reveal four additional fields: | Field | Required | Notes | | ----------------------- | -------- | ------------------------- | | Shipping Street Address | Yes | Where the goods are going | | Shipping City | Yes | | | Shipping State | Yes | | | Shipping Zip code | Yes | | ### Pricing Summary A live panel on the right of the slide-over updates as you type: | Row | Notes | | ------------- | -------------------------------------------------------------------------------- | | Amount | The base amount you entered | | Estimated tax | Calculated from the Tax % | | Surcharge | Calculated surcharge (if enabled on the merchant account and the card qualifies) | | Total | The amount that will actually be charged | ### Submit Click **SUBMIT PAYMENT** to run the transaction. The result lands in **Reporting → All Transactions** immediately and appears in the current day's batch for settlement. *** ## ACH — Manual Bank Account Entry The bank-account counterpart to KEY. Same slide-over layout, different payment fields. ACH transactions settle on the ACH network, not the card networks — expect a 1–3 business-day settlement window rather than next-day. ### Transaction Type ACH supports only two transaction types: | Type | Use it for | | ------ | -------------------------------------------------------- | | Sale | Standard debit from the customer's bank account | | Credit | Push a credit (money out) to the customer's bank account | > **Note:** ACH does not support Authorize or Validate. If you need to pre-authorize or zero-dollar verify, use KEY. ### Amount & Tax Same as KEY — Amount (required), Tax Exclusive % (optional). The live Pricing Summary updates identically. ### Bank Account Information | Field | Required | Notes | | --------------- | -------- | -------------------------------------------------- | | Name On Account | Yes | Account holder name on the bank account | | Account Number | Yes | The customer's bank account number | | Routing Number | Yes | 9-digit ABA routing number for the customer's bank | ### Billing Address Same fields as KEY — Street Address, City, State, Zip code, all required. ### Shipping Address Same toggle as KEY — billing and shipping are the same by default; uncheck to expose Shipping Street Address, Shipping City, Shipping State, Shipping Zip code. ### Submit Click **SUBMIT PAYMENT** to send the ACH transaction. It lands in **Reporting → All Transactions** with Tender Type = ACH and a Settled status that lags the card flow by 1–3 business days. *** ## Tips & Best Practices **Pick the Transaction Type before you start typing.** Switching from Sale to Authorize after filling in the form keeps the field values, but it's the single most common source of "wait, why did this not capture?" — verify the dropdown matches what you intend before submitting. **Validate is the safest way to onboard a new card.** \$0 verifications confirm a card is valid without an interchange fee and without touching the customer's available credit. Use it when adding a card to a customer's wallet before the first real charge. **Match the billing address to what the bank has on file, not where the customer lives now.** AVS compares the Street Address and Zip to the issuing bank's records — entering "where they live now" instead of "what the bank statement says" produces avoidable AVS mismatches and can trigger fraud rules. **Authorize + capture later is the pattern for orders you'll ship.** Run an Authorize when the order is placed, then open the transaction in Reporting and click Capture once you ship. The Authorize holds funds for \~7 days depending on the issuer. **Use ACH for high-ticket invoices, KEY for everything else.** ACH has effectively no per-transaction percentage fee — for \$5,000 invoices the savings versus card interchange are substantial. But ACH also has a multi-day settlement and limited recourse on returns, so keep card for anything under a few hundred dollars or where you need fast funding. **Surcharge only applies when the merchant account is configured for it and the card qualifies.** Debit cards never qualify for surcharging. If the Surcharge row in the Pricing Summary shows \$0.00, that's either the merchant configuration or a debit card — both expected. **Credit is a stand-alone push, not a refund.** If you want to refund a specific previous sale, find that transaction in Reporting and use **Refund Transaction** on the detail panel. The Credit transaction type here pushes money to a card with no link to a prior sale — useful for rebates or one-off payouts, but it leaves no audit linkage. **The Pricing Summary is the truth.** Whatever it shows as Total is exactly what will hit the customer. If you expected a tax line and don't see one, the Tax % is missing; if you expected a surcharge and don't see one, the card doesn't qualify or surcharging isn't enabled. Don't submit without confirming Total looks right. **ACH routing numbers can be validated quickly.** All US ABA routing numbers are 9 digits with a checksum — if the customer reads you a number that's the wrong length, ask them to re-read it before typing. Bad routing numbers reject at the processor, not at submit, so a typo wastes a day before you find out. **Shipping address only matters when you're shipping something physical.** For services and digital goods, leave the "billing same as shipping" checkbox alone. It saves four fields and avoids data-entry errors on records that won't be used. # Overview & Navigation Source: https://docs.ecrypt.com/dashboard/overview-navigation The Ecrypt **Dashboard** is the home screen for every login — a single-page snapshot of recent activity for the currently selected location (MID), plus the launchpad for every other feature in the platform. This guide explains how to read the dashboard, where to find each major function, and how the global navigation works so you can move efficiently between modules. **Path:** `/dashboard` (loads automatically on login) *** ## Page Layout The dashboard is divided into three persistent regions that appear on every page in Ecrypt: 1. **Left Sidebar** — global navigation (location switcher, quick actions, app modules). 2. **Top Bar** — date filter and session controls (Logout). 3. **Main Content** — the page-specific content. On the Dashboard, this is KPIs, revenue chart, and a recent transactions table. *** ## Top Bar | Element | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Ecrypt Logo** (top-left) | Clicking returns you to the Dashboard from anywhere in the app. | | **DATE FILTER → Date Range** | Sets the time window applied to the KPI cards, revenue chart, and transactions table on this page. Default is the last 7 days. | | **Logout** (top-right) | Ends the session and returns to the login screen. | ### Date Range Picker Clicking the **Date Range** field opens a picker with: * **Quick presets:** Last Month, Last 2 Weeks, Last Week, Last 7 Days, Reset Date. * **Two-month calendar** with previous/next month navigation. Click a start date, then an end date to define a custom range. * **Ok** — apply the range, **Cancel** — close without changing, **Clear** — empty the selection. The active range is also reflected in the URL (`transactionDate-range=MM-DD-YYYY~MM-DD-YYYY`), so the view is shareable / bookmarkable. *** ## Left Sidebar The sidebar is grouped into clearly labeled sections from top to bottom. ### Dashboard (link) Direct link back to this overview page from anywhere in the app. ### YOUR MERCHANT ACCOUNTS The **location switcher**. The button label reflects current scope: * `Reporting on [Location Name]` — single location selected; all transactional features are available. * `Reporting on N locations` — multiple selected; consolidated reporting mode (transactional features unavailable until a single location is selected). Click the button to open the **Your Merchant Accounts** panel: search the list, check one or more MIDs, then **APPLY**. See `16_location_management.md` for the full workflow. ### ACTIONS One-click shortcuts for the most common transactional tasks. Each launches a slide-out or full-page entry form scoped to the active location. | Action | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **POS** | Card-present transaction via a paired terminal. Use this after a terminal has been registered (Settings → Terminal Settings → Device Management). | | **KEY** | Keyed/manual credit-card transaction. The Virtual Terminal entry form for card-not-present sales. | | **ACH** | Manual ACH (eCheck) transaction. | | **Add Customer** | Create a new customer and save a profile in the Customer Vault. | | **Add Subscriptions** | Create a new subscription or installment plan. | > **Single-location only.** Quick actions require a single MID in scope. If multiple locations are selected via the location switcher, narrow to one before running these. ### APPS The full module catalog. Items with `∨` are expandable groups that reveal sub-pages. | Module | Contents | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Credit Cards** | Transactions, Refunds, Voids, Captures, Tip Adjust, L2/L3 data. | | **Check** | ACH Transactions, Bulk Refunds, Bulk Voids. | | **Customer Vault** | Stored customer profiles, payment methods, billing addresses. See `05_customer_vault.md`. | | **Subscriptions** | Recurring billing plans and active subscriptions. See `06_subscriptions.md`. | | **Reporting** | Settlements, deposits, statements, processing summaries. See `07_reporting.md`. | | **Hosted Payments** | Hosted payment page configuration. See `10_hosted_payments.md`. | | **Settings** | Expand to see sub-groups: Account Settings, Terminal Settings, Developer Tools, Fraud Prevention (see settings-specific guides). | > Invoices and Manual Payment Entry may surface from the Customer Vault / transaction flows depending on the merchant's enabled features. See `09_invoices.md` and `04_manual_payment_entry.md`. *** ## Main Content (Dashboard Body) ### KPI Cards (Top Row) Four metrics for the selected date range, each with a percentage change vs. the **immediately-preceding** window of equal length. | Card | What it counts | | ------------------------- | ------------------------------------------------------------------ | | **APPROVED TRANSACTIONS** | Count of approved transactions within the date range. | | **REFUNDED TRANSACTIONS** | Count of refunds issued within the date range. | | **NEW CUSTOMERS** | Count of new Customer Vault entries created within the date range. | | **DECLINED TRANSACTIONS** | Count of declined transactions within the date range. | Each card shows: * Big number — the total for the current range. * ↑ / ↓ percentage and color (green/red) — change vs. previous comparable window. * `PREV. 7 DAYS` label (or whatever the comparable prior window is). * `ⓘ` info icon — hover to see the exact prior window (e.g., "Previous 7 days from 05-15-2026 to 05-21-2026"). ### Revenue Breakdown A combined view of the merchant's revenue for the selected range: * **Net volume** — gross minus refunds, voids, and chargebacks. * **Gross volume** — total approved sales before deductions. * **Line chart** — daily volume over the selected date range. Hover a point to see exact daily totals. ### Recent Transactions Table A live list of transactions for the active MID within the selected date range. | Column | Description | | -------------------- | -------------------------------------------------------------- | | **ID** | Ecrypt transaction ID. Click to open the detail slide-out. | | **Transaction Date** | Date + time of the transaction. | | **Amount** | Transaction amount. | | **Type** | Sale, Auth, Credit, Refund. | | **Account Data** | Masked PAN + card brand logo (or ACH routing/account preview). | | **Customer** | Linked customer name if one was attached. | | **Status** | Approved, Settled, Voided, Refunded, Declined, etc. | Above the table: * **Transaction Date pill** — restates the active date range. * **Type tabs:** All / Auth / Sale / Credit / Refund — quick filter by transaction type. * **BATCHES** — jump to the batch view (settlement batches for the range). Below the table: * **▽ FILTERS** — open the advanced filter panel. * **CLEAR FILTERS** — reset filters. * **Rows per page** dropdown + pagination arrows. Clicking any row opens the transaction detail slide-out (covered in `02_manage_transactions.md`). *** ## Global Navigation Patterns A few conventions apply across every page in Ecrypt — knowing these makes the rest of the app feel familiar. ### Page-level URLs Every screen has its own URL with the active MID embedded as `?merchantId=...`. Date ranges and other filters are also in the URL, so any view can be bookmarked or shared with a teammate who has access to the same MID. ### Slide-out detail panels Clicking a row in any list (transactions, customers, subscriptions, invoices, etc.) opens a right-side slide-out with the full record and contextual actions (refund, void, edit, view receipt, etc.). The list behind it stays in place so you can move quickly between records. ### Date filters Most list pages have their own date-range filter that works the same as the Dashboard's — same picker, same quick presets, same URL persistence. ### Filters + Clear Filters Most list pages expose a **▽ FILTERS** button that opens a panel of field-level filters (status, amount, customer, card brand, etc.) and a **CLEAR FILTERS** link to reset. ### Settings sidebar When you enter Settings, the left sidebar swaps to a Settings-specific tree (Account Settings, Terminal Settings, Developer Tools, Fraud Prevention) plus a **Go Back** button that returns to the previous app context. *** ## Tips & Best Practices * **Always check the location button in the top-left before doing anything.** It tells you exactly which MID an action will affect — refunding the wrong location is a frustrating mistake to undo. * **Use the date range presets.** "Last 7 Days" and "Last Month" cover most day-to-day reviews; the calendar handles custom audits. * **The KPI comparison window auto-matches your selected range.** If you pick a 14-day window, the comparison is the prior 14 days — not always exactly 7 days. Hover the `ⓘ` icon to confirm. * **Click the Ecrypt logo to reset.** From deep inside Settings or a slide-out, the logo is a one-click way back to the Dashboard. * **Bookmark frequently-used filtered views.** Because filters and date ranges are URL-encoded, you can bookmark e.g. "this MID's last-30-days declines" and reload it later. * **Use Actions for one-off transactions, the apps for management.** Quick Actions (POS, KEY, ACH, Add Customer) are optimized for speed; the corresponding modules in the APPS section give you the full history, search, and bulk tools. * **Set a default MID.** If you primarily work in one location, configure it under Settings → Account Settings → Location Management so the Dashboard opens there automatically on each login. * **Mind the difference between approved and settled.** The Dashboard counts approvals; cash flow questions belong in Reporting, where settlement batches and deposits are tracked. * **Logout when stepping away from a shared workstation.** The Logout link in the top-right ends the session immediately; reauthenticating uses your SMS-verified login flow. # Receipts Source: https://docs.ecrypt.com/dashboard/receipts Ecrypt produces two distinct kinds of receipts for every transaction: 1. **Emailed receipts** — automatically (or manually) sent to the customer's email address when a transaction completes. Their layout is controlled by Ecrypt and is not customizable besides including a custom logo in Settings → Look and Feel. 2. **Printable receipts** — the version you customize in **Settings → Account Settings → Receipts**. This is the receipt that prints from a paired card terminal (e.g., end-of-transaction tape) and from the **View Receipt** action in the Transaction Detail Slide-Out when you print to a regular printer. This guide covers both: how to view, email, and print a receipt for an individual transaction, and how to customize the printable receipt template that's used for terminal slips and dashboard print-outs. *** ## Navigation * **View / print / email a single receipt:** open any transaction → **ACTIONS → View Receipt** * **Customize the printable receipt template:** **Settings → Account Settings → Receipts** *** ## View Receipt (Per-Transaction) Clicking **View Receipt** in the Transaction Detail Slide-Out opens a right-side panel with the full receipt for that transaction. The panel has three parts. ### Top — Transaction Summary | Element | Notes | | -------------- | ---------------------------------------------------------------------------------------------------------------- | | Response chips | RESPONSE (e.g., APPROVED), APPROVAL CODE, CURRENCY, ENTRY MODE. | | Amount | The transaction amount (labeled Subscription Amount when it's a subscription payment, otherwise Payment Amount). | | Card Number | Masked card or account number. | | Date | Card expiration / transaction date. | | Brand | Card brand logo (Visa, Mastercard, Discover, Amex) or bank icon for ACH. | ### Middle — Send Receipt A small form for emailing the receipt to a customer: | Field | Notes | | ------------- | -------------------------------------------------------------------- | | Email Address | Pre-populated with the customer's email if one is on file; editable. | | SEND button | Emails the receipt to the address shown. | Helper text: *"Please provide a valid email address so that we can send you the receipt."* This is the emailed-receipt path — the system-generated email layout is what the customer will get, not the customized printable template. ### Bottom — Printable Receipt Preview & Print A scrollable preview of the printable receipt for this transaction, rendered using your customized template. At the top of the preview is a **printer icon** — clicking it sends the receipt to the browser's print dialog so you can print to any connected printer. The preview contains, in order: * Custom Logo (if uploaded) * Header Lines 1–4 (free text) * DATE, TIME * MERCHANT (location name) * MERCHANT ID * TRANSACTION ID * Transaction Type (e.g., "Credit Card Sale", "ACH Sale", "Refund") * CARD# (masked) and ENTRY MODE (KEYED, SWIPED, etc.) * SUBTOTAL, TAX AMOUNT, TIP AMOUNT, SURCHARGE AMOUNT, TOTAL AMOUNT * Signature line + cardholder name * Status (e.g., SETTLED, APPROVED, VOIDED) * Footer Lines 1–4 (free text) *** ## Customize the Printable Receipt (Settings → Account Settings → Receipts) Page header: "Receipts — Customize receipts sent to your customers." The page is split into a **controls panel on the left** and a **live preview on the right**. Every change you make in the controls is reflected in the preview immediately so you can see exactly what the printed slip will look like. ### Header Lines Four free-text fields that appear at the top of every printed receipt, above the transaction details: | Field | Notes | | ------------- | ------------------------- | | Header Line 1 | First line of the header. | | Header Line 2 | Second line. | | Header Line 3 | Third line (optional). | | Header Line 4 | Fourth line (optional). | Above the four fields are three **alignment icons** (left / center / right). They apply to all four header lines as a group. Common uses: business name, store address, phone number, tagline. ### Footer Lines Four free-text fields that appear at the bottom of every printed receipt, below the signature/status: | Field | Notes | | ------------- | ------------------------- | | Footer Line 1 | First line of the footer. | | Footer Line 2 | Second line. | | Footer Line 3 | Third line. | | Footer Line 4 | Fourth line. | A second set of alignment icons (left / center / right) above the Footer Line fields controls the alignment of all four footer lines as a group. Common uses: cardholder agreement text, return policy reminder, "Retain this copy for your records," promotional message. ### Custom Logo Upload your business logo to print at the very top of the receipt, above the header lines. | Control | Notes | | ---------------------- | --------------------------------------------- | | Alignment icons | Left / center / right alignment for the logo. | | UPLOAD NEW LOGO button | Opens the file picker. | | Accepted file types | JPG or PNG. | | Max image size | 1 MB. | | Max dimensions | 350 × 350 pixels. | ### Save / Reset At the bottom of the right-side preview: * **SAVE** — persists your changes and applies them to every subsequent printed/terminal receipt. * **RESET** — discards unsaved changes and reverts the controls to whatever was last saved. *** ## Live Preview Anatomy The right-side preview always shows a representative receipt rendered with your current template. Even when no transaction is selected, the preview displays the structural sections so you can see exactly where your headers, footers, and logo will land: | Section | Source | | ------------------------------------------------- | -------------------------------------------------------------- | | Logo (top) | Custom Logo upload. | | Header block | Header Lines 1–4. | | DATE / TIME | Auto-filled per transaction. | | MERCHANT / MERCHANT ID / TRANSACTION ID | Auto-filled per transaction. | | Transaction Type | "Credit Card Sale", "ACH Sale", "Refund", etc. | | CARD# / ENTRY MODE | Auto-filled per transaction. | | SUBTOTAL / TAX AMOUNT / TIP AMOUNT / TOTAL AMOUNT | Auto-filled per transaction. | | Signature line | Printed for cardholder signature; cardholder name auto-filled. | | Status | SETTLED / APPROVED / VOIDED / DECLINED, etc. | | Footer block | Footer Lines 1–4. | *** ## Tips & Best Practices Be deliberate about the distinction between the **emailed receipt** the customer gets in their inbox and the **printable receipt** you're customizing here. The template on this page only controls printed output — terminal tape, in-browser print, and any "Save as PDF" flow that runs off the same renderer. Customers who receive their receipt by email will see the standard Ecrypt-formatted message, not your custom header and footer. If you need branding in customer-facing emails, work with the email content separately (it's not on this page). Use **Header Lines** for things customers want to see at a glance — business name, location, phone number, possibly a short tagline. Use **Footer Lines** for legal language and instructions: the cardholder agreement, return policy, "Retain this copy for your records." Keep both blocks short. Receipt printers often use narrow paper, and long lines will wrap or get cut off. Upload a **Custom Logo** sized close to the maximum dimensions (350×350 pixels) but well under the 1 MB file size limit. A high-contrast monochrome (black-on-white) logo prints most cleanly on thermal receipt paper; full-color logos look great on a regular printer but can come out muddy on a tape printer. The **alignment icons** for the header, footer, and logo are independent — you can left-align the logo, center the header lines, and left-align the footer if that's what looks right for your business. Use the live preview as your guide rather than guessing. When you're done editing, click **SAVE** before navigating away. The **RESET** button only discards unsaved changes; it does not revert previously saved customizations. If you ever need to "start over," manually clear the fields and re-upload (or remove) the logo, then save. Finally, remember that printable receipts pick up data from each individual transaction at print time — there's no merchant-wide preview that includes a real customer's data. The preview on this page intentionally uses placeholder values (N/A, \$0.00) so you can focus on layout. When you actually print from a transaction's View Receipt action, the live transaction data is substituted into the same template. # Reporting Source: https://docs.ecrypt.com/dashboard/reporting ## Overview Reporting is where every payment, refund, void, capture, and adjustment in Ecrypt is auditable. The module gives you three lenses on your data: a flat **All Transactions** ledger for any date range, a **Batches** view that groups transactions by daily settlement, and a **Create/View Report** workflow for building, saving, exporting, and re-running custom column reports. Clicking any transaction anywhere in the module opens the same Transaction Detail panel used elsewhere in the dashboard, with full payment data and contextual actions. ## Navigation Open **Reporting** in the left sidebar to reveal three sub-pages: | Sub-page | URL | Purpose | | ------------------ | ------------------------------ | --------------------------------------------------------------------- | | All Transactions | `/reporting/all-transactions` | Flat ledger of every transaction in a date range | | Batches | `/reporting/batches` | List of daily settlement batches, drilldown to per-batch transactions | | Create/View Report | `?actions=view-report` (modal) | Saved custom-column reports + new report builder | *** ## Transactions A flat, filterable list of every transaction across every channel (Credit Card, Check, Subscriptions, Invoices, Hosted Payments — anything that produced a transaction record). ### Filter By A pinned **Transaction Date range** chip applies a default 7-day window. Click **FILTERS** to open the Table Filters panel: | Field | Notes | | ----------- | -------------------------------------------------------------------------------- | | Filter By | Column to filter on (Transaction Date, Amount, Status, Customer, ID, Type, etc.) | | Filter Type | Match mode — Range, Equals, Contains, etc. — depends on the chosen field | | Value | Range picker for dates/amounts; free text for IDs/customers | Click **+ ADD FILTER** to stack multiple filters and **APPLY FILTERS** to run them. **CLEAR FILTERS** removes everything (including the default date chip). ### Columns | Column | Notes | | ---------------- | ------------------------------------------------- | | ID | Transaction ID (numeric) | | Transaction Date | Date and time | | Amount | Dollar amount; negative for refunds | | Type | Sale / Refund / Auth / Credit / Void | | Account Data | Masked PAN or ACH identifier with card-brand icon | | Customer | Customer name (uppercase if not in Vault) | | Status | Approved / Declined / Settled | Click any row to open the **Transaction Detail Panel**. *** ## Transaction Detail Panel The same right-side slide-over used in Subscriptions and Invoices. The exact actions available depend on whether the transaction belongs to a subscription and whether the cardholder is already a Vault customer. ### Header * Status badge (e.g. **APPROVED**) * Transaction timestamp * **MERCHANT** — which merchant account ran the charge * **INITIATED BY** — channel (API KEY, dashboard user, etc.) * **Transaction #** — the transaction ID * *(If subscription)* **BILLED \[cycle]** chip, **NEXT PAYMENT DATE** chip, **Subscription ID** ### Info Row Chips * **RESPONSE** (Approved / Declined) * **APPROVAL CODE** * **CURRENCY** * **ENTRY MODE** (Keyed / Swiped / etc.) ### Card Visual Cardholder name, charge amount, masked card or ACH, expiration, brand logo. ### Body * **Billing Address** / **Shipping Address** * **More Info** — Subtotal, Tax, Surcharge, AVS Status, CVV Status (with info-icon explanations) * **Subscription Info** *(subscriptions only)* — Billing Cycle, Installments, Send Receipts * **Order information** — line items if captured ### Left Panel — MENU * **Payment Information** (default view) * **Transaction History** — shows the linked chain of this transaction (e.g. Sale → Refund) ### Left Panel — ACTIONS The list adapts to the transaction: | Action | When it appears | Effect | | --------------------- | ------------------------- | -------------------------------------------- | | Void Transaction | Unsettled transactions | Cancels before settlement | | View Receipt | Always | Opens customer-facing receipt | | Charge Again | Always | Re-runs the charge on the same card | | View Customer | Customer already in Vault | Jumps to the Vault record | | Add to customer vault | Customer not yet in Vault | Saves payment method to a new Vault customer | ### Left Panel — ACTIONS FOR SUBSCRIPTIONS Appears only for transactions that belong to a subscription: Subscription History, Pay Early, Cancel Subscription, Pause Subscription, Edit Subscription. See the Subscriptions guide for details. *** ## Batches A list of daily settlement batches. Each batch corresponds to a settlement cutoff (typically nightly at the processor's batch time). ### Columns | Column | Notes | | --------------- | -------------------------------------------------- | | ID | Internal batch record ID | | Settlement Date | Cutoff date and time of the batch | | Batch Number | Processor-assigned batch number | | Sales | Count of successful sale transactions in the batch | | Gross Amount | Sum of sale amounts before refunds | | Refunds | Count of refunds in the batch | | Voids | Count of voids in the batch | | Refund Amount | Sum of refund amounts (positive number) | | Net | Gross minus refunds = the net deposit | Click **FILTERS** to filter by any of the columns. ### Batch Drilldown Click the **Batch Number** in any row (or the row itself) to open `/reporting/batch?batch=[number]` which lists every transaction inside that batch in the same table format as All Transactions. The page has: * **← GO BACK TO BATCHES** breadcrumb * **Batch #\[number]** title * The transactions table with Status column showing **Settled** instead of Approved * Click any row to open the same Transaction Detail Panel > **Tip:** Use Batches to reconcile against bank deposits — the Net column corresponds 1:1 to the ACH funding deposit you'll see in your bank account, usually 1–2 business days after Settlement Date. *** ## Create/View Reports Opens the **View Reporting** modal — the entry point for both running existing saved reports and building new ones. ### View Reporting (run an existing report) | Element | Notes | | ------------------ | ------------------------------------------------------------------ | | Search bar | Filter the saved-report list by name | | Saved reports list | Radio-select from the named reports already saved on this merchant | | Date Range | Date window to apply when running the report | | View Report | Runs the selected report in-app on the chosen date range | | Export Report | Downloads the selected report as a file (CSV/Excel) | | Edit report | Re-opens the field/name editor for the selected report | Below the controls: **OR → Create A New Report** opens the New Report builder. ### View Report output A standard table page titled **Reporting - \[report name]** containing only the columns selected when the report was built. The page includes: * **← GO BACK TO REPORTING LIST** breadcrumb * **Export to report** button (top-right) to download * Standard pagination footer ### New Report builder | Field | Required | Notes | | --------------------------- | ------------ | ---------------------------------------------------------- | | Search for available fields | No | Filters the field checklist below | | All | No | Master checkbox that toggles every field | | Field checkboxes | At least one | Pick which columns the report includes | | Report Name | Yes | Label used to find the report later | | SAVE | — | Persists the report; it appears in the View Reporting list | | CANCEL | — | Discards without saving | #### Available Fields The field list spans every aspect of a transaction: **Identifiers** — Transaction Id, Merchant, Settlement Id, Settlement Number, Action **Status / payment method** — Status, Tender Type, Entry Mode, Payment Name, Payment Network, Payment Account, Payment Account Expiration **Amounts** — Amount, Authorization Amount, Captured Amount, Date Captured, Settled Amount, Date Settled, Voided Amount, Date Voided **Verification** — Authorization Code, AVS Response Code, AVS Response Text, CVV Response Code, CVV Response Text, Enhanced Data Qualified **Source** — Terminal Id, Terminal Label, Initiated by Username **Order data** — Order Id, Order Discount, Order Surcharge, Order Shipping, Order Tip, Order Tax, Order Total **Customer** — Customer Id, Customer Merchant Id, Customer First Name, Customer Last Name, Customer Company, Customer Phone Number, Customer Email Address **Billing address** — Billing Address Line 1, Line 2, City, State, Postal Code, Country **Shipping address** — Shipping Address Name, Line 1, Line 2, City, State, Postal Code, Country **Order metadata** — `OrderMetadata` plus any custom merchant-defined fields (prefixed `[*]` in the list, e.g. `[*] Dock Number`, `[*] Slip #`, `[*] Notes`, `[*] In-Person`, `[*] Invoice#`) > **Note:** The `[*]` custom fields are defined per merchant. The ones visible to you reflect this merchant's configuration and will differ for other accounts. *** ## Tips & Best Practices **Use All Transactions for ad-hoc lookups; use saved reports for repeating workflows.** If you find yourself filtering the same way every Monday morning, save it as a report so you can re-run it with one click and a fresh date range. **Reconcile against Batches, not All Transactions.** Bank deposits land on a settlement cadence. Use the Batches page's **Net** column to reconcile what hit your bank — All Transactions includes voids and pending charges that may never settle. **Stack filters instead of exporting and slicing.** The **+ ADD FILTER** button lets you AND multiple conditions (e.g. *Status = Declined* AND *Amount > \$100* AND *Transaction Date in last 7 days*). This is usually faster than exporting to Excel. **Name reports with intent, not content.** "Weekly settlement reconciliation" outlasts "Sale + Refund + Amount" because the second describes columns that may change, while the first describes the job-to-be-done. **Export Report uses the currently selected Date Range.** It does *not* use whatever date range you last used in All Transactions. Pick the date range in the View Reporting modal before clicking Export. **Transaction History on the detail panel is the audit trail.** When investigating a disputed transaction, open it and switch from Payment Information to Transaction History — every linked action (auth, capture, void, refund) shows in order with timestamps. **"Add to customer vault" turns one-off transactions into reusable customers.** When a card runs through POS/KEY but the cardholder isn't a Vault customer yet, you can retroactively save them straight from the transaction detail panel without re-entering data. **Custom `[*]` fields are powerful for industry-specific reporting.** If you have order metadata like Dock Number, Invoice#, or Slip # configured, include them in saved reports for operations or accounting teams who think in those terms. **Batches lists all batches in reverse chronological order.** The default view shows the last 10 — paginate or filter by Settlement Date to find a specific batch when you have a date in mind from your bank. # Security Settings Source: https://docs.ecrypt.com/dashboard/security-settings The Security Settings page controls which fields appear on your payment forms and which ones a payer must fill in before a transaction can be submitted. It's where you tune the balance between collecting enough data to verify a transaction (address verification, CVV, custom merchant fields) and asking for so much that customers abandon checkout. The page is titled **Virtual Terminal Fields** with the subtitle *"Set requirements for address verification settings and card security settings."* Every change you make here applies to the dashboard's payment forms (KEY, ACH, and other manual-entry flows) for the currently selected merchant account. *** ## Navigation From the left sidebar: **Settings → Fraud Prevention → Security Settings** *** ## Layout The page is organized into three side-by-side columns, each grouping a related set of fields. Every column has an **Activate All** link in its heading that toggles every checkbox in that column on at once — a quick way to enable an entire group without clicking each box individually. A **SUBMIT FILTERS** button in the top right saves your changes. ### Two Toggle Types Each field row has one or two checkboxes: | Checkbox | What it does | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | **Required** | The payer must enter a value in this field before they can submit the transaction. Empty submissions are rejected. | | **Displayed** | The field is shown on the form. If unchecked, the field is hidden entirely. | Some fields show only a **Required** checkbox — those are core address inputs that are always rendered on the form, so the only setting that matters is whether they're mandatory. Other fields show **both** checkboxes, meaning you can choose to hide them entirely (Displayed off), show but allow blank (Displayed on, Required off), or show and require (both on). *** ## Billing Information The cardholder's billing address fields. These are the inputs Ecrypt forwards to the issuer for AVS verification. | Field | Required | Displayed | Notes | | ------- | -------- | -------------- | ------------------------------------------------------------------------ | | Address | ✓ | (always shown) | Cardholder's street address. | | City | ✓ | (always shown) | Billing city. | | Zipcode | ✓ | (always shown) | ZIP / postal code — the primary AVS input. | | State | ✓ | (always shown) | Billing state or province. | | CVV | ✓ | (always shown) | Card Verification Value from the back (or front, for Amex) of the card. | | Country | ✓ | ✓ | Billing country. Can be hidden if all your customers are in one country. | | Company | ✓ | ✓ | Cardholder's company name. | | Phone | ✓ | ✓ | Contact phone number. | | Email | ✓ | ✓ | Contact email — also used for emailed receipts. | **Tip:** Zipcode + Address are the two AVS workhorses. Even on otherwise lightweight forms, requiring at least the Zipcode catches most stolen-card fraud at the issuer level. ## Shipping Information A second address block for the customer's shipping/delivery address. Useful when goods are being shipped to a different location than the billing address. | Field | Required | Displayed | Notes | | ------- | -------- | -------------- | ------------------------------------------------- | | Address | ✓ | (always shown) | Shipping street address. | | City | ✓ | (always shown) | Shipping city. | | Zipcode | ✓ | (always shown) | Shipping ZIP / postal code. | | State | ✓ | (always shown) | Shipping state or province. | | Country | ✓ | ✓ | Shipping country. | | Name | ✓ | ✓ | Recipient name (often different from cardholder). | Whether the shipping block appears on the form at all is controlled by the "Billing address same as shipping" toggle inside the payment forms themselves; this page controls what happens *inside* the shipping block when it's shown. ## Merchant Defined Fields The custom fields you've created in **Settings → Terminal Settings → Defined Fields** show up here, each with its own Required and Displayed checkboxes. You control whether each merchant-defined field is shown on the payment form (Displayed) and whether the user can submit without filling it in (Required). This is the connection point between the **field definitions** and the **payment forms** that actually use them — defining a field doesn't automatically place it on the form; you also have to check **Displayed** here. *** ## Activate All Each of the three columns has an **Activate All** link beside its heading. Clicking it checks every checkbox in that column. Useful when you're standing up a brand-new merchant and want maximum data capture, or when you're cloning settings from a stricter merchant. You can then uncheck individual boxes to fine-tune. ## Save Click **SUBMIT FILTERS** in the top right to persist all changes. Until you click Submit, your edits are local to the form and won't affect live payment pages. *** ## Tips & Best Practices Start strict, then loosen. The cost of asking for too much data is some customers abandoning checkout; the cost of asking for too little is fraud chargebacks and missed AVS matches. For most merchants, **Address, City, Zipcode, State, and CVV** should all be Required — these give you the strongest verification at the lowest cost in friction. Country, Company, Phone, and Email can usually be left optional (Displayed but not Required) unless you have a business reason to mandate them. The **Shipping Information** block is only relevant if you actually ship goods. If you're a service business, restaurant, or anything else where there's no physical delivery, leave the shipping fields unchecked entirely and the shipping block won't add any friction to checkout. Conversely, if you ship to a different address than the cardholder's billing address frequently, requiring **Name** on the shipping side keeps your fulfillment data clean. Use **Merchant Defined Fields** when you need to capture business-specific data alongside every transaction — invoice numbers, customer references, table numbers, route IDs — without forcing those onto the standard address fields. Remember that defining a field in **Terminal Settings → Defined Fields** only puts it in the catalog; you have to check **Displayed** here to actually surface it on your payment forms. If a custom field never shows up at point of sale, this is the first place to check. The line between **Required** and **Displayed** is the most important distinction on this page. Marking something **Displayed but not Required** is a strong default — it gives the payer the chance to enter the data without blocking checkout if they choose not to. Marking it **Required** is a hard gate. Marking it **neither** removes it from the form entirely. Use Required sparingly; over-requiring is the leading driver of cart abandonment on payment forms. Finally, settings here are per-merchant. If you operate multiple merchants and want the same security profile across all of them, you'll need to configure each merchant individually. Switch merchants in the top-left "Your Merchant Accounts" picker and repeat. There's no copy-from-merchant shortcut on this page (unlike the **Copy Permissions from Another Employee** option in User Management). # Subscriptions Source: https://docs.ecrypt.com/dashboard/subscriptions ## Overview The Subscriptions module powers recurring billing in Ecrypt. Use it to charge customers automatically on a defined cadence — daily, weekly, monthly, quarterly, annually, and more — using either their saved credit card or ACH account. Subscriptions support optional installment plans, automated email receipts, "skip first payment" trials, and full lifecycle management including pause, cancel, edit, and early payment. Key capabilities: * 11 built-in billing cycles ranging from Daily to Annually, including semi-monthly variants * Use an existing Customer Vault record or create a new customer inline * Credit card or ACH as the recurring payment method * Installment billing with a configurable number of payments * Pause, cancel, edit, or charge a subscription early at any time * Real-time KPIs (Successful Payments, New Subscriptions, Declined Payments) with period-over-period change * Full payment history per subscription and aggregated across all subscriptions *** ## Navigation Subscriptions lives in the left sidebar under **APPS → Subscriptions**, which expands to three sub-sections: | Sub-section | Path | Purpose | | --------------------- | ---------------------------------- | ----------------------------------------------------- | | **Dashboard** | `/subscriptions/dashboard` | KPIs + upcoming payments in a chosen date range | | **Payments** | `/subscriptions/payments` | Every recurring charge attempt, success or failure | | **All Subscriptions** | `/subscriptions/all-subscriptions` | The complete list of subscriptions filtered by status | Subscriptions can also be created from the sidebar's **ACTIONS → Add Subscriptions** quick action. *** ## Subscriptions → Dashboard The Dashboard opens with three KPI cards and a date-filtered table of upcoming subscription payments. ### KPI Cards Each card shows a count plus an arrow indicator and percentage compared to the previous 7-day period. | Card | Description | | ----------------------- | -------------------------------------------------------- | | **SUCCESSFUL PAYMENTS** | Number of recurring charges that succeeded in the period | | **NEW SUBSCRIPTIONS** | Count of subscriptions created in the period | | **DECLINED PAYMENTS** | Number of failed recurring charges in the period | The colored percentage indicates change versus PREV. 7 DAYS — green up-arrow for increase, red down-arrow for decrease. ### Date Range Selector | Control | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Next Payment Date Range** chip | Defaults to the current rolling 7-day window (e.g., 05-21-26 — 05-27-26). Click to open a date range picker. | | **PAYMENTS** button | Top-right blue button — jumps to the Subscriptions → Payments page | ### Filter Panel Click **FILTERS** to expand the filter bar; **CLEAR FILTERS** resets it. An active filter chip appears next to **Filter By:** (e.g., "Next Payment Date range : 05/21/2026 - 05/27/2026"). ### Upcoming Payments Table | Column | Description | | ------------------- | ------------------------------------------------------------- | | **Next Payment** | Date the next recurring charge will run | | **Billing Cycle** | Cadence (Daily, Weekly, Monthly, etc.) | | **Last Payment** | Date the most recent charge was attempted | | **Status** | Subscription status (Active, Cancelled, Suspended, Completed) | | **Account Data** | Masked card or ACH account (with brand logo) | | **Customer** | Customer name from the vault | | **Created Date** | When the subscription was set up | | **Subscription ID** | Unique subscription UUID | Clicking any row opens the **Subscription Detail panel** (see below). *** ## Subscription Detail Panel Clicking a subscription row anywhere in the Subscriptions module opens a comprehensive detail panel. ### Header | Element | Description | | ---------------------- | --------------------------------------------------- | | **Status badge** | SETTLED, PENDING, DECLINED, etc. (color-coded) | | **Timestamp** | Date and time of the most recent payment | | **Merchant** | Merchant account (e.g., MIAMI) | | **Initiated By** | User or API key that created the subscription | | **Transaction #** | Latest transaction ID | | **Billing badge** | Blue chip: "BILLED DAILY" / "BILLED MONTHLY" / etc. | | **Next Payment badge** | Blue chip: "NEXT PAYMENT DATE: \[DATE]" | | **Subscription ID** | Full UUID (gold/highlighted) | ### Info Row Chips | Chip | Example | | ----------------- | -------- | | **RESPONSE** | APPROVED | | **APPROVAL CODE** | 123456 | | **CURRENCY** | USD | | **ENTRY MODE** | KEYED | ### Card Visual A large card-shaped panel shows: * Customer name (e.g., JJ TEST) * Payment Amount (large dollar amount) * Card Number (masked, e.g., 543111\*\*\*\*\*\*1111) * Date (expiration MM/YY) * Card brand logo (MasterCard, Visa, etc.) ### Body Sections | Section | Fields | | --------------------- | -------------------------------------------------------------------------------------- | | **Billing Address** | Address text | | **Shipping Address** | Address text (or N/A) | | **More Info** | Subtotal, Tax, Surcharge, AVS Status, CVV Status | | **Subscription Info** | Billing Cycle, Installments (with tooltip showing total count), Send Receipts (Yes/No) | | **Order Information** | Optional order metadata or N/A | ### Left Panel — MENU & ACTIONS The left sidebar of the detail panel groups actions into three buckets: **MENU** | Item | Description | | ----------------------- | ------------------------------------------------------------- | | **Payment Information** | The main detail view (default) | | **Transaction History** | Jumps to Subscriptions Payments filtered to this subscription | **ACTIONS** (general transaction actions) | Action | Description | | ---------------------- | ---------------------------------------- | | **Refund Transaction** | Refund the most recent charge | | **View Receipt** | Open the printable/emailable receipt | | **Charge Again** | Run a one-off charge using the same card | | **View Customer** | Jump to the customer's vault profile | **ACTIONS FOR SUBSCRIPTIONS** (subscription lifecycle) | Action | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | **Subscription History** | Opens the list of all charges run on this subscription (Payment Date, Account Data, Customer, Amount, Status, Subscription ID) | | **Pay Early** | Triggers the next scheduled charge immediately | | **Cancel Subscription** | Permanently cancels (sets status to Cancelled) | | **Pause Subscription** | Temporarily suspends recurring charges | | **Edit Subscription** | Opens the edit form (amount, tax, payment method) | ### Edit Subscription Form Opened from the **Edit Subscription** action. The right side shows a live **Pricing Summary** (Amount, Estimated tax, Surcharge, Total). | Field | Required | Notes | | ---------------------------- | -------- | ----------------------------------------------- | | **Amount** | Yes | Recurring charge amount in USD | | **Tax (Exclusive)** | No | Percentage applied on top of the amount | | **+ ADD NEW PAYMENT METHOD** | — | Adds a new card or ACH to the customer's wallet | | **Current Card tile** | — | Shows existing card; click **UPDATE** to edit | | **Billing Address** | — | Shown with **UPDATE** link | > **Note:** A warning banner appears for debit cards: "Surcharge removed. Debit cards are not eligible for surcharge fees." Click **EDIT SUBSCRIPTION** to save changes. ### Pause / Cancel / Pay Early Confirmation Panels These three actions each open a confirmation panel showing the subscription summary (status badge, billing badge, next payment date, subscription ID, info row chips, subscription amount, card details, subscription info) plus a single primary button: | Action | Confirmation Button | | ------------------- | -------------------------- | | Pause Subscription | **PAUSE SUBSCRIPTION** | | Cancel Subscription | **CANCEL SUBSCRIPTION** | | Pay Early | **PAY SUBSCRIPTION EARLY** | *** ## Subscriptions → Payments A table of every recurring charge attempt — both successes and declines — across all subscriptions. ### Columns | Column | Description | | ------------------------ | ------------------------------------------------------- | | **Next Payment** | Next scheduled charge date (N/A if completed/cancelled) | | **Billing Cycle** | Cadence at time of charge | | **Payment Date** | When this charge was attempted | | **Status** | Success (green) or Declined (red) | | **Account Data** | Masked card/ACH with brand logo | | **Customer** | Customer name | | **Amount** | Charge amount in USD | | **Subscription Created** | Original subscription creation date | | **Subscription ID** | Unique subscription identifier | ### Filter Panel The **Filter By** dropdown supports filtering on any column: | Filter Field | | -------------------- | | Next Payment | | Billing Cycle | | Payment Date | | Status | | Account Data | | Customer | | Amount | | Subscription Created | | Subscription ID | Workflow: select **Filter By** → choose **Filter Type** (equals, greater than, contains, etc.) → enter **Value** → **+ ADD FILTER** (to stack) → **APPLY FILTERS**. Clicking any row opens the same Subscription Detail panel described above. *** ## Subscriptions → All Subscriptions The master list of every subscription, scoped by status. ### Status Filter Tabs (top right) | Tab | Description | | ------------- | --------------------------------------- | | **Active** | Currently recurring (default) | | **Cancelled** | Permanently ended | | **Suspended** | Paused — no charges running | | **Completed** | Installment plans that have finished | | **All** | Every subscription regardless of status | A **PAYMENTS** button (top right, blue) jumps to the Subscriptions → Payments view. ### Columns | Column | Description | | ------------------- | ------------------------------------------------------- | | **Next Payment** | Next scheduled charge date | | **Billing Cycle** | Cadence | | **Last Payment** | Most recent charge date | | **Status** | Active / Cancelled / Suspended / Completed | | **Account Data** | Masked payment method | | **Customer** | Customer name | | **Created Date** | Subscription start (sortable — click the column header) | | **Subscription ID** | Unique UUID | The **Filter By:** chip shows the active status filter (e.g., "Status equals : Active") and can be cleared via the red X. *** ## Creating a Subscription — Add Subscriptions Action Available in the sidebar under **ACTIONS → Add Subscriptions** (or by URL `?actions=add-subscriptions`). ### Step 1 — Choose Customer The modal opens with the question "Is this a new or existing customer?" | Option | Action | | ----------------------- | -------------------------------------------------------------------- | | **NEW CUSTOMER** button | Creates a new customer inline (opens the standard Add Customer form) | | Search box (below "OR") | Type to find an existing vault customer; click a result to select | ### Step 2 — Build the Subscription After selecting a customer, the full subscription form appears. #### Billing Cycle (required) Dropdown with 11 options: | Value | | -------------------------- | | Daily | | Weekly | | Bi-Weekly | | Semi-Monthly (1st & 15th) | | Semi-Monthly (15th & Last) | | Monthly | | Monthly (1st) | | Monthly (Last) | | Quarterly | | Semi-Annually | | Annually | #### Core Fields | Field | Required | Notes | | --------------------- | -------- | ----------------------------------------------- | | **Amount** | Yes | Recurring charge amount in USD (default \$0.00) | | **Tax (Exclusive)** | No | Percentage applied on top of the amount | | **Next Payment Date** | Yes | Date picker; defaults to today | #### Payment Method The customer's existing wallet cards are shown as a tile with an **UPDATE** badge. The **Billing Address** below shows with an **UPDATE** link. To add a new card or ACH account, click **+ ADD NEW PAYMENT METHOD** to expand: | Field | Required | Notes | | ---------------------- | -------- | ------------------------ | | **Customer Wallet** | Yes | Radio: Credit Card / ACH | | **Name On Card** | Yes | Cardholder full name | | **Credit Card Number** | Yes | 15–16 digit card number | | **Expiration Date** | Yes | MM/YY format | | **Street Address** | Yes | Billing street | | **City** | Yes | Billing city | | **State** | Yes | Billing state | | **Zip code** | Yes | Billing ZIP | (Switching to **ACH** replaces card fields with Name On Account, Account Number, Routing Number.) Click **CANCEL ADDING NEW PAYMENT METHOD** to collapse the form. #### Subscription Options | Option | Default | Notes | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **☐ Installments** | Off | *"Enables installment billing, charging the subscription amount across a set number of payments."* When checked, a **Number of Installments** field appears. | | **☑ Send Receipts** | On | *"Enables email receipts for all recurring subscription payments."* When checked, an **Email** field is shown and pre-filled from the customer profile. | | **☐ Skip First Payment** | Off | *"When enabled, the first subscription payment is skipped and billing begins with the next scheduled cycle."* Useful for free-trial scenarios. | ### Pricing Summary (right panel) Updates in real time as you change Amount and Tax: * Amount * Estimated tax * Surcharge * **Total** (large, highlighted) ### Submit Click **ADD SUBSCRIPTION** (large blue button) to create the subscription. The new record appears immediately in All Subscriptions and is included in the next Dashboard refresh. *** ## Tips & Best Practices **Choosing the Right Billing Cycle.** Use Semi-Monthly variants (1st & 15th or 15th & Last) for payroll-aligned subscriptions. Use Monthly (1st) or Monthly (Last) when you need charges to land predictably on the same day each month rather than 30 days from the start date. For consumer subscriptions, Monthly or Annually is the most common. **Installments vs. Open-Ended.** Leave Installments unchecked for ongoing subscriptions (gym memberships, SaaS). Check Installments and set Number of Installments to convert a large one-time charge into a fixed payment plan (e.g., $1,200 over 12 monthly installments of $100). **Skip First Payment for Trials.** Combine Skip First Payment with a future Next Payment Date to implement a free trial. Billing begins on the next scheduled cycle date. **Pause vs. Cancel.** Pausing keeps the subscription record and payment method intact so you can resume later. Cancel is permanent — if the customer returns, you'll need to create a new subscription. **Pay Early for Catch-Up.** Use Pay Early when a customer wants to settle their next installment ahead of schedule, or when you need to recover a previously declined charge without waiting for the next cycle. **Watching Declined Payments.** The Declined Payments KPI on the Dashboard is your early warning for failing recurring charges (expired cards, insufficient funds, fraud blocks). Drill into Subscriptions → Payments and filter Status = Declined to triage. **Date Range for the Dashboard.** The default 7-day window is great for daily ops. Widen the range to 30 or 90 days during monthly retention reviews or churn analysis. **Editing the Card Without Recreating the Subscription.** Use Edit Subscription → Update on the card tile (or + Add New Payment Method) when a customer's card is replaced or expired. The subscription continues uninterrupted. **Sortable Created Date.** In All Subscriptions, the Created Date column header has a sort arrow. Click to flip between newest-first and oldest-first to spot recent signups or long-tenured customers. **Transaction History Shortcut.** The Transaction History menu item inside the detail panel takes you to Subscriptions → Payments filtered to that subscription's charges — handy for explaining a billing dispute to a customer. **Surcharge & Debit Cards.** Ecrypt automatically removes surcharge fees for debit cards (a banner warns you in the Edit Subscription form). Don't try to override this — surcharging debit cards violates card network rules in most US jurisdictions. # Surcharging Source: https://docs.ecrypt.com/dashboard/surcharging ## Overview Surcharging lets you add a small fee to credit card transactions to recover some of the processing costs you pay when a customer chooses to pay by credit card. Instead of absorbing card fees as a cost of doing business, you can pass a portion of them on to the cardholder at the time of payment. Surcharging on ECRYPT is built to keep you compliant with Card Brand rules and state law. The platform enforces a maximum rate, automatically blocks surcharges where they are not allowed, and only applies them to eligible card types. You stay in control of when a surcharge is applied, while ECRYPT handles the compliance guardrails behind the scenes. ## What Is Surcharging? A surcharge is a fee added to a transaction when a customer pays with a credit card. It is calculated as a percentage of the sale and is intended to offset the interchange and processing fees associated with accepting that card. Surcharging is different from a convenience fee or a service fee. A surcharge specifically recovers credit card acceptance costs, applies only to credit cards, and is governed by Card Brand rules and state law. Because of this, ECRYPT applies a set of built-in controls so a surcharge is only ever added when it is permitted. ## How ECRYPT Keeps You Compliant Surcharging is a regulated practice. To protect your business, ECRYPT enforces the following rules automatically on every eligible transaction. ### Maximum surcharge of 3.00% The surcharge rate on ECRYPT can never exceed **3.00%** of the transaction amount. This ceiling is enforced by the platform, so a surcharge above 3.00% cannot be configured or charged. Surcharges are meant to offset your processing costs, not to generate additional revenue. ### Credit cards only (debit and ACH are never surcharged) Surcharges may only be applied to credit card transactions. Debit cards and ACH (bank account) payments are never surcharged, even when a debit cardholder selects "credit" at checkout. To enforce this, ECRYPT runs a **BIN lookup** on the card at the time of the transaction. The BIN (the first digits of the card number) identifies the card type. If the card is identified as a debit or prepaid card, or if the payment is an ACH transaction, the surcharge is automatically removed before the customer is charged. This happens behind the scenes across every payment channel, so you never need to check card types yourself. ### Surcharging follows your state's laws Some states do not allow surcharging, and others permit it only with specific restrictions. If surcharging is not legal in your state, ECRYPT will not activate it on your account. This keeps you on the right side of state law without requiring you to track the rules yourself. Surcharge laws vary by state and change over time. ECRYPT's controls are designed to help you stay compliant, but they are not a substitute for legal advice. Consult legal counsel about the requirements that apply to your business. ## Activating Surcharging Surcharging is activated **by request only** and cannot be turned on by the merchant from within the dashboard. To enable it on your account, contact your ECRYPT representative. Before activation, ECRYPT confirms that surcharging is permitted in your state; if it is not, the feature will not be turned on. Once surcharging is active on your account, you decide when it applies. You can choose to surcharge on some transactions and not others, giving you full control over how and when the fee is presented to your customers. ## Where Surcharging Is Available Once enabled, surcharging works across all of the ways you accept payments on ECRYPT: | Channel | Description | | --------------- | ------------------------------------------------------------- | | Key Transaction | Manually keyed credit card payments entered by your team | | Cloud Terminals | In-person, card-present payments taken on a physical terminal | | Hosted Payments | The ECRYPT-hosted payment page customers complete themselves | | Payment Links | Shareable links that let customers pay from any device | | Invoicing | Branded invoices sent to customers for payment | | API | Payments processed through your own integration | In every channel, the same compliance controls apply: the 3.00% cap, the BIN lookup that excludes debit and ACH, and the state-law check. ## Your Responsibility: Notifying Customers Even though ECRYPT handles the technical compliance controls, Card Brand rules require **you, the merchant, to clearly disclose the surcharge to your customers.** This is your responsibility, not something ECRYPT can do on your behalf. To stay compliant, make sure you: * Notify customers that a surcharge applies **before** they complete payment, at both the point of entry (for example, your store entrance or website) and the point of sale (the checkout screen). * Show the surcharge as a **separate line item** on the receipt so the customer can see the fee clearly, distinct from the purchase total. * Present the surcharge as a **percentage of the sale**, consistent with the rate configured on your account. Clear, upfront disclosure protects you from disputes and chargebacks and keeps you compliant with both Card Brand rules and state requirements. ## Tips & Best Practices **Disclose early and often.** The most common cause of surcharge-related disputes is a customer who did not realize a fee was being added. Visible signage and on-screen notices reduce confusion and chargebacks. **Surcharge consistently.** Because you control when surcharging applies, decide on a clear policy for when you add the fee and apply it the same way each time. Consistency is easier to explain to customers and to defend if questioned. **Let the platform do the compliance work.** You do not need to manually check whether a card is debit or credit, whether the 3.00% cap is met, or whether your state allows surcharging. ECRYPT enforces all of these automatically once the feature is active. **Reach out to enable it.** Surcharging cannot be self-activated. If you want to start surcharging, contact your ECRYPT representative, who will confirm eligibility and turn it on for your account. # Velocity Filter Source: https://docs.ecrypt.com/dashboard/velocity-filter The **Velocity Filter** is a rate-limiting tool that caps how many transactions the gateway will accept in a given window of time. If the threshold is exceeded, additional transactions are automatically declined until the window resets. Velocity filtering is one of the most basic — but most useful — defenses against **card testing** (sometimes called "auth scrub") attacks, where a bad actor uses an ecommerce checkout, hosted payment page, or exposed API key to validate large batches of stolen card numbers in rapid succession. **Path:** Settings → Fraud Prevention → Velocity Filter *** ## Understanding Card Testing / Auth Scrub Attacks Stolen card data is a commodity. Before reselling or using cards, criminals need to know which ones are still live (not yet cancelled, not flagged, with sufficient available credit). The cheapest way to find out is to push small auths through a real merchant's checkout and watch the response codes — approvals are valid, declines are dead. This activity is called **card testing**, and it's typically run by automated bots that hit a checkout page or payment API hundreds or thousands of times in a short period. The damage to the merchant is real even though the dollar amount per attempt is tiny: * Authorization, network, and gateway fees pile up — many processors charge per attempted transaction whether approved or declined. * Chargebacks follow when legitimate cardholders discover the unauthorized charges. * Decline ratios spike, which can trigger network compliance programs (Visa VAMP, Mastercard ECM, etc.) and put the merchant at risk of fines or termination. * Approved test auths become real transactions that must be refunded or end up as fraud chargebacks. ### How a velocity filter helps A velocity filter sets a ceiling. For example, no more than 5 transactions in any 1-minute window. If an attacker's bot starts pushing 50 attempts a minute, the gateway only accepts the first 5 and declines the rest. The attack doesn't stop, but the **rate of damage is capped** and the abnormal pattern becomes visible quickly in reporting, giving the merchant time to investigate and respond. > **Important caveat:** The velocity filter is a containment tool, not a prevention tool. It does **not** actively block card-testing attacks — the attacker's traffic still reaches the gateway, and the attempts that fit within the threshold will still be authorized and counted. What the filter does is stop the bleed early so the merchant doesn't wake up to thousands of failed auths and the fees that come with them. *** ## Page Layout The Velocity Filter page is a single form with two inputs and a submit button. ### Header * **Title:** Velocity Filter * **Subtitle:** "Set the amount of transactions that can be processed though the gateway" * **Description:** "The velocity filter allows you to specify a threshold for the number of transactions that can be processed in a given time frame." ### Notes block A reminder that reads: > "If you exceed the number of transactions for the given timeframe below, your transactions will decline. Reach out to your account representative for additional support." ### Form Fields | Field | Type | Description | | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- | | **Allow** | Number input | The maximum number of transactions allowed within the selected time window. Transactions over this limit are declined. | | **How Many Minutes** | Dropdown | The size of the rolling time window. Options: **Per 1 Minute**, **Per 3 Minutes**, **Per 5 Minutes**, **Per 10 Minutes**. | Helper text under each field: * Under **Allow:** "Set the maximum transactions allowed within the Time Period. Transactions over this limit will be declined." * Under **How Many Minutes:** "Define the time in minutes for the Transaction Limit. Transactions exceeding the limit within this period will be declined." ### Submit * **SUBMIT FILTERS** — saves the configuration. The new threshold takes effect immediately for the active MID. *** ## Configuring the Filter 1. Navigate to Settings → Fraud Prevention → Velocity Filter. 2. In **Allow**, enter the maximum number of transactions to permit per window. 3. In **How Many Minutes**, select the window length (1, 3, 5, or 10 minutes). 4. Click **SUBMIT FILTERS**. The setting is per MID — if you operate multiple locations, configure the filter on each MID individually via the location switcher in the top-left. ### Choosing a threshold Pick a number that comfortably exceeds your peak legitimate volume so good customers aren't accidentally declined, but low enough that a card-testing burst gets capped quickly. A few rules of thumb: * **Low-volume merchants** (a handful of transactions per hour): 2-5 per 1 minute is usually safe. * **Medium-volume merchants:** Look at your busiest minute over the last 90 days, then add headroom (e.g., 2x the peak). * **High-volume / flash-sale merchants:** A short window like 1-3 minutes with a high allow count works better than a long window with a small allow count, because long windows can starve legitimate buyers during traffic spikes. If you start seeing legitimate customer complaints about declines, loosen the threshold. If you see suspicious decline spikes in reporting, tighten it. *** ## Preventing Card Testing Attacks (Beyond Velocity Filtering) Because the velocity filter only *contains* attacks, it should be paired with measures that *prevent* the bot traffic from reaching the gateway in the first place. Recommended controls: * **Add reCAPTCHA (or hCaptcha / Turnstile) to your checkout page.** This is the single most effective control against automated card-testing bots. Google reCAPTCHA v3 runs silently in the background and scores each visitor; reCAPTCHA v2 shows the familiar "I'm not a robot" challenge. Either will stop the vast majority of unsophisticated bots before a card number ever gets submitted. * **Use Ecrypt's Hosted Payment Page or Customer Vault tokenization** instead of accepting raw card numbers on your own form. The hosted page benefits from Ecrypt's own bot-mitigation controls. * **Require AVS and CVV** on your checkout. Mismatches add friction for attackers, who often have card numbers but not full billing details. (Configure under Settings → Fraud Prevention → Security Settings.) * **Block known-bad IPs at the WAF or CDN layer.** Cloudflare, AWS WAF, and similar services maintain bot-traffic signatures and let you challenge or block suspicious sources. * **Use Ecrypt's IP Allowed list** when transactions should only originate from a known set of IPs (e.g., internal POS systems or a single ecommerce host). * **Rate-limit at the application layer.** Limit submissions per IP, per session, and per device fingerprint on your own checkout — don't rely solely on the gateway's velocity filter. * **Don't expose your Private API key in client-side code.** Public keys are designed for browser use; private keys must stay on your server. A leaked private key gives attackers a direct API path that bypasses your checkout entirely. * **Monitor decline patterns daily.** A sudden spike in declines — especially from `Do Not Honor`, `Invalid Card Number`, or `Expired Card` codes — is a strong card-testing signal. Catching it within hours instead of days dramatically limits the damage. * **Set up webhook alerts** for declined transactions so you're notified in near real time when something abnormal starts. *** ## What to Do If You're Being Attacked 1. **Tighten the velocity filter immediately** — set Allow to a very low number (e.g., 1) and the window to 1 minute. This nearly halts the attack. 2. **Rotate your API keys** in case a private key is compromised. (Settings → Developer Tools → API Keys.) 3. **Enable IP Allowed list restrictions** if your traffic should only come from known IPs. 4. **Add or strengthen reCAPTCHA** on your checkout. 5. **Contact your Ecrypt account representative** — they can apply additional gateway-level controls and help review the activity. 6. **Review and refund any approved test transactions** so they don't become chargebacks. *** ## Tips & Best Practices * **Always set some velocity threshold** — even a generous one. An unconfigured velocity filter is the difference between a contained incident and a five-figure surprise on your statement. * **Treat the velocity filter as a backstop, not a strategy.** Real prevention lives upstream at your checkout (CAPTCHA, hosted payments, key hygiene). * **Revisit the threshold after seasonal changes.** Black Friday, end-of-month billing runs, and product launches can all push legitimate volume above a previously safe ceiling. * **Document the configuration with your team** so support staff don't troubleshoot "mysterious declines" that are actually working as designed. * **Combine with Security Settings.** Requiring CVV, AVS, and other billing fields raises the cost of each test attempt and reduces the value of your checkout as a card-validation target. * **Watch reporting after configuring.** The Reporting module's decline summaries will show whether the filter is catching anything — if you see steady decline volume at exactly your threshold, you're likely already under attack. # Webhooks Source: https://docs.ecrypt.com/dashboard/webhooks Webhooks let Ecrypt push real-time event notifications to your own systems. Whenever a configured event happens — a card transaction is approved, a subscription is cancelled, a new customer is created — Ecrypt sends an HTTPS POST request to a URL you control, with the event details in the body. You can then use those notifications to update your database, send your own emails, fire downstream automations, or sync state with other tools. This guide covers the Webhook Management page where you create, edit, and delete webhook endpoints, including the events you can subscribe to and the custom headers you can attach to outgoing requests. *** ## Navigation From the left sidebar: **Settings → Developer Tools → Webhook Management** The page is split into two sections stacked vertically: 1. **Create Webhook** — the form at the top where you configure a new webhook. 2. **Webhook's Table** — the list of webhooks you've already created. *** ## Create Webhook The form at the top of the page is used to register a new webhook endpoint. ### Webhook Info | Field | Required | Notes | | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Webhook URL | Yes | The destination for outgoing webhook requests. Tooltip on the info icon: *"Enter a valid HTTPS URL where webhook POST requests will be delivered."* HTTPS is required. | ### Event Selection Checkboxes grouped into three categories. Tick the events you want this webhook to receive — leaving a category unchecked means Ecrypt won't fire for that event. | Group | Events | | ------------- | ----------------------------- | | Transactions | Approved, Declined | | Subscriptions | Created, Suspended, Cancelled | | Customers | Created | A single webhook can subscribe to any combination of events from any number of groups. ### Custom Headers Optional HTTP headers Ecrypt will attach to every outgoing webhook request to this URL. Useful for authentication (e.g., a shared secret in `Authorization`), routing, or anything else your endpoint needs to validate the request. | Field | Notes | | ----------- | ------------------------------------------------------------------------ | | Header | The header name (e.g., `Authorization`, `X-API-Key`). | | Value | The header value (e.g., `Bearer abc123`). | | +ADD button | Adds another Header/Value row so you can attach multiple custom headers. | ### Save Click **GENERATE WEBHOOK** to register the endpoint. It will appear in the Webhook's Table below. *** ## Webhook's Table A list of every webhook you've registered. | Column | Notes | | | | ------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------- | | Status | **ENABLED** when the webhook is active and delivering events. | | | | URL | The destination URL you registered. | | | | Events | A compact summary of the events the webhook is subscribed to, grouped by category (e.g., \`TRANSACTION - Approved & Declined | SUBSCRIPTION - Created & Deleted | CUSTOMERS - Created\`). | | Action | **Edit** and **Delete**. | | | Pagination controls (rows per page, page arrows) appear at the bottom right. ### Edit a Webhook Clicking **Edit** scrolls the top form into "Edit" mode. The heading changes to "Edit \[URL]" and the form is pre-populated with the webhook's current settings: * **Webhook URL** is read-only (greyed out) — you cannot change the destination once created. Delete and re-create with a new URL if you need to move endpoints. * **Event checkboxes** are pre-checked according to the webhook's current subscription. Toggle as needed. * **Custom Headers** can be added or removed. Buttons: **SAVE WEBHOOK** to apply changes, **CANCEL** to discard them. ### Delete a Webhook Clicking the red **Delete** opens a confirmation dialog: > Are you sure you want to delete this webhook? Buttons: **DELETE** / **CANCEL**. Deletion is immediate. Ecrypt will stop sending events to the URL the moment you confirm. *** ## How Webhooks Work When a subscribed event happens on your account, Ecrypt makes an HTTPS POST request to the Webhook URL with the event payload in the body. If you've configured Custom Headers, they're attached to every request. Your endpoint should: 1. Respond with a `2xx` status code as quickly as possible to acknowledge receipt. 2. Verify the request is authentic (typically via a shared secret in a custom header). 3. Process the event asynchronously after acknowledging — don't do heavy work inside the request itself. Failures to deliver (non-`2xx` responses, timeouts, network errors) are handled by Ecrypt's delivery system; your endpoint should be designed to handle the same event arriving more than once (idempotency). *** ## Tips & Best Practices Always use **HTTPS** for your webhook URL — the form requires it, and for good reason. Webhook payloads can include transaction amounts, customer identifiers, and subscription state, which should not transit the public internet in cleartext. Treat webhooks as untrusted input on your endpoint. Anyone who can hit your URL could try to forge an event, so use a **Custom Header** with a strong shared secret (or a signed token) and verify it on every incoming request before acting on the payload. Reject requests that don't match. Subscribe only to the events you actually need. A webhook subscribed to every event will receive many more requests than one focused on, say, just "Transactions → Approved" — and every extra request is one more thing your endpoint has to acknowledge. If you only care about successful sales, leave Declined unchecked; if you only care about cancellations, skip Created and Suspended. Design your endpoint for **at-least-once** delivery. Webhooks can be retried, network blips can cause duplicates, and you should be able to handle the same event arriving twice without doing the work twice. A common pattern is to record the event's transaction ID (or subscription ID, customer ID) the first time you process it and skip subsequent deliveries with the same ID. When you need to change your endpoint URL (e.g., moving from staging to production, or to a new domain), remember that you can't edit the URL on an existing webhook — you'll need to delete the old one and create a new one. Plan the cutover carefully so you don't miss events during the swap, or run both endpoints in parallel for a brief window and de-duplicate on your side. Finally, the **Status** column will show `ENABLED` for healthy webhooks. If you see anything else, or if you suspect events aren't being delivered, double-check the URL is reachable from the public internet, the TLS certificate is valid, and your endpoint is returning `2xx` quickly enough that Ecrypt doesn't time out. # WooCommerce Source: https://docs.ecrypt.com/dashboard/woo-commerce Accept credit and debit card payments in your WooCommerce store with the ECRYPT plugin. ECRYPT's WooCommerce plugin lets you accept credit and debit card payments directly in your store. It supports online payments, native refunds, and a secure customer wallet for storing cards on file. Available on the WordPress plugin directory. ## Requirements | Requirement | Minimum Version | | --------------- | --------------- | | ECRYPT account | -- | | SSL certificate | -- | | WordPress | 5.6+ | | WooCommerce | 3.5+ | | PHP | 7.4+ | ## Installation 1. Confirm your store meets the requirements above. 2. Download the [ECRYPT plugin](https://wordpress.org/plugins/ecrypt-payment-gateway-for-woocommerce/) from the WordPress plugin directory. 3. In your WordPress admin, go to **Plugins > Upload**, then upload the plugin file. 4. Install and activate the plugin. 5. Go to **WooCommerce > Settings > Payments** and enable ECRYPT. ## Connect Your ECRYPT Account 1. In the ECRYPT dashboard, go to **Settings > API/Security Keys** and copy your public API key. 2. In your WordPress admin, go to **WooCommerce > Settings > Payments > ECRYPT**. 3. Paste your public API key and save. ## Features **Native Checkout:** Allow customers to checkout natively on WooCommerce without redirecting to a hosted payment page. **Save card on file:** Customers can save their payment details at checkout for future purchases. You can add or delete stored payment methods from your WooCommerce settings. **Native refunds:** Refunds are handled directly in WooCommerce. Open an existing order and click the refund button. **Auth only:** Authorize transactions and capture full or partial amounts later. # Add-Ons Source: https://docs.ecrypt.com/guides/ach-add-ons ECRYPT offers optional add-on services to enhance your ACH integration with faster funding, real-time payments, and account validation tools. Contact your account manager to enable any of the services below and learn about pricing. ## Value Added Services | Service | Description | | ------------------------ | --------------------------------------------------------------------------------------------------- | | Premium Funding | Accelerates ACH settlement to 1-2 business days instead of the standard funding timeline. | | Same Day ACH Origination | Submits ACH transactions through the Same Day ACH network for same-business-day settlement. | | Real Time Payments (RTP) | Sends payments instantly via the RTP network, with funds available to the recipient within seconds. | ## Authorization & Validation Services | Service | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Basic Account Validation | Confirms that a bank account number and routing number form a valid combination. | | Enhanced Account Validation | Verifies account validity and checks whether the account is open and able to receive transactions. | | Premier Account Validation | Provides the highest level of account verification, including ownership and status confirmation. | | Consumer Identity Verification | Validates that the account holder's identity matches the name provided during enrollment. | | Credentialed Token Creation | Uses a credentialed data provider (such as Plaid) to generate a secure, reusable account token. | | Credentialed Balance Check | Retrieves a real-time balance from the account holder's bank via a credentialed data provider (such as Plaid). | # ACH Overview Source: https://docs.ecrypt.com/guides/ach-overview This guide covers ACH payment processing through the ECRYPT API. It explains how bank account data is represented, how ACH transactions are submitted and settled, and what actions you can take after a transaction is created. *** ## How ACH Works ACH (Automated Clearing House) is a bank-to-bank payment network operated by Nacha that moves funds electronically between U.S. financial institutions. Unlike card transactions, ACH payments are not authorized in real time. Transactions are submitted in batches throughout the day, processed overnight by the ACH network, and settled within 1-3 business days. ACH supports two directions of money movement: * **Debit:** Funds are pulled from a customer's bank account into your merchant account. This is the most common flow for collecting payments. * **Credit:** Funds are pushed from your merchant account into a recipient's bank account. Typically used for refunds, payouts, or disbursements. *** ## Bank Account Data Two fields are required to tokenize a bank account. Additional fields can be included for record-keeping and statement clarity. ### Required **`accountNumber`:** The number that identifies the specific account at the financial institution. Raw account numbers should never be stored in your system. Use tokenization instead. **`routingNumber`:** A 9-digit number that identifies the financial institution. Routing numbers appear at the bottom-left of a paper check. ### Optional **`name`:** The name of the individual or business that owns the account. Included in the ACH transaction record transmitted to the network. **`accountType`:** Indicates whether the account is checking (`0`) or savings (`1`). **`checkNumber`:** The check number associated with the transaction, if applicable. *** ## Tokenization Before initiating an ACH transaction, tokenize the bank account details. Tokenization replaces the routing number and account number with a non-sensitive token that is safe to store and reuse. To tokenize a bank account, send the account details to `POST /v1/tokens` using the `check` object. Only `accountNumber` and `routingNumber` are required: ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/tokens \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "check": { "account_number": "123123123", "routing_number": "123123123", "name": "Jane Smith", "check_number": "001", "account_type": "Checking" } } ' ``` ```json theme={null} { "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c", "metadata": { "accountNumber": "1*****3123" }, "requestId": "0HNK1A7BLRLH00000005E" } ``` The token string is what you pass in all subsequent transaction requests. The raw account number is never stored or returned after this point. *** ## Transaction Lifecycle ACH transactions do not use an authorization and capture model. There is no real-time approval step and no hold placed on funds. When you submit an ACH transaction, it is queued for processing and settlement begins asynchronously. ### Submitting a Transaction To initiate an ACH transaction, send a request to `POST /v1/transactions/sale` with the token from the tokenization step and the desired amount. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/sale \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "payment": { "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c" }, "amount": { "value": 100 } } ' ``` A successful submission returns a `transactionId` that you use for all subsequent operations (void, refund, etc.). ### Pending Once submitted, the transaction enters a `pending` state. ECRYPT batches ACH transactions and submits them to the ACH network on a regular processing schedule. ### Settlement After the batch is submitted to the network, settlement typically completes within 1-3 business days depending on the receiving bank and the time of submission. The transaction status changes from `pending` to `settled` once funds have transferred. Because there is no real-time authorization, a submitted transaction does not guarantee that funds are available. Insufficient funds, closed accounts, and invalid account data are discovered only during settlement or in the form of a return. ### Returns A return occurs when the receiving bank rejects the transaction after it has been submitted. Returns are identified by a standardized R-code. Common return reasons include: | Return Code | Description | | ----------- | ----------------------------------------- | | R01 | Insufficient funds | | R02 | Account closed | | R03 | No account or unable to locate | | R04 | Invalid account number | | R10 | Customer advises not authorized | | R29 | Corporate customer advises not authorized | Returns can arrive up to 2 banking days after settlement for most codes. Unauthorized transaction claims (R05, R07, R10, R29) have an extended return window of up to 60 days for consumers. ECRYPT delivers return notifications via [webhook](/guides/webhooks-setup). *** ## Managing Transactions Once a transaction exists, the actions available to you depend on whether it has settled. All actions reference the `transactionId` returned at submission. ### Pre-Settlement **Void:** Cancels the transaction before it settles. No funds are transferred. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/void \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transaction_id": "{{transaction_id}}" } ' ``` ### Post-Settlement **Refund:** Returns funds to the originating account after settlement has completed. A refund initiates a new ACH credit in the opposite direction of the original debit. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/refund \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transaction_id": "{{transaction_id}}", "amount": 100 } ' ``` Partial refunds are supported. You can issue multiple partial refunds against a single settled transaction as long as the total refunded amount does not exceed the original transaction amount. | Timing | Action | Funds Move? | | --------------- | ------------------------ | -------------- | | Pre-settlement | Void | No | | Post-settlement | Refund (full or partial) | Yes (returned) | *** # Apple Pay Source: https://docs.ecrypt.com/guides/apple-pay Accept Apple Pay through Ecrypt's hosted checkout products. Apple Pay lets shoppers check out with any credit or debit card saved to Apple Wallet, authorizing the payment with Face ID, Touch ID, or their device passcode. Ecrypt handles the wallet flow on our hosted pages, so you can enable Apple Pay without building or certifying the wallet integration yourself. ## At a glance | | | | ----------------------------- | ------------------------------------------------- | | **Channels** | Dynamic Checkout, iFrame, Payment Links, Invoices | | **Cardholder locations** | All countries where Apple Pay is supported | | **Settlement currency** | USD | | **Domain registration** | Required (handled by Ecrypt — see below) | | **Supported browsers** | Safari, plus supporting third-party browsers | | **Recurring billing** | Supported | | **Refunds / partial refunds** | Supported | | **Voids** | Supported | ## Where Apple Pay is available in Ecrypt Apple Pay is currently offered only through Ecrypt's hosted checkout surfaces. When a shopper lands on one of these pages from a compatible Apple device and browser, the Apple Pay button renders automatically alongside the standard card form: * **Dynamic Checkout**: full-featured, hosted checkout page created with the `/v1/dynamiccheckout` endpoint. * **Hosted iFrame**: populate Apple Pay in Ecrypt's hosted iFrame underneath card fields. * **Payment Links**: shareable URLs that accept a single payment or kick off a subscription. * **Invoices**: customer-facing invoice pages with a pay-now action. Because the button renders through Apple's own JavaScript API, it always displays the current, correctly localized Apple Pay button style. Ecrypt does not create custom Apple Pay buttons or alter Apple's artwork, in line with Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) and [Marketing Guidelines](https://developer.apple.com/apple-pay/marketing/). ## Turn Apple Pay on Apple Pay is activated by the Ecrypt team. Ecrypt registers and manages the Apple Pay configuration on your behalf. You don't need an Apple Developer account, and you don't manage any Apple Pay keys or certificates. To enable Apple Pay: * **New merchants**: request Apple Pay with your Ecrypt account representative during initial onboarding. * **Existing merchants**: reach out to your Ecrypt account representative or contact [support](https://support.ecrypt.com) to request activation. Once activated, the Apple Pay button begins rendering on your hosted checkout surfaces. If you embed Dynamic Checkout or the hosted iFrame on your own domain, complete the one-time domain verification step below. > Ecrypt manages token decryption and processing on your behalf. You never handle raw card numbers. ## Accepting inbound international payments Ecrypt accepts Apple Pay from shoppers in any country or region where Apple Pay operates. The cardholder selects a card from Apple Wallet, and Ecrypt processes it as a standard card transaction. Settlement happens in USD to your merchant account, following your normal funding schedule. For an up-to-date list of countries and regions where shoppers can use Apple Pay, see [Apple's supported countries and regions](https://support.apple.com/en-us/HT207957). ## Recurring billing and subscriptions Apple Pay works with Ecrypt subscriptions. When a customer completes their first payment through Dynamic Checkout that includes a `subscription` object, Ecrypt stores the resulting tokenized payment credential and reuses it for each recurring charge on the cycle you define. For recurring, automatic-reload, and deferred payments, Ecrypt requests an Apple Pay **merchant token** where the card issuer supports it. A merchant token links the card, merchant, and shopper so billing continues even if the shopper upgrades their device or removes the card from one device. Where the issuer does not yet support merchant tokens, Ecrypt falls back to the standard device token automatically — no change on your end. Ecrypt marks the stored credential appropriately so follow-on charges run as merchant-initiated transactions. For details on cycle types and billing dates, see the [Subscriptions](https://docs.ecrypt.com/subscriptions) reference. ## Post-payment operations Apple Pay transactions settle as standard card transactions in Ecrypt, so you can manage them exactly like any other credit card charge. Refunds (full or partial), voids on unsettled authorizations, and chargeback responses all run through the same endpoints and dashboard workflows you already use for card payments. Apple Pay transactions appear in reporting with the `paymentNetwork` set to the underlying card brand (Visa, Mastercard, and so on) and are flagged as Apple Pay, making them easy to identify and reconcile alongside your other card volume. ## Data verification **Payment data**
Ecrypt handles the generation of the Apple Pay payment request and manages the encrypted payload securely. Merchants are not required to manually configure merchant identifiers, supported networks, or certificates — Ecrypt maps the decrypted Apple Pay token (including the one-time cryptogram and ECI values) to the authorization message for you. **Billing and shipping data**
Ecrypt automatically configures the contact fields collected in the Apple Pay payment sheet and uses them for address verification during checkout. Apple does not verify the contact information a shopper provides, so Ecrypt validates it on our side and surfaces any correctable fields back through the payment sheet. No additional code or custom configuration is required on the merchant's end. ## Testing To test the Apple Pay flow end-to-end: 1. Generate a Dynamic Checkout, Payment Link, or Invoice in your Ecrypt **sandbox** environment. 2. Sign in to iCloud on a physical Apple device using an [Apple Pay Sandbox Tester account](https://developer.apple.com/apple-pay/sandbox-testing/), and add one of Apple's sandbox test cards to Wallet. 3. Open the resulting URL in Safari (or a supporting third-party browser) and complete the flow. Sandbox charges are not settled. 4. Also test in your **production** environment with a real card to confirm the end-to-end flow before going live. Apple Pay only renders on devices and browsers that meet Apple's eligibility rules: an Apple Pay-capable device, an HTTPS connection, a supported browser, and at least one card in Wallet. On desktop, the shopper needs an Apple Pay-capable iPhone or a Mac with Touch ID to authorize. If the button doesn't appear, those are the first things to check. ### Embedding Dynamic Checkout in an iFrame If you're testing Dynamic Checkout inside an ` ``` * `allow="payment"` enables the Payment Request API that Apple Pay relies on. * `allow-same-origin` is required so Ecrypt's checkout page can talk to its own origin. * `allow-scripts` and `allow-forms` are required for the page itself to function. The simplest option is omitting the `sandbox` attribute entirely, which gives the iFrame full permissions. Only use `sandbox` if you have a specific reason to restrict what the frame can do. Remember that the **top-level** domain — not the iframe's `src` — is the one that must be verified for Apple Pay. ## Acceptable use and terms Merchants using Ecrypt's hosted checkout with Apple Pay enabled must ensure their implementation complies with Apple's [Acceptable Use Guidelines for Apple Pay on the Web](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/) and follow Apple's branding requirements in the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) and [Marketing Guidelines](https://developer.apple.com/apple-pay/marketing/). Among other things, you may not use Apple Pay on a site that violates any law or that involves restricted activities without Apple's approval. ## Resources from Apple * [Apple Pay on the Web — Developer Documentation](https://developer.apple.com/documentation/apple_pay_on_the_web) * [Apple Pay Platform Integration Guide (PDF)](https://developer.apple.com/download/files/Apple-Pay-Platform-Integration-Guide.pdf) * [Acceptable Use Guidelines for Apple Pay on the Web](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/) * [Apple Pay Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) * [Apple Pay Sandbox Testing](https://developer.apple.com/apple-pay/sandbox-testing/) *** Apple Pay is a trademark of Apple Inc., registered in the U.S. and other countries and regions. # Batches Source: https://docs.ecrypt.com/guides/batches The Reporting API provides two batch endpoints: one to retrieve a list of batches by date range, and one to fetch the transactions within a specific batch. Both batch endpoints support pagination via `page` and `pageSize` parameters. The maximum `pageSize` is `1000`. Use the `totalCount` field in the response to determine how many pages to request. Date filtering is based on UTC time. ## Authentication All Reporting API requests require a **Reporting API key** passed in the request header. ```http theme={null} X-Api-Key: {{reporting_api_key}} ``` *** ## List Batches Fetch a list of batch IDs for a given date range. ```http theme={null} POST https://reporting.ecrypt.com/api/Batch ``` ### Request ```http theme={null} POST /api/Batch HTTP/1.1 Host: reporting.ecrypt.com X-Api-Key: {{reporting_api_key}} Content-Type: application/json ``` ```json theme={null} { "page": 1, "pageSize": 100, "sortOrder": "desc", "startDate": "2024-09-01T00:00:00", "endDate": "2024-09-30T23:59:59" } ``` ### Body Parameters | Parameter | Type | Description | | ----------- | ------- | ----------------------------------------- | | `page` | integer | Page number for pagination | | `pageSize` | integer | Records per page. Maximum: `1000` | | `sortOrder` | string | Sort direction: `asc` or `desc` | | `startDate` | string | Start of date range. Format: `MM-DD-YYYY` | | `endDate` | string | End of date range. Format: `MM-DD-YYYY` | Date filtering is based on **UTC time**. ### Response ```json theme={null} { "batches": { "items": [ { "id": 82382801, "closed": "2024-09-30T02:00:00", "status": "COMPLETED" } ], "page": 1, "pageSize": 1000, "totalCount": 1 } } ``` ### Response Fields | Field | Description | | ------------ | ------------------------------------------ | | `id` | Batch identifier | | `closed` | Timestamp the batch was closed (UTC) | | `status` | Batch status (e.g., `COMPLETED`) | | `totalCount` | Total number of batches matching the query | *** ## Get Batch Detail Fetch the transactions within a specific batch. ```http theme={null} POST https://reporting.ecrypt.com/api/BatchDetail ``` ### Request ```http theme={null} POST /api/BatchDetail HTTP/1.1 Host: reporting.ecrypt.com X-Api-Key: {{reporting_api_key}} Content-Type: application/json ``` ```json theme={null} { "id": 82382801, "page": 1, "pageSize": 1000, "sortOrder": "desc", "sortColumn": "Id" } ``` ### Body Parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------- | | `id` | integer | Batch ID to retrieve | | `page` | integer | Page number for pagination | | `pageSize` | integer | Records per page. Maximum: `1000` | | `sortOrder` | string | Sort direction: `asc` or `desc` | | `sortColumn` | string | Column to sort by (e.g., `Id`) | ### Response ```json theme={null} { "id": 82382801, "transactions": { "items": [ { "transactionId": 229764501, "type": "SALE", "tender": "CREDITCARD", "paymentName": "JJ TEST", "paymentNetwork": "VI", "paymentAccount": "4***********1111", "paymentAccountExpiry": "1025", "amount": 125.00, "authorizationAmount": 125.00, "capturedAmount": 125.00, "gratuityAmount": 0.00, "surchargeAmount": 0.00, "settlementAmount": 125.00, "approvalCode": "123456", "avsCode": "N", "cvvCode": "M", "status": "SETTLED", "created": "2024-09-29T17:16:24" }, { "transactionId": 229743301, "type": "SALE", "tender": "CREDITCARD", "paymentName": "John Doe", "paymentNetwork": "VI", "paymentAccount": "4***********1111", "paymentAccountExpiry": "1025", "amount": 6.00, "authorizationAmount": 6.00, "capturedAmount": 6.00, "gratuityAmount": 0.00, "surchargeAmount": 0.00, "settlementAmount": 6.00, "approvalCode": "123456", "cvvCode": "M", "status": "SETTLED", "created": "2024-09-29T14:14:23" } ], "page": 1, "pageSize": 1000, "totalCount": 2 } } ``` ### Response Fields | Field | Description | | ------------------------- | ----------------------------------------- | | `id` | Batch ID | | `transactions.items` | Array of transactions in the batch | | `transactions.totalCount` | Total number of transactions in the batch | | `transactions.page` | Current page | | `transactions.pageSize` | Page size used for this response | Each transaction item contains the same fields as the [Get a Transaction](/reporting/transactions) response. # Cards Overview Source: https://docs.ecrypt.com/guides/cards-overview This guide covers the fundamentals of card-based payment processing through the ECRYPT API. It walks through how cards are represented, how transactions flow from authorization to settlement, and the tools you have to manage transactions after they are created. > **Note:** This guide applies to both online and in-person card transactions. The only difference between the two is how card data is collected. Once tokenized, the transaction lifecycle and API calls are identical. For details on setting up physical devices, see [Terminal Overview](/guides/cloud-terminal). *** ## Supported Card Brands ECRYPT supports the following card networks: | Brand | BIN Prefix(es) | CVV Name | | --------------------------------- | ---------------------- | -------------- | | Visa | 4 | CVV | | Mastercard | 51-55, 2221-2720 | CVC | | American Express | 34, 37 | CID (4 digits) | | Discover (includes JCB, UnionPay) | 6011, 622, 644-649, 65 | CID | All four brands are enabled by default. No additional configuration is needed to begin accepting any of these networks. *** ## Anatomy of a Card Every card transaction relies on a small set of data points printed on (or embedded in) the physical card. Understanding these fields is important because they map directly to the parameters you will pass to the API. ### PAN (Primary Account Number) The PAN is the long number on the front of the card, typically 15 or 16 digits. Visa also supports PANs up to 19 digits. It identifies the card issuer and the cardholder's account. You should never store raw PANs in your system. Instead, use tokenization (covered below) to exchange the PAN for a secure token. ### Expiration Date A month and year (MM/YY) indicating when the card is no longer valid. The card remains usable through the last day of the expiration month. Include this in every transaction request. ### CVV / CVC / CID The 3- or 4-digit security code used to verify that the person submitting the transaction has physical access to the card. Visa, Mastercard, and Discover use a 3-digit code on the back of the card. American Express uses a 4-digit code on the front. Like the PAN, the CVV must never be stored after authorization. Card network rules explicitly prohibit CVV retention. *** ## Tokenization Before you can charge a card, you need to tokenize it. Tokenization replaces sensitive card data (PAN, expiration, CVV) with a non-sensitive token that is safe to store and reuse. This is the entry point for all card transactions in ECRYPT. To tokenize a card, send the card details to `POST /v1/tokens` using the `creditCard` object. The API returns a token string that represents that card. From that point on, you use the token in place of raw card data for all transaction requests. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/tokens \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "creditCard": { "accountNumber": "4111111111111111", "expires": "1227", "verificationValue": "123", "postalCode": "90210" } } ' ``` ```json theme={null} { "token": "0HNJOGLAUD7P200000003", "metadata": { "creditCardNumber": "4***********1111", "creditCardNetwork": "visa", "creditCardType": "credit" }, "requestId": "000000000000000000000" } ``` To store a token for future use (such as saving it to a [Customer Wallet](/api-reference/gateway/customers-wallet) for recurring billing or returning customers), add the token to a customer wallet after creation. **Why tokenize?** * **PCI compliance.** Handling raw card data increases your PCI scope significantly. Tokens let you reference a card without touching sensitive data after the initial exchange. * **Reuse.** Tokens can be stored in a Customer Wallet and used for future charges, recurring billing, or one-click checkout flows without asking the cardholder to re-enter their details. * **Security.** Even if your database is compromised, tokens are useless outside of your ECRYPT account. For client-side integrations, use the [Hosted Iframe](/guides/iframe) to collect card details directly in the browser. The iframe handles tokenization without the card data ever touching your servers, which keeps you in the lowest PCI compliance tier (SAQ A). *** ## Transaction Lifecycle A card transaction moves through three stages: authorization, capture, and settlement. Depending on your use case, you may interact with each stage individually or use a single API call that handles them together. ### Authorization An authorization (or "auth") is a request to the cardholder's issuing bank to verify that the card is valid and that sufficient funds are available. If approved, the issuer places a hold on the requested amount. No money moves at this stage. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/authorize \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "payment": { "token": "0HNJOGLAUD7P200000003" }, "amount": { "value": 42.00 } } ' ``` An approved authorization returns a `transactionId` that you will reference in all subsequent operations (capture, void, etc.). **Authorization holds and expiration.** An auth hold does not last forever. If you do not capture the authorization within the allowed window, the hold is released and the funds become available to the cardholder again. The expiration timeline varies by card brand: | Brand | Typical Hold Duration | | ---------------- | --------------------- | | Visa | 7 days | | Mastercard | 7 days | | American Express | 7 days | | Discover | 10 days | These durations are approximate and may differ depending on the issuing bank. Certain industries are granted longer hold windows by the card networks. Hotels, rental car agencies, and similar businesses where the final charge amount is not known at check-in may have authorization holds that last up to 30 days. If you need to charge the card after a hold expires, you will need to create a new authorization. Auth-only workflows are common in industries where the final charge amount is not known at the time of the initial request. Hotels, rental car agencies, and restaurants are typical examples. ### Capture A capture tells ECRYPT to finalize the authorized amount and include it in the next settlement batch. You can capture the full authorized amount or a partial amount. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/capture \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transactionId": "{{transaction_id}}", "amount": 42.00 } ' ``` **Partial captures.** If you authorized $42.00 but only need to charge $30.00 (for example, an item was out of stock), you can capture a lesser amount. The remaining hold is released back to the cardholder. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/capture \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transactionId": "{{transaction_id}}", "amount": 30.00 } ' ``` Once a transaction is captured, it is queued for settlement. A transaction can only be captured once. ### Settlement Settlement is the process of transferring funds from the cardholder's issuing bank to your merchant account. ECRYPT batches captured transactions and submits them for settlement automatically. You do not need to trigger settlement manually. Each merchant account has a configured **Auto Close** time that determines when the current batch is closed and submitted for settlement each day. This time is set during account onboarding. All transactions captured before the Auto Close cutoff are included in that day's batch. Transactions captured after the cutoff roll into the next batch. After settlement completes, funds are deposited into your merchant account, usually within 1-2 business days. The transaction status changes from `captured` to `settled`. ### The Sale (Auth + Capture) For most use cases, you do not need to separate authorization and capture into two steps. A **sale** performs both in a single API call. The transaction is authorized and immediately captured, then included in the next settlement batch. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/sale \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "payment": { "token": "0HNJOGLAUD7P200000003" }, "amount": { "value": 42.00 } } ' ``` The sale is the most commonly used transaction type. Use it whenever you know the exact charge amount at the time of the transaction and do not need a delayed capture window. *** ## Managing Transactions Once a transaction exists, the actions available to you depend on whether it has settled. ### Pre-Settlement **Void.** Cancels the transaction entirely before it settles. The authorization hold is released, and no funds are transferred. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/void \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transactionId": "{{transaction_id}}" } ' ``` **Capture.** If the transaction was created as an auth-only, you can capture it to move it into the settlement batch. See the Capture section above. ### Post-Settlement **Refund.** Returns funds to the cardholder after settlement has completed. You can refund the full amount or a partial amount. Unlike a void, a refund is a new transaction that appears on the cardholder's statement as a credit. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/refund \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "transactionId": "{{transaction_id}}", "amount": 42.00 } ' ``` Partial refunds are supported. You can issue multiple partial refunds against a single transaction as long as the total refunded amount does not exceed the original transaction amount. | Timing | Action | Funds Move? | | --------------- | ------------------------ | -------------- | | Pre-settlement | Void | No | | Pre-settlement | Capture (auth-only) | Queued | | Post-settlement | Refund (full or partial) | Yes (returned) | *** ## Address Verification Service (AVS) AVS is a fraud prevention tool that compares the billing address provided in the transaction request against the address the issuing bank has on file for the cardholder. It adds a layer of verification beyond the card number and CVV alone. ### How It Works When you include billing address fields in your transaction request, the issuing bank checks them and returns an AVS response code indicating the degree of match. ECRYPT evaluates this code against your AVS configuration to decide whether to approve or decline the transaction. ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/transactions/sale \ --header 'X-Api-Key: {{api_key}}' \ --header 'content-type: application/json' \ --data ' { "payment": { "token": "0HNJOGLAUD7P200000003" }, "amount": { "value": 42.00 }, "order": { "billTo": { "line1": "123 Main St", "postalCode": "90210" } } } ' ``` ### AVS Configuration ECRYPT supports three levels of AVS enforcement. You can configure this per merchant account. **Zip Code Only (Default).** ECRYPT requires a zip code match by default. This is the most common configuration and provides a strong balance between fraud prevention and conversion. Transactions where the zip code does not match the issuer's records will be declined. **Full Address.** Requires both the street address and zip code to match. This provides stronger fraud protection but can lead to higher decline rates, particularly when cardholders have recently moved or when the issuer's address records are not up to date. **None.** AVS checks are disabled entirely. The transaction is processed regardless of any address data provided (or not provided). This is not recommended for card-not-present transactions, as it removes an important fraud signal. | Configuration | Fields Required | Fraud Protection | Decline Risk | | ------------------ | --------------------- | ---------------- | ------------ | | Zip Only (default) | `postalCode` | Moderate | Low | | Full Address | `line1`, `postalCode` | High | Moderate | | None | None | None | None | Regardless of your enforcement level, including address data when available is good practice. Some issuing banks may decline a transaction outright if no AVS data is provided, independent of your ECRYPT configuration. Even if you are not declining on AVS mismatches, the response codes are returned in the transaction response and can be useful for your own fraud review processes. *** # Go Live & Certification Source: https://docs.ecrypt.com/guides/certification Complete your integration review and move to production. ## Overview Every integration must be reviewed and certified by the ECRYPT engineering team before processing live transactions. Certification confirms that your implementation handles payment flows correctly, meets compliance requirements, and avoids common issues that can cause problems in production. The process has three stages: prepare your integration in sandbox, schedule a certification call with our engineering team, and cut over to production once approved. ## Before You Schedule Work through the checklist below in your sandbox environment. Completing these items before your certification call keeps the review focused and avoids delays. ### Test Core Payment Flows Run each of the following transaction types end-to-end and confirm you receive the expected response codes: | Flow | What to Verify | | ---------------------- | ------------------------------------------------------------------------------------------------ | | Sale | Transaction approved, `transactionId` returned, amount matches | | Refund | Refund issued against a settled transaction, amount does not exceed original | | Void | Unsettled transaction voided successfully | | Authorize | Authorization hold placed, no capture | | Authorize then Capture | Capture completes against the original authorization, amount is equal to or less than authorized | | Authorize then Void | Authorization voided before settlement | If your integration only handles initial transactions (sales, authorizations) and you plan to manage refunds, voids, and captures through the ECRYPT dashboard, let us know when scheduling your certification call. If your integration accepts ACH payments, also test a sale and refund using the `check` payment object. ### Test Entry Points Certification requirements vary depending on how you accept payments. Make sure you test every entry point your integration uses: | Entry Point | What to Cover | | ----------------------- | ----------------------------------------------------------------------------------------------- | | API (card-not-present) | Tokenization via `POST /v1/tokens`, then sale using `payment.token` | | Hosted Iframe | Token generation through the iframe, sale submission from your server | | Checkout Page | Dynamic checkout creation via `POST /v1/dynamiccheckout`, end-to-end purchase | | Terminal (card-present) | Terminal registration, sale via `payment.terminal`, tip prompt if applicable | | Stored credentials | Charging a customer wallet via `payment.stored`, both merchant-initiated and customer-initiated | ### Verify Error Handling Trigger common failure scenarios and confirm your integration handles them gracefully: * **Declined transactions.** Submit a transaction that returns a decline and verify your UI communicates the result clearly to the end user. * **Validation errors (400).** Send a malformed request (missing required fields, invalid values) and confirm you parse the `errors` array from the response. * **Authentication failures (401/403).** Attempt a request with an invalid or missing API key and verify you do not expose raw error details to end users. ### Confirm Webhook Delivery If your integration relies on webhooks: 1. Register your webhook endpoint in the ECRYPT dashboard. 2. Process at least one transaction and confirm the webhook payload is received. 3. Verify your endpoint returns a `200` response promptly. 4. Test your handling for relevant event types (transaction approved, declined, refunded, voided). ### Review Compliance Basics * **PCI scope.** Confirm you understand your PCI obligations based on your integration method. If you tokenize via the hosted iframe or checkout page, your server never handles raw card data. If you tokenize server-side via `POST /v1/tokens` with raw card numbers, your environment must meet SAQ D requirements and provide ECRYPT a copy of your AOC. * **Surcharging.** If surcharging is enabled on your account, verify that surcharge amounts display correctly to the cardholder before they confirm the transaction. ECRYPT automatically drops surcharges on debit and prepaid cards via BIN lookup. You are responsible for complying with your states surcharging laws. * **Stored credentials.** When charging a customer wallet for recurring or installment payments, make sure `initiatedBy` is set correctly (`0` for merchant-initiated, `1` for customer-initiated). ## Schedule Your Certification Call Once you have completed the checklist above, contact the ECRYPT engineering team to schedule your review: Email your account manager or [**devsupport@ecrypt.com**](mailto:devsupport@ecrypt.com) with: * DBA Name * Brief description of your integration * Supported features (iFrame, terminals, subscriptions, etc.) The engineering team will coordinate a time to walk through your integration together. ## What Happens During the Call The certification call is a live review where an ECRYPT engineer works through your integration with you. Expect the session to cover: 1. **Transaction walkthrough.** You will run each of the core payment flows (sale, refund, void, authorize, capture) while the engineer monitors the requests and responses on the ECRYPT side. 2. **Error handling review.** The engineer may trigger specific decline codes or error conditions to confirm your integration responds appropriately. 3. **Compliance check.** The engineer reviews how you handle sensitive data, display surcharges (if applicable), and manage stored credentials to ensure there are no compliance risks. 4. **Edge cases.** Depending on your integration type, the engineer may check scenarios like partial refunds, duplicate transaction prevention, webhook retry handling, or terminal connectivity recovery. 5. **Feedback.** If any issues are found, the engineer will walk through what needs to change. Minor issues can often be resolved and re-tested on the same call. Most certification calls take 30 to 60 minutes depending on the complexity of the integration. ## After Certification Once the ECRYPT engineering team approves your integration: ### Switch to Production Credentials Replace your sandbox API keys with your production API keys. Your production keys are available in the ECRYPT dashboard under **Settings > API Keys**. | Setting | Sandbox | Production | | ---------- | -------------------------------- | ------------------------ | | Base URL | `https://sandbox.api.ecrypt.com` | `https://api.ecrypt.com` | | API Key | Sandbox private key | Production private key | | Public Key | Sandbox public key | Production public key | Never use sandbox keys in production or production keys in sandbox. Sandbox transactions are simulated and will not process real payments. ### Run a Live Verification After switching to production credentials, run a small live transaction (such as a \$1.00 sale followed by a void or refund) to confirm your production configuration is working end to end. ### Register Production Terminals If your integration uses in-person terminals, you must register each terminal in the production environment. Terminal registrations do not carry over from sandbox. ### Update Webhook URLs If you registered sandbox webhook URLs, update them to point to your production endpoints. ## Need Help? If you have questions about certification requirements or need to reschedule your review, visit the [Developer Support](/guides/developer-support) page. # Charge Customer Wallet Source: https://docs.ecrypt.com/guides/charge-customer-wallet Charge a customer's stored payment method using their customer ID or a specific wallet payment method. ## Overview Once a customer has a payment method saved to their wallet, you can charge them through the standard transaction endpoints using the `payment.stored` object. You can charge either the customer's default payment method or a specific wallet entry. *** ## Charge the Default Payment Method To charge a customer's default payment method, pass the customer `id` in `payment.stored.customer`. ECRYPT will automatically use whichever wallet entry is marked as default. ```bash theme={null} POST /v1/transactions/sale ``` ```json theme={null} { "payment": { "stored": { "customer": "00000000-0000-0000-0000-000000000000", "initiated_by": "MERCHANT" } }, "amount": { "value": 99.00, "currency": "USD" } } ``` *** ## Charge a Specific Wallet Payment Method To charge a specific payment method, pass the wallet entry `id` in `payment.stored.wallet` instead. This is useful when a customer has multiple payment methods on file and you need to target a specific one. ```bash theme={null} POST /v1/transactions/sale ``` ```json theme={null} { "payment": { "stored": { "wallet": "00000000-0000-0000-0000-000000000000", "initiated_by": "MERCHANT" } }, "amount": { "value": 99.00, "currency": "USD" } } ``` *** ## initiatedBy The `initiatedBy` field indicates who initiated the transaction. This is required for stored payment method transactions and affects how the transaction is processed at the network level. | Value | Meaning | Description | | ----- | -------- | -------------------------------------------------------------------------------------------------------------- | | `0` | Merchant | The merchant initiated the transaction. Used for recurring payments, installments, and agent-assisted charges. | | `1` | Customer | The customer initiated the transaction. Used when the customer selects a stored card during checkout. | *** ## Authorize and Capture If you need to place a hold before capturing, use the authorize endpoint instead of sale. The same `payment.stored` object applies. ```bash theme={null} POST /v1/transactions/authorize ``` Once ready to capture: ```bash theme={null} POST /v1/transactions/capture ``` ```json theme={null} { "transaction_id": "123456789", "amount": 99.00 } ``` *** ## Transaction Response A successful charge returns a transaction ID, approval code, and the amount processed. ```json theme={null} { "transaction_id": "123456789", "auth_code": "TAS123", "response_code": "APPROVED", "response_text": "APPROVED", "amount": 99.00, "request_id": "000000000000000000000" } ``` Store the `transactionId` from every charge. It is required for voids, refunds, and captures. *** ## Recurring Payments Customer wallets are also the foundation for automated recurring billing. ECRYPT supports two models -- subscriptions for ongoing recurring charges, and installment plans for splitting a fixed amount into scheduled payments. Automatically charge a customer's wallet on a recurring schedule -- daily, weekly, monthly, and more. Split a total amount into a defined number of scheduled charges against a customer's wallet. # Dynamic Checkout Page Source: https://docs.ecrypt.com/guides/checkout-page A feature-rich tool that offers an end-to-end sales solution with a highly customizable checkout/invoice experience. Dynamic Checkout is a feature-rich tool that offers an end-to-end sales solution for ISV partners. It creates a highly customizable checkout/invoice experience that can be fully branded to the user's preference. The interface offers complete control over the design, including the use of colors, fonts, logos, and background colors, creating a unique brand experience for users. Users can add an itemized list of the products they are selling, along with the respective prices. Additionally, Dynamic Checkout supports adding tax, surcharge, and custom total price. This feature offers greater flexibility for users when creating and managing their checkout/invoices. The API returns a link that can be used in an iframe, email, or SMS, making it an efficient way to share invoices with customers. The responsive design of the checkout/invoice is also highly advantageous, as it ensures that customers can view the invoice on any device, making it highly accessible. In summary, Dynamic Checkout offers a highly customizable and responsive checkout/invoice experience, complete with a flexible pricing structure, making it an invaluable tool for ISV partners. ## Get Started You will need to post to this API using your private key in the headers: ```text theme={null} https://api.ecrypt.com/v1/dynamiccheckout ``` Here is an example of what you will post in the body for a checkout: ```json theme={null} { "invoice_info": null, "tax": 6.00, "discount": 0.00, "surcharge": 6.18, "total": 82.18, "subtotal": 70.00, "collect_shipping": false, "send_receipt": true, "thank_you_url": "", "customer_info": null, "items": [ { "name": "Lorem ipsum dolor", "price": 70.00, "quantity": 1, "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean ac aliquam massa. Item 1 description" } ], "appearance": { "invoice_text_color": "", "invoice_accent_color": "", "invoice_border_color": "", "invoice_background_color": "", "invoice_button_text_color": "", "invoice_button_background_color": "", "invoice_icon_theme": "", "form_icon_theme": "", "form_text_color": "", "form_accent_color": "", "form_border_color": "", "form_background_color": "", "form_button_text_color": "", "form_button_background_color": "", "form_input_text_color": "", "form_input_background_color": "", "alert_color": "", "input_variant": "", "success_color": "", "mobile_icon_theme": "", "mobile_text_color": "", "mobile_background_color": "", "mobile_button_text_color": "", "mobile_button_background_color": "", "mobile_input_text_color": "", "mobile_input_background_color": "", "mobile_input_border_color": "", "invoice_mobile_background_color": "", "invoice_mobile_text_color": "", "mobile_accent_color": "" } } ``` ## Dynamic Checkout Object Documentation This object represents an invoice/checkout and contains various properties and sub-objects describing the invoice's/checkout's details. *** ### invoice\_info This object contains details about the invoice. * `number` (string): The invoice number. * `invoice_date` (string): The date the invoice was issued. * `due_date` (string): The due date for payment. **Example:** ```json theme={null} "invoice_info": { "number": "9621876516", "invoice_date": "1-07-2023", "due_date": "12-30-2023" } ``` If left `null` it won't display the invoice information on the left. If `invoice_info` object is left `null`: ![Invoice info null](https://files.readme.io/103e168-Screen_Shot_2023-02-21_at_2.53.23_PM.png) If `invoice_info` object is `filled`: ![Invoice info filled](https://files.readme.io/11d05fc-Screen_Shot_2023-02-21_at_2.53.15_PM.png) *** ### tax This property is a floating-point number representing the total amount of tax charged on the invoice. **Example:** ```json theme={null} "tax": 6.00 ``` *** ### discount This property is a percentage representing the discount rate applied to the invoice. **Example:** ```json theme={null} "discount": "3%" ``` *** ### surcharge This property is a floating-point number representing the total amount of surcharge charged on the invoice. **Example:** ```json theme={null} "surcharge": 2.00 ``` *** ### total This property is a floating-point number representing the total amount due for the invoice. **Example:** ```json theme={null} "total": 300.00 ``` *** ### subtotal This property is a floating-point number representing the subtotal of the invoice before taxes and surcharges are added. **Example:** ```json theme={null} "subtotal": 200.00 ``` *** ### collect\_shipping This property is a Boolean value indicating whether or not you want to collect the shipping information of your user. This will add an extra step to the flow. **Example:** ```json theme={null} "collect_shipping": false ``` *** ### send\_receipt This property is a Boolean value indicating whether or not the invoice should be sent to the customer as a receipt. If true, this will add an email input when collecting your user's payment information. By default, this is set to false. **Example:** ```json theme={null} "send_receipt": false ``` *** ### thank\_you\_url This property refers to a string value that designates a URL for a button on the Order confirmation page. This allows users to easily navigate back to any link that is passed to the button. **Example:** ```json theme={null} "thank_you_url": "https://www.ecrypt.com/" ``` ![Thank you URL example](https://files.readme.io/c1c5a97-thank_you_url.png) *** ### customer\_info This object contains details about the customer who is receiving the invoice. If `invoice_info` is left `null`, this information will not be displayed in the UI but will be used to prefill user info in the Payment / Billing inputs. * `name` (string): The customer's name. * `email` (string): The customer's email address. * `address` (string): The customer's street address. * `city` (string): The customer's city. * `state` (string): The customer's state. * `zip` (string): The customer's ZIP or postal code. * `country` (string): The customer's country. **Example:** ```json theme={null} "customer_info": { "name": "John Doe", "email": "johnDoe@test.com", "address": "12301 Fake Oaks Blvd", "city": "Beverly Hills", "state": "CA", "zip": "90210", "country": "US" } ``` *** ### items This property is an array of objects representing the items included in the invoice. Each item object contains the following properties: * `name` (string): The name of the item. * `price` (number): The price of the item. * `quantity` (number): The quantity of the item. * `description` (string): A description of the item. **Example:** ```json theme={null} "items": [ { "name": "Hover-1 Pro Series Altai R500 Electric Bicycle", "price": 23000.99, "quantity": 1, "description": "PERFORMANCE THAT EXCITES - Altai R500's powerful 500W motor..." }, { "name": "Seway Scooter Lock Cable for Xiaomi Mijia M365 ES Series", "price": 13.49, "quantity": 1, "description": "BRAIDED STEEL & PVC COATING: Scooter cable lock is made of high strength braided steel wire..." } ] ``` Example picture showing where all keys are placed: ![Dynamic Checkout keys overview](https://files.readme.io/7b29b44-dynamicCheckout.jpg) *** ## Appearance The Appearance object includes various properties that define the appearance of the invoice and form. Each property is optional and should be a string representing a color code or a theme. Supported formats for color codes: * Hexadecimal Format: `#000000` * RGB Format: `rgb(0, 0, 0)` * RGBA Format: `rgba(0, 0, 0, 1)` * HSL Format: `hsl(0, 0%, 0%)` * HSLA Format: `hsla(0, 0%, 0%, 1)` * Named Colors: `black` *** ### invoice\_text\_color `invoice_text_color` (string): The color of the text in the invoice UI. **Example:** ```json theme={null} "invoice_text_color": "#000000" ``` ![invoice\_text\_color example](https://files.readme.io/42046ea-invoice_text_color.png) *** ### invoice\_accent\_color `invoice_accent_color` (string): The accent color in the invoice UI. **Example:** ```json theme={null} "invoice_accent_color": "#4B9FD6" ``` ![invoice\_accent\_color example](https://files.readme.io/9b2caa6-invoice_accent_color.png) *** ### invoice\_border\_color `invoice_border_color` (string): The color of the borders in the invoice UI. **Example:** ```json theme={null} "invoice_border_color": "#000000" ``` ![invoice\_border\_color example](https://files.readme.io/86c778f-invoice_border_color.png) *** ### invoice\_background\_color `invoice_background_color` (string): The background color of the invoice UI. **Example:** ```json theme={null} "invoice_background_color": "#F0F1F2" ``` ![invoice\_background\_color example](https://files.readme.io/8401987-invoice_background_color.png) *** ### invoice\_button\_text\_color `invoice_button_text_color` (string): The color of the text on the invoice button on tablet and mobile view. **Example:** ```json theme={null} "invoice_button_text_color": "#ffffff" ``` ![invoice\_button\_text\_color example](https://files.readme.io/66ff397-invoice_button_text_color.png) *** ### invoice\_button\_background\_color `invoice_button_background_color` (string): The background color of the invoice button on tablet and mobile view. **Example:** ```json theme={null} "invoice_button_background_color": "#0f2659" ``` ![invoice\_button\_background\_color example](https://files.readme.io/18501ac-invoice_button_background_color.png) *** ### invoice\_icon\_theme `invoice_icon_theme` (string): This changes the default ecrypt logo from dark or light. Only two values are accepted: `dark` or `light`. **Example:** ```json theme={null} "invoice_icon_theme": "dark" ``` ![invoice\_icon\_theme example](https://files.readme.io/837b78b-invoice_icon_theme.png) *** ### form\_icon\_theme `form_icon_theme` (string): Changes the default credit card icon and down arrow icon to dark or light. Only two values are accepted: `dark` or `light`. **Example:** ```json theme={null} "form_icon_theme": "dark" ``` ![form\_icon\_theme example](https://files.readme.io/db5c245-form_icon_theme.png) *** ### form\_text\_color `form_text_color` (string): The color of the text in the form UI. **Example:** ```json theme={null} "form_text_color": "#333333" ``` ![form\_text\_color example](https://files.readme.io/bf28cf3-form_text_color.png) *** ### form\_accent\_color `form_accent_color` (string): The accent color in the form UI. **Example:** ```json theme={null} "form_accent_color": "#4b9fd7" ``` ![form\_accent\_color example](https://files.readme.io/5bd4817-form_accent_color.png) *** ### form\_border\_color `form_border_color` (string): The color of the borders in the form UI. **Example:** ```json theme={null} "form_border_color": "#333333" ``` ![form\_border\_color example](https://files.readme.io/feaf532-form_border_color.png) *** ### form\_background\_color `form_background_color` (string): The background color of the form UI. **Example:** ```json theme={null} "form_background_color": "#ffffff" ``` ![form\_background\_color example](https://files.readme.io/4585647-form_background_color.png) *** ### form\_button\_text\_color `form_button_text_color` (string): The color of the text on the form button. **Example:** ```json theme={null} "form_button_text_color": "#ffffff" ``` ![form\_button\_text\_color example](https://files.readme.io/f1c6620-form_button_text_color.png) *** ### form\_button\_background\_color `form_button_background_color` (string): The background color of the form button. **Example:** ```json theme={null} "form_button_background_color": "#499fd7" ``` ![form\_button\_background\_color example](https://files.readme.io/db67588-form_button_background_color.png) *** ### form\_input\_text\_color `form_input_text_color` (string): The color of the text in the form input fields. **Example:** ```json theme={null} "form_input_text_color": "#333333" ``` ![form\_input\_text\_color example](https://files.readme.io/47054a8-form_input_text_color.png) *** ### form\_input\_background\_color `form_input_background_color` (string): The background color of the form input fields. **Example:** ```json theme={null} "form_input_background_color": "#ffffff" ``` ![form\_input\_background\_color example](https://files.readme.io/5f350b8-form_input_background_color.png) *** ### alert\_color `alert_color` (string): The color of the alert message. **Example:** ```json theme={null} "alert_color": "#d12230" ``` ![alert\_color example](https://files.readme.io/64fd4ad-alert_color.png) *** ### input\_variant `input_variant` (string): The variant of the input field. Only accepted values: `outlined`, `filled`, or `standard`. **Example:** ```json theme={null} "input_variant": "outlined" ``` ![input\_variant example](https://files.readme.io/2dd9289-input_variant.png) *** ### success\_color `success_color` (string): The color of the success message in the order confirmation. **Example:** ```json theme={null} "success_color": "#28ab75" ``` ![success\_color example](https://files.readme.io/63eaae0-success_color.png) *** ### mobile\_icon\_theme `mobile_icon_theme` (string): The theme of the icons used in the mobile UI. Only two values are accepted: `dark` or `light`. **Example:** ```json theme={null} "mobile_icon_theme": "dark" ``` ![mobile\_icon\_theme example](https://files.readme.io/498afc1-mobile_icon_theme.png) *** ### mobile\_text\_color `mobile_text_color` (string): The color of the text in the mobile UI. **Example:** ```json theme={null} "mobile_text_color": "#333333" ``` ![mobile\_text\_color example](https://files.readme.io/e93c28c-mobile_text_color.png) *** ### mobile\_background\_color `mobile_background_color` (string): The background color of the mobile UI. **Example:** ```json theme={null} "mobile_background_color": "#ffffff" ``` ![mobile\_background\_color example](https://files.readme.io/7738182-mobile_background_color.png) *** ### mobile\_button\_text\_color `mobile_button_text_color` (string): The color of the text on the mobile button. **Example:** ```json theme={null} "mobile_button_text_color": "#ffffff" ``` ![mobile\_button\_text\_color example](https://files.readme.io/db6ef4f-mobile_button_text_color.png) *** ### mobile\_button\_background\_color `mobile_button_background_color` (string): The background color of the mobile button. **Example:** ```json theme={null} "mobile_button_background_color": "#4d9ed7" ``` ![mobile\_button\_background\_color example](https://files.readme.io/2739cb3-mobile_button_background_color.png) *** ### mobile\_input\_text\_color `mobile_input_text_color` (string): The color of the text in the mobile input fields. **Example:** ```json theme={null} "mobile_input_text_color": "#333333" ``` ![mobile\_input\_text\_color example](https://files.readme.io/d6b16dc-mobile_input_text_color.png) *** ### mobile\_input\_background\_color `mobile_input_background_color` (string): The background color of the mobile input fields. **Example:** ```json theme={null} "mobile_input_background_color": "#ffffff" ``` ![mobile\_input\_background\_color example](https://files.readme.io/2d54648-mobile_input_background_color.png) *** ### mobile\_input\_border\_color `mobile_input_border_color` (string): The color of the border in the mobile input fields. **Example:** ```json theme={null} "mobile_input_border_color": "#333333" ``` ![mobile\_input\_border\_color example](https://files.readme.io/01c2b74-mobile_input_border_color.png) *** ### invoice\_mobile\_background\_color `invoice_mobile_background_color` (string): The background color of the invoice in the mobile UI. **Example:** ```json theme={null} "invoice_mobile_background_color": "#f0f1f2" ``` ![invoice\_mobile\_background\_color example](https://files.readme.io/54b7016-invoice_mobile_background_color.png) *** ### invoice\_mobile\_text\_color `invoice_mobile_text_color` (string): The color of the text in the invoice in the mobile UI. **Example:** ```json theme={null} "invoice_mobile_text_color": "#333333" ``` ![invoice\_mobile\_text\_color example](https://files.readme.io/633dc9a-invoice_mobile_text_color.png) *** ### mobile\_accent\_color `mobile_accent_color` (string): The accent color in the mobile UI. **Example:** ```json theme={null} "mobile_accent_color": "#4d9ed7" ``` ![mobile\_accent\_color example](https://files.readme.io/29e1157-mobile_accent_color.png) # Parent `postMessage` Events The dynamic checkout iframe sends events to its embedding parent window via `window.parent.postMessage(...)`. Every message has: * `type` — event name (string) * `timestamp` — `Date.now()` (number, ms since epoch) * Plus event-specific fields described below > **Security:** messages are sent with target `"*"`. The parent **must** verify `event.origin` against the iframe's known origin before trusting any payload. > > `event.origin` will be the iframe's origin (the sender), **not** the parent's own. Use the domain you set in the iframe's `src` attribute: `https://shop.ecrypt.com`. > > The examples below show this pattern. *** ## Event reference ### 1. `page_ready` Fires when the iframe page loads successfully (after the React app mounts). **Payload:** ```js theme={null} { type: "page_ready", timestamp: 1746500000000 } ``` *** ### 2. `payment_approved` Fires when the payment was successfully processed by the gateway. **Payload:** ```js theme={null} { type: "payment_approved", timestamp: 1746500000000, transactionId: "abc123xyz", // gateway transaction ID amount: 49.99 // amount charged (USD) } ``` *** ### 3. `payment_declined` Fires when the gateway accepted the request but **declined** the payment (e.g. insufficient funds, CVV mismatch, fraud rules). API call succeeded, the gateway said "no". **Payload:** ```js theme={null} { type: "payment_declined", timestamp: 1746500000000, transactionId: "abc123xyz", // may be empty if the gateway didn't return one reason: "Insufficient funds" // gateway-provided message, or generic fallback } ``` *** ### 4. `payment_error` Fires when the payment **API call itself failed** — not a decline. Examples: `404`, `500`, network timeout, encryption failure before the request was sent. Different from `payment_declined`: here we never got a clean answer from the gateway. **Payload:** ```js theme={null} { type: "payment_error", timestamp: 1746500000000, reason: "Network Error", // exception message or generic fallback status: 500 // HTTP status if available, otherwise null } ``` *** ### 5. `page_error` Fires when the iframe page fails to load or render. Covers three categories: * **Initial load failure** — the server-side render couldn't satisfy the page: * `reason: "MISSING-ID"` — the `id` query param was missing from the iframe URL * `reason: "NO-DATA"` — the API call to fetch checkout appearance/config returned no data for the supplied `id` * **React rendering crash** — caught by the page's `ErrorBoundary` (e.g. an undefined state, bad API shape during render) * **Unhandled runtime error** — fired from `window.onerror` or an `unhandledrejection` **Payload:** ```js theme={null} { type: "page_error", timestamp: 1746500000000, reason: "MISSING-ID" // or "NO-DATA" // or a JS error message like "Cannot read properties of undefined (reading 'foo')" } ``` > After firing `page_error` for initial-load failures, the iframe will navigate to its internal `/error` page. The parent typically doesn't need to do anything beyond logging — but you may want to surface a "checkout link is invalid" message to the user. *** ## Parent-side example (full listener) ```html theme={null} ``` *** ## Summary Five events, all flat payloads, all include `type` + `timestamp`: | Event | Fired when | | ------------------ | -------------------------------------------------------------------- | | `page_ready` | iframe finishes loading | | `payment_approved` | gateway approved the payment | | `payment_declined` | gateway declined the payment | | `payment_error` | payment API call itself failed (network/HTTP error, not a decline) | | `page_error` | iframe page failed to load (missing `id`, no data, or runtime crash) | # Cloud Terminal Source: https://docs.ecrypt.com/guides/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](/guides/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} POST https://api.ecrypt.com/v1/terminals ``` ```json 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} { "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} 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} POST https://api.ecrypt.com/v1/transactions/sale ``` **Request:** ```json 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} { "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} 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} POST https://api.ecrypt.com/v1/transactions/capture ``` ```json 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} 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} 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} 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](https://docs.ecrypt.com/api-reference/gateway/terminals/create). *** ## 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. # Customers Overview Source: https://docs.ecrypt.com/guides/customers-overview Store customer profiles and payment methods to enable on-file charging, subscriptions, and more. ## What Is a Customer? A customer record in ECRYPT stores profile information and saved payment methods. Once created, a customer can be charged directly through the API without re-collecting card or bank account details. ECRYPT automatically generates a unique ID when a customer record is saved. *** ## Customer Profile Customer profiles are organized into four field groups: ### Personal Information | Field | Description | | --------------- | -------------------------------- | | Customer name | Full name | | Mailing address | Mailing address | | Email address | Email address | | Phone number | Phone number | | Customer ID | Auto-generated unique identifier | ### Credit Card Details | Field | Description | | ------------------ | ---------------------- | | Cardholder name | Name on card | | Credit card number | Card number | | Expiration date | Card expiration date | | Billing address | Billing street address | | Billing zip code | Billing zip code | ### ACH Details | Field | Description | | ---------------- | ---------------------- | | Accountholder | Name on bank account | | Account number | Bank account number | | Routing number | Bank routing number | | Billing address | Billing street address | | Billing zip code | Billing zip code | ### Shipping Information | Field | Description | | ---------------- | ----------------------- | | Shipping address | Shipping street address | | City | City | | State | State | | Zip code | Zip code | | Country | Country | | Phone number | Shipping phone number | *** ## Merchant-Defined Fields Merchant-defined fields are custom fields that can be added to customer records and displayed in checkout experiences. You can create up to **21 merchant-defined fields** and choose from the following field types: | Field Type | Description | | ------------ | --------------------------------------------------------------------------------------------- | | Text Box | Simple text input for data like reference IDs, names, phone numbers, and similar values | | Dropdown | A selection list allowing the customer or merchant to choose one option from multiple choices | | Radio Select | A checkbox-style input for yes/no questions or multi-option selection | Merchant-defined fields are configured in your ECRYPT dashboard and returned alongside the customer profile in API responses. *** ## Customer Wallet Each customer profile includes a wallet that can hold up to **4 payment methods**. Both credit card and ACH payment methods are supported. All card numbers and bank account numbers are tokenized and displayed as truncated values. ECRYPT does not store raw payment data after the initial tokenization, removing your responsibility for storing sensitive payment information. *** ## Common Use Cases ### Charge a Customer on File Once a customer has a saved payment method, you can charge them by referencing their customer ID and wallet token -- no need to re-collect payment details. Useful for repeat purchases, invoicing, and agent-assisted payments. ### Subscriptions Subscriptions are linked to a customer record and automatically charge a designated wallet payment method on a defined schedule. See [Subscriptions](/docs/subscriptions). ### Installment Plans Installment plans split a total amount into scheduled charges against a customer's wallet. Like subscriptions, they are tied to a customer record and run automatically. See [Installment Plans](/docs/installment-plans). ### Stored Card at Checkout During an online checkout flow, returning customers can select a saved card from their wallet rather than re-entering payment details. This is supported through the [Hosted iFrame](/docs/hosted-iframe) and [Checkout Page](/docs/checkout-page) by passing a customer reference at load time. # Definitions Source: https://docs.ecrypt.com/guides/definitions A glossary of key terms used throughout the ECRYPT documentation and the payments industry. *** ## A **ACH (Automated Clearing House)** An electronic funds transfer network used in the United States for processing bank-to-bank payments. ACH transactions are typically lower cost than card transactions but take longer to settle. **ACH Credit** A transaction that pushes funds from the merchant's account into a customer's bank account. Commonly used for disbursements or refunds. **ACH Debit** A transaction that pulls funds from a customer's bank account into the merchant's account. **Acquirer (Acquiring Bank)** A bank or financial institution that processes credit or debit card payments on behalf of a merchant. The acquirer routes transactions through the card networks to the issuing bank and is responsible for depositing settled funds into the merchant's account. **API (Application Programming Interface)** A set of protocols and tools that allow two software systems to communicate with each other. ECRYPT provides a RESTful API for processing payments, managing customers, and retrieving transaction data. **API Key** A credential used to authenticate requests to the ECRYPT API. See Public API Key and Private API Key. **Authentication** The process of verifying the identity of a user, device, or system before granting access. In payments, authentication may also refer to verifying a cardholder's identity during a transaction (see 3D Secure). **Authorization** A request sent to the card-issuing bank to verify that the cardholder has sufficient funds and that the card is valid. An authorization places a temporary hold on the funds but does not transfer money. **Authorization Code** A numeric or alphanumeric code returned by the issuing bank when a transaction is approved. This code confirms the authorization and is included in the transaction record for reference. **AVS (Address Verification System)** A fraud prevention tool that compares the billing address provided by the cardholder during a transaction with the address on file at the issuing bank. The result is returned as an AVS response code indicating a full match, partial match, or no match. *** ## B **Batch** A group of transactions that are submitted together for settlement at the end of a processing period, usually once per day. **BIN (Bank Identification Number)** The first six to eight digits of a card number that identify the issuing bank, card brand, and card type (credit, debit, prepaid). Also referred to as an IIN (Issuer Identification Number). *** ## C **Capture** The process of finalizing an authorized transaction so that funds are transferred from the cardholder's account to the merchant's account. A transaction must be captured before it can be settled. **Card Network** An organization that facilitates the routing of payment transactions between acquirers and issuers. The major card networks include Visa, Mastercard, American Express, and Discover. Card networks set interchange rates, establish processing rules, and manage dispute resolution procedures. **Card Not Present (CNP)** A transaction where the cardholder does not physically present their card to the merchant, such as online or phone orders. CNP transactions generally carry higher fraud risk and may have higher interchange rates. **Card Present (CP)** A transaction where the cardholder physically presents their card at a terminal, either by tapping (contactless), inserting the chip, or swiping the magnetic stripe. **Cardholder** The individual or entity to whom a credit or debit card has been issued. The cardholder is responsible for charges made on the card and is the party who may initiate a dispute. **Chargeback** A forced reversal of a transaction initiated by the cardholder's issuing bank, typically as the result of a dispute. The merchant loses the transaction amount, and a chargeback fee is usually assessed. Merchants can contest chargebacks by submitting evidence that the transaction was valid. **Checkout Page** A fully hosted, ECRYPT-branded payment page that customers are redirected to in order to complete a transaction. Requires no frontend development on the merchant's side. **Clearing** The process of exchanging financial transaction data between the acquirer and issuer after a transaction has been authorized. Clearing prepares transactions for final settlement. **Customer** A stored record in ECRYPT representing an individual or business that makes payments. Customer records can hold contact information, payment methods, and billing history. **Customer ID** A unique identifier assigned by ECRYPT to each stored customer record. Use this ID to reference, charge, or manage a customer through the API. **Customer Wallet** A secure, tokenized collection of one or more saved payment methods (cards, bank accounts) associated with a customer record. Wallets allow returning customers to pay without re-entering their payment details. **CVV / CVC (Card Verification Value / Code)** A three- or four-digit security code printed on a payment card (not stored in the magnetic stripe or chip). Used in card-not-present transactions to help verify that the person making the payment has physical possession of the card. *** ## D **Decline** A response from the issuing bank or card network indicating that a transaction cannot be approved. Declines can be hard (the card is permanently invalid, expired, or reported lost) or soft (temporary issues like insufficient funds or network timeouts). **Device Management** The process of registering, configuring, monitoring, and deactivating physical payment terminals through the ECRYPT dashboard or API. **Disbursement** The transfer of funds from a merchant or platform to a recipient, typically via ACH credit or other payout method. **Dispute** A formal objection to a transaction raised by the cardholder through their issuing bank. If the dispute is upheld, it becomes a chargeback. Merchants can respond to disputes by submitting evidence supporting the validity of the original transaction. *** ## E **EMV (Europay, Mastercard, Visa)** A global standard for chip-based payment cards and the terminals that accept them. EMV chip cards generate a unique transaction code for each payment, making them significantly more secure against fraud than magnetic stripe cards. **Encryption** The process of converting sensitive data into an unreadable format using a cryptographic algorithm. ECRYPT encrypts cardholder data in transit and at rest to protect against unauthorized access. **Environment** A configuration setting that determines whether API requests are processed against the ECRYPT sandbox (for testing) or live (for real transactions). Each environment has its own set of API keys. *** ## F **Fraud** Unauthorized or deceptive activity intended to result in financial gain at the expense of the cardholder, merchant, or payment processor. Common types include stolen card use, account takeover, and friendly fraud (where the legitimate cardholder disputes a valid charge). *** ## G **Gateway** A service that securely transmits payment data from a merchant's website or terminal to the payment processor for authorization. ECRYPT functions as both a gateway and processor. *** ## H **Hosted Iframe** A pre-built, PCI-compliant payment form that is embedded directly into your website using an HTML iframe. The iframe is hosted by ECRYPT, which keeps sensitive card data off your servers and reduces your PCI compliance burden. *** ## I **Idempotency** A property of an API request that ensures making the same request multiple times produces the same result as making it once. ECRYPT supports idempotency keys to prevent duplicate charges caused by network retries or timeouts. **Installment Plan** A structured payment schedule that breaks a total amount into a fixed number of smaller charges over time. **Interchange** The transfer of transaction data and funds between acquirers and issuers through the card networks. Also refers to the fee structure associated with these transfers. **Interchange Fee** A fee set by the card networks and paid by the acquirer to the issuing bank on each transaction. Interchange fees vary based on card type, merchant category, and how the transaction is processed. These fees are a primary component of overall processing costs. **Issuer (Issuing Bank)** The bank or financial institution that issues a credit or debit card to a cardholder on behalf of a card network. The issuer is responsible for approving or declining transactions, extending credit, and handling cardholder disputes. *** ## K **KPI (Key Performance Indicator)** A measurable value that tracks how effectively a business or system is achieving a specific objective. Common payment KPIs include authorization rate, chargeback rate, average transaction value, and settlement time. *** ## L **Latency** The time elapsed between sending an API request and receiving a response. Low latency is critical in payment processing to ensure fast checkout experiences. **Level 2 and Level 3 Data** Enhanced transaction data submitted with B2B and government card payments. Level 2 includes fields like tax amount and customer reference number. Level 3 adds line-item detail such as item descriptions, quantities, and unit costs. Providing this data can result in lower interchange rates. **LLM (Large Language Model)** A type of artificial intelligence model trained on large volumes of text data, capable of understanding and generating natural language. In a payments context, LLMs may be used to power support chatbots, analyze transaction data, or assist with documentation search. *** ## M **Merchant** A business or individual that accepts payment in exchange for goods or services. In the context of ECRYPT, the merchant is the entity integrating with the API to process payments. **Merchant Category Code (MCC)** A four-digit code assigned by card networks to classify a business by the type of goods or services it provides. MCCs influence interchange rates and may affect whether certain transaction types (such as surcharging) are permitted. **Merchant ID (MID)** A unique identifier assigned to a merchant by their acquirer or payment processor. The MID is used to route and identify transactions associated with that merchant's account. *** ## N **NACHA** The National Automated Clearing House Association, which governs the rules and standards for the ACH network in the United States. *** ## P **Pagination** A method of dividing large API response sets into smaller, sequential pages. ECRYPT uses cursor-based or offset-based pagination to return transaction lists, customer records, and other collections efficiently. **Payment Method** Any instrument a customer uses to pay for a transaction. Common payment methods include credit cards, debit cards, ACH transfers, and digital wallets. **Payment Processor** A company that handles the technical routing of transaction data between merchants, acquirers, card networks, and issuers. ECRYPT acts as a payment processor for its merchants. **PCI-DSS (Payment Card Industry Data Security Standard)** A set of security standards established by the PCI Security Standards Council (founded by Visa, Mastercard, American Express, Discover, and JCB) to protect cardholder data. All merchants and service providers that store, process, or transmit card data must comply with PCI-DSS. **Private API Key** A server-side credential used to authenticate API requests that perform sensitive operations such as charging a card, issuing refunds, or accessing customer data. Private API keys must be kept confidential and should only be stored on your server. Never expose a private API key in client-side code, version control, or logs. **Product Code** A classification code assigned to a transaction that identifies the type of card or payment method used, such as Visa credit, Mastercard debit, or prepaid. **Public API** The externally accessible interface that developers use to integrate ECRYPT into their applications. All endpoints documented in ECRYPT's developer docs are part of the public API. **Public API Key** A client-side credential used to identify your account when making API requests from environments visible to end users, such as a browser or mobile app. Public API keys can only be used for limited, non-sensitive operations like tokenizing card data. They should never be treated as secret, but they should not be shared outside your organization. *** ## R **Rate Limiting** A mechanism that restricts the number of API requests a client can make within a given time window. Rate limits protect the platform from abuse and ensure consistent performance for all users. **Receipt** A record of a completed transaction provided to the cardholder or merchant. Receipts typically include the transaction amount, date, payment method, authorization code, and merchant information. **Reconciliation** The process of matching transaction records in ECRYPT with corresponding entries in your bank statements or accounting system to verify accuracy. **Recurring Billing** A billing model where a customer is automatically charged on a regular schedule (daily, weekly, monthly, annually) for ongoing goods or services. See Subscription and Installment Plan. **Refund** A reversal of a previously captured transaction that returns funds to the cardholder. Refunds can be full or partial. **Response Code** A standardized numeric or alphanumeric code returned by the payment processor or issuing bank that indicates the result of a transaction attempt. Examples include approval codes, decline codes, and error codes. See the Response Codes reference for a full list. **Retry Logic** The automated process of re-attempting a failed recurring payment according to configurable rules, such as retry intervals and maximum attempts, before marking the payment as permanently failed. *** ## S **Sandbox** A testing environment that simulates live payment processing without moving real money. Used during development and QA to validate integrations before going live. **SDK (Software Development Kit)** A collection of libraries, code samples, and documentation that simplifies integration with the ECRYPT API in a specific programming language or platform. **Settlement** The process by which captured transactions are finalized and funds are deposited into the merchant's bank account. Settlement typically occurs in daily batches. **Statement Descriptor** The text that appears on a cardholder's bank or credit card statement to identify a transaction. Clear and recognizable statement descriptors help reduce chargebacks caused by cardholders who do not recognize a charge. **Subscription** An automated, recurring charge at a fixed interval (such as weekly, monthly, or annually) for an ongoing service or product. **Surcharge** An additional fee added to a transaction to offset the cost of credit card processing. Surcharging rules vary by card network and jurisdiction. *** ## T **Terminal** A physical device used to accept in-person card payments, including tap (contactless), dip (chip), and swipe transactions. **3D Secure (3DS)** An authentication protocol that adds an extra verification step during online card transactions. The cardholder is prompted to verify their identity (for example, via a one-time passcode or biometric confirmation) before the transaction is approved. 3D Secure shifts fraud liability from the merchant to the issuer for authenticated transactions. **Tipping** A feature that allows customers to add a gratuity during the payment flow on a terminal or checkout page. **Token / Tokenization** The process of replacing sensitive payment data (such as a card number) with a non-sensitive placeholder value called a token. Tokens can be stored and used for future transactions without exposing the original data, reducing PCI scope. **Transaction** A single payment event processed through ECRYPT. Transactions can be card-based, ACH-based, or associated with a recurring billing cycle. **Transaction ID** A unique alphanumeric identifier assigned by ECRYPT to every transaction. Use this ID to reference, query, or look up a specific transaction through the API or dashboard. *** ## U **Uptime** The percentage of time the ECRYPT platform is operational and available. Typically expressed as a percentage in a service level agreement (SLA), such as 99.99% uptime. *** ## V **Void** The cancellation of an authorized transaction before it has been captured or settled. Voided transactions release the hold on the cardholder's funds. *** ## W **Webhook** A mechanism that sends real-time HTTP POST notifications to your server when specific events occur in ECRYPT, such as a completed transaction or a failed payment. Webhooks eliminate the need to poll the API for updates. *** ## Additional Terms **Changelog** A chronological record of updates, bug fixes, and new features released for the ECRYPT API and platform. Developers should review the changelog regularly to stay informed about breaking changes and deprecations. **Tax Rate** A percentage applied to a transaction to calculate the tax amount due. ECRYPT supports configurable tax rates that can be associated with specific products or transactions. # Developer Support Source: https://docs.ecrypt.com/guides/developer-support ## Integration Support For help with your API integration, ECRYPT's developer support team is available to assist. **Email:** [devsupport@ecrypt.com](mailto:devsupport@ecrypt.com)
**Phone:** (800) 935-9309 To help expedite troubleshooting, include the full request payload and any error responses you received. Never include raw card data or other sensitive PCI-scoped information in your support request. ## Account Support Your dedicated account manager, assigned during onboarding, is your first point of contact for anything related to your ECRYPT account. If you do not have your account manager's contact information, reach out to general support. **Email:** [support@ecrypt.com](mailto:support@ecrypt.com)
**Phone:** (800) 935-9309 # Environments & Keys Source: https://docs.ecrypt.com/guides/environments Understand the difference between Sandbox and Production environments, and how to use your API keys correctly. ## Overview The API operates in two separate environments: **Sandbox** and **Production**. Each environment has its own set of API keys, ensuring your testing and development work never interferes with live transactions. ## Environments ### Sandbox The Sandbox environment is your safe space for development, QA, and integration testing. It behaves like Production but processes no real money and all transactions are simulated with test payment methods. * Use test card numbers and ACH account numbers to simulate payment scenarios * Responses mirror Production behavior without triggering real charges * Ideal for building integrations, running automated tests, and onboarding new developers See the [Testing](/guides/testing) guide for a full list of supported test cards and ACH account numbers. ### Production The Production environment processes real transactions with real funds. Only switch to Production once your integration has been validated in Sandbox. * All API calls result in actual charges and transfers * Requires an activated merchant account * Keep Production keys strictly separate from your Sandbox keys *** ## API Keys Each environment (Sandbox and Production) has its own set of three API keys. Never mix keys across environments. | Key | Where It's Used | Purpose | | --------- | ---------------------- | ---------------------------------- | | Public | Frontend / Client-side | Sending tokenization requests | | Private | Backend / Server-side | All operations post tokenization | | Reporting | Backend / Server-side | Pulling transaction and batch data | ### Public Key The Public key is used on the **frontend** to submit card or ACH details and request a payment token. Because it is embedded in client-facing code, its scope is intentionally limited to tokenization only — it cannot initiate or modify transactions. * Used in your frontend integration (Hosted iFrame or Checkout Page) * Safe to expose in browser environments * Cannot be used to run sales, refunds, or any other transaction operations ### Private Key The Private key is used on your **backend** to perform all transaction operations after a token has been obtained. This includes: * **Charges:** Sale, Authorization * **Post-transaction operations:** Capture, Void, Refund * **Customer management:** Create and manage customer profiles and saved payment methods * **Recurring billing:** Create and manage subscriptions and installment plans Your Private key must never be exposed in client-facing code or public repositories. Treat it like a password — store it in an environment variable or secrets manager. ### Reporting Key The Reporting key provides **read-only** access to your transaction and batch data. It is scoped exclusively to reporting endpoints and cannot be used to initiate or modify transactions. * Use it to power internal dashboards, reconciliation tools, and financial reporting * Limit access to trusted internal services only *** ## Managing Your Keys You can find your Sandbox and Production API keys in the dashboard under **Settings → Developer Tools → API Keys**. * Keys are environment-specific. Your Sandbox and Production keys are listed separately * To regenerate a key, navigate to the key in your dashboard and select **Generate Key** * Rotating a key immediately invalidates the previous key, so make sure to update all services before rotating in Production *** ## Public IP Addresses Use these IPs to allow ECRYPT's servers for webhooks and inbound API traffic. ```text theme={null} 52.26.189.58 44.232.175.238 44.224.200.173 52.33.202.58 ``` *** ## Security Best Practices * **Never hardcode keys** in your source code or commit them to version control * **Use environment variables** or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) to inject keys at runtime * **Restrict Reporting key access** to internal services. It should never be used client-side * **Rotate keys immediately** if you suspect they have been compromised * **Audit access regularly** and revoke keys for any services that no longer need them # Error Handling Source: https://docs.ecrypt.com/guides/error-handling Error codes indicate whether an API request succeeded or failed. When a payment flow fails, the error code tells you what went wrong and helps you resolve the issue. ## HTTP Error Codes | Code | Status | Description | | :----------------- | :---------------- | :-------------------------------------------------------------------------------------------- | | 200 | OK | The request succeeded. | | 400 | Bad Request | The request was unacceptable, often due to a missing or invalid parameter. | | 401 | Unauthorized | No valid API key was provided. | | 402 | Request Failed | The parameters were valid but the request failed. | | 403 | Forbidden | The API key does not have permission to perform this request. | | 404 | Not Found | The requested resource does not exist. | | 409 | Conflict | The request conflicts with another request, such as a duplicate idempotency key. | | 429 | Too Many Requests | Too many requests were sent in a short period. Use exponential backoff when retrying. | | 500, 502, 503, 504 | Server Error | Something went wrong on ECRYPT's end. These are rare. If the issue persists, contact support. | ## Error Objects When a request fails, the response body includes an `errors` array with details about what went wrong. ```json theme={null} { "requestId": "abc123", "errors": [ { "type": "VALIDATION", "message": "The amount field is required." } ] } ``` | Field | Type | Description | | :----------------- | :----- | :------------------------------------------------------------------------- | | `requestId` | string | A unique identifier for the request. Include this when contacting support. | | `errors[].type` | string | The category of error. | | `errors[].message` | string | A description of what went wrong. | ## Errors Handling Guidelines **400 errors** are caused by your request. Check that all required fields are present and that values match the expected types and formats. **401 and 403 errors** indicate an authentication or permissions issue. Verify that you are using the correct API key for the environment and that the key has the necessary access level. **429 errors** mean you have exceeded the rate limit. Implement exponential backoff so your retry attempts increase in wait time with each failed attempt rather than hammering the API repeatedly. **5xx errors** originate on ECRYPT's servers. Retry the request using exponential backoff. If the issue persists, contact [ECRYPT support](https://www.ecrypt.com). # Google Pay™ Source: https://docs.ecrypt.com/guides/google-pay Accept Google Pay™ through Ecrypt's hosted checkout products. Google Pay™ lets shoppers check out with any credit or debit card saved to their Google Account. Ecrypt handles the wallet flow on our hosted pages, allowing you to enable Google Pay™ without building or certifying the wallet integration yourself. ## At a glance | | | | ----------------------------- | ------------------------------------------------- | | **Channels** | Dynamic Checkout, iFrame, Payment Links, Invoices | | **Cardholder locations** | All countries where Google Wallet is supported | | **Settlement currency** | USD | | **Domain registration** | Not required | | **Recurring billing** | Supported | | **Refunds / partial refunds** | Supported | | **Voids** | Supported | ## Where Google Pay™ is available in Ecrypt Google Pay™ is currently offered only through Ecrypt's hosted checkout surfaces. When a shopper lands on one of these pages from a compatible device and browser, the Google Pay™ button renders automatically alongside the standard card form: * **Dynamic Checkout**: full-featured, hosted checkout page created with the `/v1/dynamiccheckout` endpoint. * **Hosted iFrame**: Populate Google Pay™ in Ecrypt's hosted iFrame underneath card fields. * **Payment Links**: shareable URLs that accept a single payment or kick off a subscription. * **Invoices**: customer-facing invoice pages with a pay-now action. ## No domain registration needed Some processors require merchants to register every domain that displays a Google Pay™ button. Because the button renders on pages served from Ecrypt's own domain, you don't need to register anything. You can embed Dynamic Checkout in an iframe on your own site, email a Payment Link, or send an Invoice, and Google Pay™ will show up without additional setup. ## Accepting inbound international payments Ecrypt accepts Google Pay™ from shoppers in any country where Google Wallet operates. The cardholder selects their saved Google Wallet card, and Ecrypt processes it as a standard card transaction. Settlement happens in USD to your merchant account, following your normal funding schedule. For an up-to-date list of countries where shoppers can use Google Wallet, see [Google's supported countries list](https://support.google.com/wallet/answer/12060037). ## Recurring billing and subscriptions Google Pay™ works with Ecrypt subscriptions. When a customer completes their first payment through Dynamic Checkout that includes a `subscription` object, the resulting payment credential is saved to the customer's wallet and reused for each recurring charge on the cycle you define. Once the initial Google Pay™ charge succeeds, Ecrypt stores the customer's tokenized payment method and handles every subsequent billing cycle automatically. No extra work is needed on your end to flag the payment as recurring — Ecrypt marks the stored credential appropriately so follow-on charges run as merchant-initiated transactions. For details on cycle types and billing dates, see the [Subscriptions](https://docs.ecrypt.com/subscriptions) reference. ## Post-payment operations Google Pay™ transactions settle as standard card transactions in Ecrypt, so you can manage them exactly like any other credit card charge. Refunds (full or partial), voids on unsettled authorizations, and chargeback responses all run through the same endpoints and dashboard workflows you already use for card payments. Google Pay™ transactions also appear in reporting with the `paymentNetwork` set to the underlying card brand (Visa, Mastercard, and so on), making them easy to reconcile alongside your other card volume. ## Data Verification **Payment Data**
Ecrypt handles the generation of the `PaymentDataRequest` and manages the encrypted payloads securely. Merchants are not required to manually configure variables like gateway IDs, card networks, authorization methods, etc. **Billing Address Data**
Ecrypt automatically configures the `BillingAddressParameters` within the Google Pay™ payment sheet. Dynamic Checkout collects the buyer's billing address directly and securely for address verification. No additional code or custom billing address configuration is required on the merchant's end to process these transactions. ## Testing To test the Google Pay™ flow end-to-end: 1. Generate a Dynamic Checkout, Payment Link, or Invoice in your Ecrypt **sandbox** environment. 2. Open the resulting URL on a physical Android device, or in Chrome on a desktop logged into a Google account that has at least one card saved to Google Wallet. 3. Complete the flow using Google's [test card suite](https://developers.google.com/pay/api/android/guides/resources/test-card-suite) or a real card saved to your Google Wallet (sandbox charges are not settled). Google Pay™ will only render on devices and browsers that meet Google's own eligibility rules: an HTTPS connection, a supported browser, and a Google account with a saved card. If the button doesn't appear, those are the first things to check. ### Embedding Dynamic Checkout in an iFrame If you're testing Dynamic Checkout inside an ` ``` * `allow-popups` and `allow-popups-to-escape-sandbox` let the Google Pay™ window open and operate on Google's domain. * `allow-same-origin` is required so Ecrypt's checkout page can talk to its own origin. * `allow-scripts` and `allow-forms` are required for the page itself to function. * `allow="payment"` enables the Payment Request API that Google Pay™ relies on. The simplest option is omitting the `sandbox` attribute entirely. This gives the iFrame full permissions. Only use `sandbox` if you have a specific reason to restrict what the frame can do. ## Turn Google Pay™ on The Ecrypt team activates Google Pay™ by request. Reach out to your Ecrypt account representative or contact [support](https://support.ecrypt.com) to get started. Merchants using Ecrypt's hosted checkout with Google Pay™ enabled are required to adhere to the [Google Pay and Wallet API's Acceptable Use Policy](https://payments.developers.google.com/terms/aup) and accept the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos). ## Resources from Google Pay™ * [Google Pay™ Web Developer Documentation](https://developers.google.com/pay/api/web/overview) * [Google Pay™ Web Integration Checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) * [Google Pay™ Web Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) # Quickstart Source: https://docs.ecrypt.com/guides/guides-quickstart ECRYPT handles the complexity of payments so you can focus on building. This guide walks you through the core flows to get up and running quickly. *** ## Get Started Create a test account and generate your API key to start building with ECRYPT Integrate hosted iFrame or Dynamic Checkout pages to accept card payments online. Connect Cloud EMV devices to accept in-person card-present payments through the ECRYPT API. Configure recurring billing, installment plans, and automated retry logic for failed payments. Use ECRYPT's sandbox environment and test card numbers to validate your integration end-to-end. Accept bank account payments alongside cards using the same token-based payment flow. Schedule your certification call to confirm all endpoints and flows are ready to go before going live. *** ## Your First API Call Every request to the ECRYPT API requires an `X-Api-Key` header. Generate your key in **Settings > API/Security Keys**. The first step in any payment flow is tokenizing card data. Tokenization keeps sensitive PAN data off your servers and removes your integration from PCI scope. **Request** ```bash theme={null} curl --request POST \ --url https://api.ecrypt.com/v1/tokens \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'X-Api-Key: YOUR_API_KEY' \ --data '{ "credit_card": { "name_on_card": "John Doe", "account_number": "4111111111111111", "expires": "0135", "verification_value": "000", "postal_code": "90210" } }' ``` **Response** ```json theme={null} { "token": "95222bfc-d032-4aa6-a949-3c000ad93b4b", "metadata": { "credit_card_number": "4***********1111", "credit_card_network": "visa", "credit_card_type": "credit" }, "request_id": "0HNJOGLAUDGRT00000057" } ``` The `token` value is what you pass into subsequent transaction requests in place of raw card data. The `metadata` object returns masked card details you can display to users for confirmation. The full card number is never returned. Use the `requestId` for support inquiries or debugging. *** ## Next Steps 1. **Environments and Keys** -- Understand sandbox vs. production and how to manage your API keys. 2. **How Payments Work** -- The full authorization, capture, and settlement lifecycle. 3. **Testing** -- Dummy card numbers and ACH account numbers for validating your integration. 4. **Webhooks Setup** -- Get notified in real time when transactions change state. # How Payments Work Source: https://docs.ecrypt.com/guides/how-payments-work-1 A developer's guide to payment fundamentals, common transaction flows, payment methods and compliance. *** ## Overview This guide covers the fundamentals of how credit card and ACH payments are processed through the ECRYPT platform. Whether you are building a direct API integration, embedding ECRYPT's hosted iframe, or connecting Cloud EMV terminals, the underlying transaction lifecycle follows the same core pattern. Understanding this lifecycle will help you choose the right transaction type for your use case, handle edge cases like voids and refunds correctly, and build more reliable payment flows. > **Note:** This guide focuses on concepts. For endpoint-specific request and response schemas, refer to the [API Reference](https://docs.ecrypt.com/api-reference). *** *** ## Credit Card Transaction Lifecycle Every credit card payment moves through a series of stages. The exact path depends on the transaction type you choose, but most follow a variation of the same flow: tokenize the card, request authorization from the issuing bank, capture the funds, and settle the batch. ### 1. Tokenization Before any transaction can occur, raw card data (the PAN, expiration date, and CVV) must be converted into a token. A token is a non-sensitive reference value that represents the card within ECRYPT's system. Tokens ensure the actual card data is encrypted and stored in ECRYPT's PCI Level 1 compliant token vault. Tokenization happens automatically when card data is submitted through ECRYPT's payment tools. Once tokenized, you use the resulting token for all subsequent operations (authorizations, sales, refunds, etc.) without ever handling raw card numbers again. > **PCI Scope:** Tokenization removes your application from PCI scope. Your servers never see or store raw card data, only the token passes through your system. | Concept | Description | | --------------- | ---------------------------------------------------------------------------------------------------------- | | **Token** | A non-sensitive string that maps to encrypted card data in ECRYPT's vault. Safe to store in your database. | | **PAN** | The 15–19 digit card number embossed on the physical card. You should never record or store this. | | **Token Vault** | ECRYPT's secure, encrypted storage that holds the mapping between tokens and actual card data. | ### 2. Authorization (Auth) An authorization is a request to the cardholder's issuing bank to verify that the card is valid, the account has sufficient funds, and the transaction is not flagged for fraud. If approved, the bank places a hold on the requested amount, reserving those funds for the merchant. An authorization does **not** move money. It is a promise from the issuing bank that the funds are available. The hold typically expires after 7–30 days (depending on the card network and issuer) if no capture is submitted. Common use cases for auth-only transactions include hotel check-ins (where the final total is unknown), car rentals, and any scenario where the final charge amount may differ from the initial estimate. > **Warning:** Authorizations that are never captured will eventually expire and release the hold. Avoid holding authorizations longer than necessary considering it ties up the cardholder's available credit and can lead to disputes. ### 3. Capture A capture tells ECRYPT to finalize a previously authorized transaction and include it in the next settlement batch. The capture amount can be equal to or less than the original authorization amount. You cannot capture more than the authorized amount. Once captured, the transaction moves into a pending settlement state. It will be included in the next batch that is sent to the processor for clearing. | Scenario | What Happens | | ------------------- | ----------------------------------------------------------------------------------------------- | | **Full capture** | Capture the exact amount that was authorized. The most common pattern. | | **Partial capture** | Capture less than the authorized amount. The remaining hold is released back to the cardholder. | | **No capture** | The authorization expires after the hold period. No funds are transferred. | ### 4. Settlement Settlement (also called clearing or batching) is the process by which captured transactions are submitted to the card networks for final processing. During settlement, funds are transferred from the cardholder's issuing bank to the merchant's acquiring bank. ECRYPT batches and settles transactions automatically, typically on a daily cycle. You do not need to manually trigger settlement in most configurations, though the ECRYPT dashboard and API provide visibility into batch status and timing. Auto-Close: This is your preferred cuttoff time to begin settling captured transactions each day. After settlement, the transaction is considered final. Reversals after this point require a refund (not a void). *** ## The Auth + Capture Flow The standard two-step flow for card-not-present transactions: | Step | Stage | Description | | ----- | ------------- | ------------------------------------------------------------------------------------------------------------ | | **1** | **Collect** | Cardholder enters payment details via iframe, API, or terminal. ECRYPT tokenizes the card data. | | **2** | **Authorize** | ECRYPT sends the token and amount to the processor. The issuing bank approves or declines and places a hold. | | **3** | **Capture** | Merchant confirms the final amount. ECRYPT marks the transaction for settlement. | | **4** | **Settle** | ECRYPT submits the batch. Funds move from issuer to acquirer to merchant account. | *** ## Transaction Types ECRYPT supports several transaction types beyond the standard auth + capture flow. Each serves a different purpose in the payment lifecycle. ### Sale A sale combines authorization and capture into a single step. When you submit a sale transaction, ECRYPT authorizes the card and immediately marks it for capture in the next settlement batch. This is the simplest transaction type and the most common for e-commerce purchases, subscription charges, and one-time payments where the final amount is known at checkout. Use a sale when you know the exact charge amount upfront and don't need a delay between authorization and capture. ### Auth An auth-only transaction requests authorization without capturing funds. This is the first half of the two-step auth + capture flow described above. Use an auth when the final charge amount may change (tips, hotel stays, estimated services) or when you need to verify the card before fulfilling an order. You must follow up with a capture request using the original transaction ID to finalize the charge. If you don't capture, the hold will expire and release automatically. ### Void A void cancels a transaction that has **not yet settled**. Because the funds were only held (not transferred), a void simply releases the hold on the cardholder's account. No money moves in either direction. You can void both auth-only and sale transactions, as long as the batch containing that transaction has not yet been submitted for settlement. Once a transaction has settled, you must issue a refund instead. > **Tip:** Voids are always preferable to refunds when possible. They release funds instantly, avoid interchange fees, and do not count against your chargeback ratio. ### Refund A refund returns funds to the cardholder for a transaction that has **already settled**. Unlike voids, refunds create a new transaction that credits the cardholder's account. Refunds typically take 5–10 business days to appear on the cardholder's statement. ECRYPT supports both full and partial refunds. A partial refund returns a portion of the original transaction amount. You can issue multiple partial refunds against a single transaction, as long as the total refunded does not exceed the original captured amount. To process a refund, you reference the original transaction ID. ECRYPT handles the credit routing back to the same card that was charged. ### Verification A verification (also called a zero-dollar auth or account verification) checks whether a card is valid and in good standing without placing a hold or charging the cardholder. The issuing bank confirms the card number, expiration date, and optionally the CVV and AVS data. Use verifications when you want to validate a card before storing it in the customer vault for future charges — for example, during account registration, trial sign-ups, or when a customer adds a new payment method. ### Summary | Transaction Type | When to Use | | ---------------- | ------------------------------------------------------ | | **Sale** | Final amount is known. One-step charge. | | **Auth** | Amount may change. Two-step flow required. | | **Capture** | Finalize a previous auth. Submit for settlement. | | **Void** | Cancel before settlement. No money moves. | | **Refund** | Return funds after settlement. Credits the cardholder. | | **Verification** | Validate a card without charging. Zero-dollar auth. | *** ## Before vs. After Settlement Understanding where a transaction is in the settlement cycle determines what actions are available to you. This is one of the most important concepts to internalize when building payment logic. | State | Available Actions | | -------------- | ---------------------------------------------------------------------------------------------------------- | | **Authorized** | Capture (full or partial), Void | | **Captured** | Void (if batch is still open) | | **Settled** | Refund (full or partial) | | **Voided** | No further action. Transaction is cancelled. | | **Refunded** | No further action (unless partial refund, then additional refunds are possible up to the original amount). | *** ## ACH Transactions ACH (Automated Clearing House) is a bank-to-bank transfer network used for direct debits and credits from checking and savings accounts. ACH transactions operate on a fundamentally different rail than credit card transactions — they are slower, have a different fee structure, and follow a distinct lifecycle. ### How ACH Differs from Cards Card transactions are authorized in real time — you get an approval or decline within seconds. ACH does not work this way. ACH transactions are submitted in batches to the Federal Reserve or a clearing house, and settlement takes 1–3 business days. There is no real-time authorization against the bank account balance. This means an ACH transaction can be submitted successfully but fail later due to insufficient funds, a closed account, or other bank-side issues. Because of this delayed feedback loop, ACH transactions carry a higher risk of returns (the ACH equivalent of a chargeback). NACHA rules govern the return window: most returns must be initiated within 2 business days, though unauthorized transaction claims can be filed up to 60 calendar days after settlement. ### ACH Transaction Lifecycle | Step | Stage | Description | | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **1** | **Collect** | Collect the customer's bank account and routing number. Optionally verify the account using micro-deposits or instant verification. | | **2** | **Submit** | Create an ACH debit (or credit) transaction via the ECRYPT API. The transaction enters a pending state. | | **3** | **Batch** | ECRYPT batches pending ACH entries and submits them to the ACH network. This typically happens on a daily cycle. | | **4** | **Settle** | The receiving bank processes the entry. Funds are debited from (or credited to) the customer's account. Settlement takes 1–3 business days. | | **5** | **Return** | If the bank rejects the entry (NSF, closed account, invalid details), a return is generated. Returns can arrive up to 60 days later for unauthorized claims. | ### ACH Transaction Types | Type | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **ACH Sale** | Debit funds from the customer's bank account. The most common ACH transaction. Used for bill payments, subscription charges, and invoice collection. | | **ACH Refund** | Credit funds back to the customer's bank account for a previously settled ACH sale. Can only be performed after the original transaction has settled. | | **ACH Void** | Cancel a pending ACH transaction before it has been submitted in a batch to the ACH network. Once batched, a void is no longer possible. | > **Warning:** ACH transactions cannot be authorized in real time. Always implement webhook listeners or polling to monitor for ACH returns and update your system accordingly. ### ACH vs. Card Comparison | | Credit Card | ACH | | ------------- | ------------------------------------------------- | -------------------------------------------- | | **Speed** | Real-time auth, 1–2 day settlement | No real-time auth, 1–3 day settlement | | **Cost** | Interchange + processing fee (percentage-based) | Flat fee per transaction (typically lower) | | **Risk** | Chargebacks (120-day window) | Returns (2–60 day window) | | **Reversals** | Void (pre-settlement) or Refund (post-settlement) | Void (pre-batch) or Refund (post-settlement) | | **Best for** | Consumer purchases, e-commerce, POS | B2B payments, rent, subscriptions, invoices | *** ## Key Concepts ### Idempotency Payment APIs should be called idempotently whenever possible. If a network timeout occurs during a sale request and you retry, you risk charging the customer twice. Always include a unique idempotency key with your requests so ECRYPT can detect and deduplicate retries. ### Webhooks While synchronous API responses give you immediate feedback for card transactions, certain events (ACH returns, settlement confirmations, chargeback notifications) happen asynchronously. Configure webhook endpoints in your ECRYPT dashboard to receive real-time notifications when these events occur, rather than polling the API. ### PCI Compliance ECRYPT is a PCI Level 1 certified service provider. By using ECRYPT's hosted iframe or Cloud EMV terminals for card data collection, your application stays out of PCI scope. If you collect card data directly via the API, you take on additional PCI compliance obligations. For most integrations, the hosted iframe is the recommended approach. *** ## Next Steps Now that you understand how payments flow through the ECRYPT platform, explore these related guides to start building: | Guide | Description | | ------------------ | ---------------------------------------------------------------------------------------------------- | | **Hosted Iframe** | Embed a PCI-compliant payment form on your website and tokenize card data without handling raw PANs. | | **Customer Vault** | Store tokenized payment methods, manage customer profiles, and charge cards on file. | | **Cloud EMV** | Set up and manage card-present terminals for in-person payments. | | **API Reference** | Full endpoint documentation with request/response schemas for every transaction type. | # Hosted Iframe Source: https://docs.ecrypt.com/guides/iframe ECRYPT's hosted iframe allows you to embed a PCI compliant payment form on your webpages and securely collect payment details. Once details are collected, sensitive credit card information is tokenized in your ECRYPT account. You can customize the appearance of your payment form to match your brand and there are a variety of themes for quick implementation. ## To get started, place the code snippet below on your site. ```javascript theme={null} ``` ## Pick a prebuilt theme for quick implementation. Here is a list of themes you could use. Juan to provide iframe demo embed. **Code sample:** ```text theme={null} {/* Add this element anywhere you want in the Body */}
{/* Place this right before the closing body tag */} ``` ## **Appearance** This section covers the appearance config for both short-form and long-form themes. ## **Customizable form components include:** * Color * Font Family * Form messages ## **The**`short-form`**theme appearance config options:** * `short-form-light-zip` * `short-form-Dark-zip` ```text theme={null} {/* Add this element anywhere you want in the Body */}
{/* Place this right before the closing body tag */} ``` ### **The**`long-form`**theme appearance config options:** * `long-form-light` * `long-form-dark` * `long-form-border-light` * `long-form-border-dark` ```text theme={null} {/* Add this element anywhere you want in the Body */}
{/* Place this right before the closing body tag */} ``` ## **Color** Ecrypt iframe will accept hex and letter color formats only. Shortformiframeimage Long form iframe example ## **Google Font** * Go to [**Googe font site**](https://fonts.google.com/) * Select a font you like, once you add the font to your selected family. * Apply the CSS rules to specify families. You should see a CSS code snippet `font-family: 'Roboto', sans-serif;` * Only copy the value of the CSS rule font-family 'Roboto', sans-serif * Then paste it in the config for example ```text theme={null}
``` # Manage Customers Source: https://docs.ecrypt.com/guides/manage-customers Create, retrieve, list, and delete customer records and wallet payment methods. ## Customer Actions ### Create a Customer Creates a new customer profile. Once the customer is created and a `customer_id` is returned, payment methods can be added to the customer's wallet. ```bash theme={null} POST /v1/customers ``` ```json theme={null} { "first_name": "Jane", "last_name": "Smith", "email_address": "jane@example.com", "phone_number": "8005550100", "shipping_address": { "line1": "123 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" }, "metadata": { "account_id": "ACC-001234", "loyalty_tier": "gold", "store_location": "Austin-TX-01" } } ``` ```json theme={null} { "customer": { "id": "00000000-0000-0000-0000-000000000000", "first_name": "Jane", "last_name": "Smith", "email_address": "jane@example.com", "metadata": { "account_id": "ACC-001234", "loyalty_tier": "gold", "store_location": "Austin-TX-01" } }, "request_id": "000000000000000000000" } ``` Store the returned `id` -- it is required for all subsequent customer and wallet operations. Use `metadata` to attach any key-value data from your internal systems to a customer record. Common uses include internal account IDs, CRM references, loyalty tiers, and location codes. Metadata is returned on all API responses that include the customer object. *** ### Get a Customer Retrieves a single customer record by ID. ```bash theme={null} GET /v1/customers/{Customer} ``` *** ### List Customers Returns all active customers on your account in descending order by creation date. Results are paginated with a default page size of 100. ```bash theme={null} GET /v1/customers ``` | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------ | | `Page` | integer | Page number to retrieve. Default: `1` | | `Size` | integer | Number of results per page. Default: `100`, max: `100` | *** ### Delete a Customer Permanently deletes a customer record and all associated wallet payment methods. ```bash theme={null} DELETE /v1/customers/{Customer} ``` Deleting a customer invalidates all stored wallet tokens. Cancel any active subscriptions or installment plans linked to the customer before deletion. *** ## Wallet Actions A customer wallet stores up to 4 payment methods. Payment methods are added to the wallet after the customer record is created using the customer's `id`. ### Add a Payment Method Adds a credit card or ACH payment method to the customer's wallet. A payment method can be added using either a token from the `/v1/tokens` endpoint or the `transactionId` from a previously approved transaction. ```bash theme={null} POST /v1/customers/{Customer}/wallet ``` ```json theme={null} { "token": "00000000-0000-0000-0000-000000000000", "default": true, "billing_address": { "line1": "123 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" } } ``` ```json theme={null} { "wallet": { "id": "00000000-0000-0000-0000-000000000000", "network": "visa", "account_number": "4***********1111", "default": true }, "request_id": "000000000000000000000" } ``` *** ### List Wallet Payment Methods Returns all payment methods stored in the customer's wallet. ```bash theme={null} GET /v1/customers/{Customer}/wallet ``` | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------ | | `Page` | integer | Page number to retrieve. Default: `1` | | `Size` | integer | Number of results per page. Default: `100`, max: `100` | *** ### Get a Wallet Payment Method Retrieves a single wallet payment method by ID. ```bash theme={null} GET /v1/customers/{Customer}/wallet/{Wallet} ``` *** ### Set Default Payment Method Sets a wallet payment method as the default. The default payment method is used when charging a customer without specifying a wallet ID. ```bash theme={null} PUT /v1/customers/{Customer}/wallet/{Wallet} ``` ```json theme={null} { "default": true } ``` *** ### Delete a Wallet Payment Method Removes a payment method from the wallet and invalidates its token. ```bash theme={null} DELETE /v1/customers/{Customer}/wallet/{Wallet} ``` *** ## Next Steps With your customer profiles and wallet payment methods in place, you're ready to start charging customers on file. Learn how to charge a customer's default or saved payment method, including one-time payments, subscriptions, and installment billing. Learn how to create ongoing subscriptions or break up large payments into installment plans with customer wallets.  # Migrate to ECRYPT Source: https://docs.ecrypt.com/guides/migrate-tokens Move your stored payment tokens from another processor to ECRYPT. Migrating to ECRYPT does not require your customers to re-enter their payment information. ECRYPT can receive a secure token export from your current payment service provider (PSP) and import those records directly into your vault. ## How it works Token migrations follow a consistent pattern regardless of your current PSP: 1. You contact your current PSP and request a token export. 2. Your PSP encrypts the export file using ECRYPT's public PGP key. 3. The encrypted file is sent to your primary ECRYPT contact via our PCI Level 1 approved encrypted email service. 4. ECRYPT imports the records into your vault. All imports must be approved by the primary contact at ECRYPT before any data is submitted. Reach out to your ECRYPT account representative to initiate the process. ECRYPT does not audit or filter imported data. It is the responsibility of the merchant and the data holder to provide a complete file containing only the records intended for import. *** ## Before you begin * Confirm you have an active ECRYPT account and have been in contact with your ECRYPT representative. * Identify all stored payment methods you want to migrate (cards, ACH accounts, or both). * Determine whether you want to migrate customer profile data alongside payment methods, or payment tokens only. * Download ECRYPT's public PGP key (below) and share it with your current PSP when making your request. *** ## Contact your current PSP **Request a payment data export** 1. Contact your PSP's support team or account manager. 2. Request a **stored card or token data export** for migration to a new processor. 3. Share ECRYPT's public PGP key and confirm the data will be encrypted before transmission. 4. Coordinate delivery of the encrypted file with your ECRYPT representative. Most PCI-compliant processors support token migrations, though timelines and processes vary. If your processor is unfamiliar with the process, direct them to ECRYPT's contact for coordination. *** ## ECRYPT's public PGP key All exported data must be encrypted using the PGP key below before transmission to ECRYPT. Share this key directly with your PSP when initiating your migration request. ```text theme={null} -----BEGIN PGP PUBLIC KEY BLOCK----- Version: Keybase OpenPGP v1.0.0 Comment: https://keybase.io/crypto xsFNBF/KcQ4BEADXrrhdsANxnx97m8YHJTz4UpU2wZr5KohSo7Mvcl96ypN6P1Xk xim+Go/h+5dqiM4tCscZjf7viy/FhI6x68pMPePL0B3kLrlxEV3LGUva4mDrzi4s z+jTgE010MnwYlY0SUqqMiVYne2Ae1OAztPG3YwbYa1D/4Wrs+7RH77ngBE3Q41g Eu+FAtzsIe/UqOBLMBjOSlR7r3Aq4oiIUAcvOv0bHVqsQDRIugl1Y0eHUmuqVAD6 ZKL/dRsBGVjr6SXFCPedaaMzeFSMq75nSA3yCg1DJ7J1xp3f0YhIsWTM4KxL3ezj zzAsUZwk/7XYj91Aio9OXR/JmL4/ioWLY6ZEuTK5KbuoMnuqSYLVbKfvJPipb/6X UmlEQ486QeQw3nPZ5m7V3X/dp2tTbC6Qne6vCiHS35vf22/ttuO0kxYcF1zJXvez AQshLcECCaGgLSM/LubeccHxnaLIdxNfhfMC/xfjiOPokIxCxI0G54SeHewcG4lr lnO78eVCwgsshkIfdfoT50xQt5B/NyKXVyxVVuzBgxHo0TTRUtDUXIawzo0U/Wu6 hJsKgRaB6QBBrhGQy3RzpXX+gbanve8XEA63fZQTj0dRXrJx989Hd90kwqEaEVkv Z6anzsjbgFrc9gQN9iDD/1C9o6GDjumU2zZIw04DKdigQoflYF3QzkDi7wARAQAB zSlBbGV4IFBhcmVkZXMgPGFsZXhAcHJlZmVycmVkcGF5bWVudHMuY29tPsLBbQQT AQoAFwUCX8pxDgIbLwMLCQcDFQoIAh4BAheAAAoJEOrL2hQV34jAw1gP/RFtI8hJ lc1lF/LyxkKYSD8mv2l/MqZ+mbEiZ/k5xahL6LtApPKZ98qahsgAu3kRxfMveBa6 hHWCd+Bz8rAVckRXAQF719vSNy+1PhY3Bh6sqENAEvWoBtPn4HOXmqGikWSnz9mY abbbfAGXMfzl8t2Rtz2VxTMTjNy2DtuB0TaiT/vp+s+m4rCCaeCQRV2Nnzd5dZMi bFtJl53wRHQMO8rtY/dQh6Q+vF2H1GHm2jkwkTT+3G2PEnMiPDcC7Fk72RdExEFk yJg5IXxpmM+ZdGyXpu5ZIZlQ9M81s+zB3gD4I3H3UzMW5k2RGCdb1XexPzvJYMT+ CvHT9N0PK9hGGn1Ql6Ewd5qcYwqchu7zH5EEHDelo8O81hvaWERyrG1jBSTTJYRR 7bt7rDajTZ6AIQA6qJHFaDfPkecxuw4eK4QLsQpVYe/DsgxgzXAMBBlGTulZlDaX BwrnNTRdj/83186bYHGahy9nISmRlBL60xxUfj12O4gqx0N2840qIsEl5/9lDvI5 QaABIT80MSjRMsgL7wdV6Zv5zng5Crbb+h86yICp1NQm6NpYUJQRPI+glvpBKaWA apSG/3NKQ/XRIXPZlaouxbFMkFBDy1sKfKDesk1A00O4ypseAf+WAnggY4sTewBn 4hC2z/HfzXAoOrl8kFzTyIlwZvA/v3B2zKm5zsFNBF/KcQ4BEADHMTV66tahVwjh kxhbskyJ/x/HMRib75UlmojPmUUYEn00QrZ/RI4ZWtGUYcQz/2jV1EOw4VEOdrXs UYRqQMJJD+7Ar6CT45cRbx9L8rLMpgV5BdxHtnijr6WDXYw4syH91jZqDPdsbaRZ NxGwyCSbTKptliDdgxKUzJWZrdm6wmje+U+KIUOcp3mmJXXEAGWBlxq4mjlALt8v glsCwgAsTdvpOL8pHOKA9hhq5sOIh10SvSZBDvVKQtFbSvI99QIz+VBXvjokfCJX H4epMo65KH6pQbA+qiQqJ9GVor9we0QP9cy6QZ9N53jwI8t0+m0aCbC603hswo+U FCF8A/xIdaD1MLfbdkEnLw+RsMMEP3nmeRGtH/tWeRogBcKUyqpwfq54enURfBTa 2FA6c0ha5o7703Ao6ixV8IDnxYIOtszT+S0j7WLujnsI1wB/PyLkUmH7Fy4p6bDA d0l04zeg9sIkByYEQJzw16qZwzzySK0pOj7M8p/fHN7hQhd+MRIOFqhXuXaYZ91Y Efhqiv1pj5FCoaqG2S+XnRc8EIxHMIhkwqZLsxdhdQh4DvyIkI6YLNIg7KUJ060v lEBbz698MMkc3hyw+ggZOHk72bbfdCSqqyJoh+RZ0E4GzQgyP+AgW0Yowm3OcplT 4N7o6U7j5F1gd5QZECdKh/R0oY2O5QARAQABwsOEBBgBCgAPBQJfynEOBQkPCZwA AhsuAikJEOrL2hQV34jAwV0gBBkBCgAGBQJfynEOAAoJEPtzS9G6k2NkSssQAKoT /2MQgwccSg7e0PcUNn+qBzwEKWxYCilhBrpSK8htwxeYbXwYJP1lu3pZeFaja46F /vFhyEYxBSscsP/AgomaNWQihvA9c96YoDKy9GMai/2FftnJesPojoQIjx6Ir0/h +N/2iofj3JByBZM4L+eFqGzQ1Uk3CdwqoqFLII0QUjq1yf/Ni5nh6AroWyJonxRs MzvYn0Ti0gXKyC5cEIZeYu3o4/BInaETJTXuSBc+ml+LnSEC5UNiX9u5GoCc01oy 1mJwlqa4tvO4fleTN8SA2dX0wL3NLdTHHcYT69i8u81J13TaCuDRq1bPaGIOaX+E BqL8FVY6rPH5OWIzBIgqgaoEDm5daCMuAkvWtXPO7noFuRAgzt32slZvbwPJXVPL Sg01Z1qq+BrusEw8po6HmSjlDCPQXQQBh0Ej1NaLrYeYiD0aWTcreHa8+w/ZZtEz m//om0UV8NVrmw4Yn08LFZjIvxVS18f2Ft/rMsC7VvdR9jKXlYnnLkyjcEGAolrO S1MHsKuRgvcIYmmNZ54/monvr9YNDTaoaO2Cs3XHeb0mMfr2En5zQDJqYjJNk9pF SddrhE7/A2HOoLue5s2ROxEK3xqBfS2TW6lh9r+jpfNwB1wR23XVZE5BvqBoiQ9a 8Tmho6cf2xy8SFAH4yAOQdbWF/GI3AZWN2BqBnSAvlEQAMc+mbqkUq9n8TzO8C9o /ovwF/uh9gILtcfTqZFziRhfTiVRZQ4pCkUrF0Ud1Pmu42mhi7/yZlLGLPOWej62 471R9MNR4BfO3E90TpKtG5fSqaRyBhi+/T20iqBWXoFiS2aKN9QLjv5a8VNseQUi zs1q2bAopCyqq1mxWZ+BuT9BQKh4/f1kX3faT8z92Q2gxiR+Zl07IwYouWevCjt2 oozL46gmiONCcPSYJV8NFHxYK+tXeS0h5EtAIU6+3Qc99DZJuzFfV0zekWiRh0+q byogFp3uyHWkQF03twzlXT9i5BFKEWiSgBaMRHS11OLki3GrUeDRs1+DnVoZVSJa BeX0kyGb70GvlZZQTeuxBGzgXtBkWh8VImc/sS28cy7K1hE0m1yP8CpcK4ipEPzR QWKVb8n/uZp7F3mSdfUT0uPzmnkGpVNM6WJf+BRZ6doU2e/PdS4if4yXwf6jJkly oByQkjEWsnJhONyeR4XBDwp19ZTBUHxiTwclVyQXOAo0v2v/F4wEXhD+vAH34Lad Gw9M/Iby1JrNG6qgpTrxQ34sVpvdfAWI+5xClZOObGjsCAZRm2icVgw1xFOZdBXt 2T7nxBBM33NwDkJHTi1J/T0OMFRBQmheanEHF+1CaQphFLs1GmGys8Njkft3pmUY 7Yp5x8L6qHiWMbkkyqciyZSPzsFNBF/KcQ4BEAC4bpbu7GoXX53vj4x9KmOMpWIq Fx2Ez/oiP8rdXb+xNH5V6ihpRficBf9E8jN12RJgNlOsc6OSFtBaq7fUoq7diWRD p/wmTNJu7LTZoCYrQfE7s/XEs5b+j/wP3fI9u+DuDFyOwWb1+0BRzLOlYZcUVEI+ mn3FU6a++gZ8eLPB0il9B5vKJaBWEauUH8DWSfm13+Vj3BiJ1pKGBmfS2UpxFRRd oLC3rkLaMsdzMZvPAKDyjj1MVMpjGX1TPrYNB9vMzqoEHvYLptoKm+WBq9PBvHGJ p4VSK0jJpGdQrDjqOTrczsebfUrQFdOPdvu/oaT3fOY20izIqszvRToTGdi6mxQ1 cZqYdx0xXGbr1KR4BVy2PrUaCxl4OCjV+hf8eElKpJcDOR0N8HTXxsITe+BFycxm /lNNGbuvHBiYZDtk2/Al6FmI3W5fgaNNE7R5BtQyy1a9tuXUlpMyZVez6TPYOEw0 7M9PT66fFSEzdPk1FdERmjOLqYsaMhvP/NyquOXo9SSuvGd+K4aiY/HYaRh7CPSn VTo/DANn/uvO6ey1Zxe8ckCfcJGwZLH7u78628OD025BIaU6sz9m+ZVLaYdofGa/ Zs+LcGW1PCTTE+YfTvrH4vsTEytEdZk5fLo4JchfGqNXuBgIi0pOwxqiONpFS3JV N5OTcyH4i4eRER5exQARAQABwsOEBBgBCgAPBQJfynEOBQkPCZwAAhsuAikJEOrL 2hQV34jAwV0gBBkBCgAGBQJfynEOAAoJEHRNsJf4jAq1b3MP/iLBz1NURAhlEEnP vbkNEhoRd0XPpR2IgS9X1Qys11m28n9onOYmmYt7Ue6k08eE7D4RbmjCw8DV8c9L Ad3edYl/xKR4Xx2uQ45Ilx2YS+HqNgsB+1H+2PofQH7PjZa3XFSHP0R8OO2fAxbH eKQbAVV+zClHZeOy1N0sZbr/AdS6U2zvSicu/vrZUWdtNze4kPhqn7TJYJLg9gC+ 74q9/EAaMiItffjrhfW5KFYbHgulFD7iS/PKkPPLELlSE2Gu0yvGytEVe2+PpmM0 76KalA5vh/LP+BrjOz9uwRFsytXCirSVSwuqenyh5HEZyaU39ENK2YcDpKivwG1D 9ZxMouHvILldLNOFcjW38bunWpH/ZiykU5240YM2X5EDxl3ToVL5B5KClNCPRFiW RFcsGQ3zmNfSSLGLy4Rb4BcnrOUZdCcq66Ltt0c9l86fbk3+jWyC7/l1QXatjdCt bA+zgIQcbEpdJXfOpxfQ7hfYDw1keG0mLkeWMG/azBMIB4tHWUy35BNh7VDONSXJ 7zf0HxTk7HkOBEpcc1Dzl5FdHqunZgannUZ8LWTK5N9PtxP4tJyyjJS4pnHqqZ8B k5rEKsMVn4aqyxKYqPAK4NRN4Ay5D/R2VDWCevRMEEDSjGf9X7Zz9LYHNcgWPtyq XN4hichhwxc7naTf2OLKxAnIp8g+FScQAK/2hsI1XQfx/B/F44R26/BtPDegndX9 Lli6MJFXj+3Qm2zUUKXyGJK2rJWBXTMsfhgQr0xLguEzla0l6T/a/ER5ltUFk9wC E9/ncyOwd7clMflYmGzNwtNsXqSHvtJ6dXnp97nsp4XZERJIMi0z///p5sMK6MCp vK4/zbN5yj5zxkshBDG3swfGDQhNC2tp8JBQgFgIoyTsihAtc6f6VgNIsyg9V90w YACwIcjJdPkagG9sV9xsGlI97pgtb37Mydehr4txz7d2KCa9NeQD0qS/BILV7aUV cVbi49K8gdn5Qhiz1/TWhNiZF8cD4570l6qZZ4Fur7Q4TwOWYNifdy02hOs+XqaW KBmjrpw5qdsilkRq1ByECGB2MoA6SwMWSGy0ed6umHR+HDRk2UtXc8ZtZ8+E0SV5 S/J0+sCbSffKjU1MF5OzLZzQ+FvQzjI0+oL2XLZPWvEC0u4J5cjEhTyU5sDn9Ws8 XO7aUFHiLKHxyRRJgeiYPp2WMRmwfCDSpu+WqUjiRW9/+BsR4yPUCZM9phAMxPs/ 1ouoYzk1tIcjSXR5w6mquX+aVkeQJDkPCvtmzfSNVa5NzsKXRALqQKqyDvTErdNy 0ZJg6e1tM7N4gbwAB33D3Y+HSTRXAois6qfteV1S/HhpSrebC8GBtZU2QUt741YG A6VE4vi2x51m =WQPD -----END PGP PUBLIC KEY BLOCK----- ``` # Order Devices Source: https://docs.ecrypt.com/guides/order-devices ECRYPT currently supports the following Ingenico terminals. All devices support Tap-to-Pay (NFC), EMV chip, and magnetic stripe, and all support tipping at the time of sale. ### Ingenico Link2500 A compact, portable terminal well-suited for field services, table-side payments, line-busting, or any environment where mobility matters. | Spec | Detail | | -------------------- | ------------ | | Connectivity | Wi-Fi | | Form Factor | Portable | | Display | 2.4" Color | | Tap-to-Pay | Yes | | Tip at Time of Sale | Yes | | Electronic Signature | No | | **Cost** | **\$384.99** | Ingenico Link 2500 ### Lane 3000 A countertop terminal designed for fixed checkout lanes. Connects via Ethernet for a reliable wired connection. | Spec | Detail | | -------------------- | ------------ | | Connectivity | Ethernet | | Form Factor | Countertop | | Display | 2.8" Color | | Tap-to-Pay | Yes | | Tip at Time of Sale | Yes | | Electronic Signature | No | | Price | **\$424.99** | Ingenico Lane 3000 ### Lane 5000 A countertop terminal with a larger display and electronic signature capture, suitable for retail environments where signature collection is required. | Spec | Detail | | -------------------- | ------------ | | Connectivity | Ethernet | | Form Factor | Countertop | | Display | 3.5" Color | | Tap-to-Pay | Yes | | Tip at Time of Sale | Yes | | Electronic Signature | Yes | | Price | **\$469.99** | Ingenico Lane 5000 ### Lane 7000 The flagship countertop terminal, featuring a large 5" display and electronic signature capture. Ideal for high-volume retail, grocery, or multi-lane environments. | Spec | Detail | | -------------------- | ------------ | | Connectivity | Ethernet | | Form Factor | Countertop | | Display | 5" Color | | Tap-to-Pay | Yes | | Tip at Time of Sale | Yes | | Electronic Signature | Yes | | **Price** | **\$764.99** | Ingenico Lane 7000 1 *** ## Ordering Terminals Terminals can be ordered directly through ECRYPT. Contact your account manager or reach out to our [support team](https://info.ecrypt.com/contact-support/) to place an order. Devices ship pre-configured and are ready to activate against your ECRYPT account once received. > **Note:** Terminals are pre-certified by ECRYPT and should only be sourced through ECRYPT to ensure they are properly provisioned for cloud integration. Third-party devices are not supported. # PCI-DSS Compliance Source: https://docs.ecrypt.com/guides/pci-dss-compliance ECRYPT is a Level 1 PCI-DSS Assessed Payment Processing Gateway. As a service provider, ECRYPT is committed to the secure transmission and storage of cardholder data. This document describes the PCI-DSS requirements ECRYPT meets for merchants using the ECRYPT Gateway. PCI-DSS applies to any organization that stores or transmits card data. The ECRYPT Gateway helps meet this requirement and reduces the compliance burden for merchants, specifically as it relates to card storage through tokenization. ECRYPT merchants are still responsible for their own PCI-DSS compliance. This document only defines the specific items ECRYPT assists merchants with. Any requirement not listed here is the merchant's responsibility. *** ## Requirement 3.2.1 — Data Retention **Limiting data storage amount and retention time to that which is required for legal, regulatory, and/or business requirements.** * **ECRYPT:** Stores merchant cards for 2 years from last token use. * **Merchant:** No action required. *** ## Requirement 3.3.1 — Track Data Retention **The full contents of the track are not retained after authorization.** * **ECRYPT:** Does not retain full track data after authorization. * **Merchant:** No action required. *** ## Requirement 3.3.1.2 — CVV Retention **The card verification code (CVV) is not retained after authorization.** * **ECRYPT:** Does not store the CVV after authorization. * **Merchant:** No action required. *** ## Requirement 3.3.1.3 — PIN Retention **The PIN or PIN block are not retained after authorization.** * **ECRYPT:** Does not store the PIN or PIN block after authorization. * **Merchant:** No action required. *** ## Requirement 3.3.2 — SAD Encryption Prior to Authorization **Sensitive authentication data (SAD) stored electronically prior to completion of authorization is encrypted using strong cryptography.** * **ECRYPT:** Provides HTTPS TLS 1.2 endpoints for secure transmission. * **Merchant:** Must connect to ECRYPT TLS 1.2 endpoints. *** ## Requirement 3.4.1 — PAN Masking **PAN is masked when displayed.** * **ECRYPT:** Masks PAN in the ECRYPT Dashboard. * **Merchant:** No action required. *** ## Requirement 3.5.1 — PAN Storage **PAN is rendered unreadable anywhere it is stored, using one-way hashes, truncation, index tokens, or strong cryptography with associated key-management processes.** * **ECRYPT:** Uses one-way hashes based on strong cryptography to store cards and maintains compliant key management processes and procedures. * **Merchant:** If card data is stored with the ECRYPT Gateway and billed via tokens, this requirement is met. If card data is stored separately from ECRYPT, the merchant must meet this requirement independently. *** ## Requirement 3.6.1.2 — Key Storage **Secret and private keys used to encrypt/decrypt stored account data are stored in encrypted form, within a secure cryptographic device such as an HSM, or as at least two full-length key components.** * **ECRYPT:** Uses an HSM to protect keys of encrypted cards. * **Merchant:** No action required. *** ## Requirement 3.7.3 — Key Storage Policies **Key-management policies and procedures include secure storage of cryptographic keys used to protect stored account data.** * **ECRYPT:** Has policies and procedures for the secure storage of cryptographic keys. This responsibility is met through an upstream service provider. * **Merchant:** No action required. *** ## Requirement 3.7.7 — Key Substitution Prevention **Key-management policies and procedures include prevention of unauthorized substitution of cryptographic keys.** * **ECRYPT:** Has policies and procedures to prevent the unauthorized substitution of cryptographic keys. This responsibility is met through an upstream service provider. * **Merchant:** No action required. *** ## Requirement 3.7.8 — Key Custodian Acknowledgment **Cryptographic key custodians formally acknowledge in writing or electronically that they understand and accept their key-custodian responsibilities.** * **ECRYPT:** Has designated key custodians for all cryptographic keys. * **Merchant:** No action required. *** ## Requirement 4.2.1 — PAN Transmission Security **Strong cryptography and security protocols are implemented to safeguard PAN during transmission over open, public networks, using only trusted keys, valid certificates, and secure protocol versions.** * **ECRYPT:** Uses TLS 1.2 with valid SSL certificates to safeguard PAN over open public networks. * **Merchant:** No action required. *** ## Requirement 4.2.2 — PAN in Messaging Technologies **PAN is secured with strong cryptography whenever sent via end-user messaging technologies.** * **ECRYPT:** Transmits and receives PAN using secure messaging technologies with TLS 1.2 in transit and encryption at rest, with an attestation of compliance. * **Merchant:** Must send and receive card data only from systems inside their cardholder data environment (CDE) using secure technologies, and destroy SAD after transmission. # Security Guidelines Source: https://docs.ecrypt.com/guides/security-best-practices Payment integrations are a common target for fraud. This guide covers the tools ECRYPT provides to help protect your integration, and the steps you should take on your end to reduce exposure. ## Address Verification (AVS) AVS checks the billing address submitted with a transaction against the address on file with the card issuer. ECRYPT returns an AVS code on every card transaction so you can evaluate the result and decide how to proceed. ```json theme={null} "avs": { "code": "Y", "text": "Address and ZIP code match" } ``` AVS is a signal, not a guarantee. A passing AVS result does not confirm the cardholder is present or that the transaction is legitimate. Treat it as one factor in a broader risk assessment. A few things to keep in mind: * ECRYPT requires ZIP code by default for card-not-present transactions. You can optionally require full billing address instead. Contact your account manager to change this setting. * Some issuing banks may decline transactions when no AVS data is provided. Collecting at minimum a ZIP code at checkout reduces this risk. * International cards often return a no-match or unavailable result even on legitimate transactions, since many issuers outside the US do not participate in AVS. * You can configure ECRYPT to automatically decline transactions that fail AVS checks. Contact your account manager to discuss thresholds. See [Response Codes](/payment-operations/card-transactions/response-codes) for the full list of AVS codes and their meanings. ## CVV Verification CVV (also referred to as CVC or CVV2) is the 3 or 4 digit security code printed on a card. It is not stored on the magnetic stripe or chip, so its presence confirms the person submitting the transaction has the physical card or at minimum has seen it. ECRYPT returns a CVV response code on every card transaction: ```json theme={null} "cvv": { "code": "M", "text": "CVV matches" } ``` Always collect CVV for card-not-present transactions. A no-match result is a strong fraud signal and in most cases the transaction should not be fulfilled. CVV may not be required for transactions using a stored token, as the card was already verified at the time it was tokenized. ## Card Testing / Auth Scrub Attacks Card testing is a fraud technique where an attacker uses your checkout to verify whether stolen card numbers are valid. They typically run a large volume of small transactions or authorizations in quick succession. A spike in declines, particularly on low-dollar amounts, is a common indicator. ### Use CAPTCHA on public-facing checkout pages The most effective defense against automated card testing is CAPTCHA on any page that submits a payment. CAPTCHA distinguishes human users from automated scripts and makes bulk testing difficult. Recommendations: * **Google reCAPTCHA v3** runs invisibly and scores each request without requiring user interaction. * **Cloudflare Turnstile** is a privacy-friendly alternative that also operates without user-visible challenges in most cases. Implement CAPTCHA at the form submission step, before the tokenization request is made. ### Additional measures * **Rate limit by IP address** on your server before requests reach ECRYPT. Block or throttle IPs that exceed a reasonable threshold. * **Require CVV and billing address** on all card-not-present transactions. Attackers often omit these fields. * **Monitor decline rates.** An unusual increase in declines, especially for small amounts, warrants investigation. * **Review your rate limit configuration.** ECRYPT's default rate limit provides a baseline layer of protection. See [Rate Limits](#rate-limits) for details. ## Duplicate Transaction Protection ECRYPT automatically blocks duplicate transactions submitted within a **5-minute window**. A duplicate is defined as a transaction with the same card, amount, and merchant account within that period. This protects against: * Accidental double-charges from users clicking a submit button more than once * Retry loops in integrations that do not check for a prior response before resubmitting * Automated duplicate submissions from bots or malicious actors If a duplicate is detected, ECRYPT returns a `409 Conflict` response. Your integration should handle this response by checking the status of the original transaction before retrying. If you have a legitimate use case that requires charging the same card the same amount in rapid succession, contact your account manager to discuss options. ## Rate Limits ECRYPT enforces a default rate limit of **10 requests per 60 seconds** per merchant account. Requests that exceed this threshold return a `429 Too Many Requests` response. If your integration requires a higher limit, contact your account manager. ## Sensitive Data Handling Never log, store, or transmit raw card data through your own systems. ECRYPT's [tokenization](/guides/tokens) flow is designed so that raw card data never touches your servers. If you are using the hosted iframe or checkout page, this is handled for you automatically. If you collect card data directly, use the `/v1/tokens` endpoint immediately to exchange raw card data for a token before any further processing. See [PCI-DSS Compliance](/developer-resources/pci-dss-compliance) for compliance responsibilities if you plan on handling raw PAN data on your own servers. # Subscriptions Source: https://docs.ecrypt.com/guides/subscriptions Subscriptions allow you to automate recurring billing for a customer on a defined schedule. This guide covers the prerequisites, API flow, and how to create and manage subscription plans. ## Prerequisites Before creating a subscription, two things must be in place: * **Stored Customer**: The customer must exist in the Ecrypt system with a populated customer wallet containing at least one stored payment token (wallet payment method). * **Reusable Payment Token**: When capturing the initial payment method (via iFrame or checkout page), `oneTimePayment` must be set to `false`. This ensures the generated token can be stored to the customer wallet and used for future recurring charges. Setting this to `true` will prevent the token from being reused. ## API Flows ### iFrame and Direct API For a first-time customer using the iFrame or direct API integration, the typical sequence is: 1. **Create Token** -- Tokenize the customer's payment method via the iFrame or checkout page with `oneTimePayment: false`. 2. **Create Customer** -- `POST /v1/customers` 3. **Create Customer Wallet** -- `POST /v1/customers/{Customer}/wallet` -- Store the token to the customer's wallet. 4. **Create Subscription Plan** -- `POST /v1/subscriptions` -- Define the billing plan (cycle, amount, label). 5. **Create Customer Subscription** -- `POST /v1/customers/{Customer}/subscriptions` -- Link the customer and their wallet to the subscription plan. ### Dynamic Checkout Page The [Dynamic Checkout](/guides/checkout-page) page simplifies this considerably. By including a `subscription` object in the `POST /v1/dynamiccheckout` request body, the checkout page handles the entire flow in a single session: > **Tokenization > create customer > store payment method > subscription enrollment.** You simply select a pre-defined billing cycle and a billing date (start date) within the pages subscription object, and the checkout page takes care of the rest. ## Create a Subscription Plan **`POST /v1/subscriptions`** This endpoint defines a reusable subscription plan that can then be assigned to one or more customers. ### Required Fields `label` *(string, required)* -- A human-readable name for the subscription plan. Must be between 1 and 100 characters. `cycle` *(object, required)* -- Defines the billing frequency and timing. | Field | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unit` | string | The base time unit: `day`, `week`, `month`, or `year` | | `interval` | int32 | How often the cycle repeats within that unit. For `day`: 1-365 (1 = daily, 2 = every other day). For `week`: 1-52 (1 = every week, 2 = every other week -- defaults to Monday if no `dayOfCycle` is set). For `month`: 1-12 (1 = every month, 2 = every other month -- defaults to the subscription activation date if no `dayOfCycle` is set). For `year`: 1-500. | | `day_of_cycle` | int32 | The specific day within the cycle to charge. For `week` unit: 1-7 (1 = Monday, 7 = Sunday). For `month` unit: 1-31 (31 defaults to the last day of the month for shorter months). For `year` unit: 1-365. Not applicable for `day` unit. | `amount` *(object, required)* -- The billing amount for each cycle occurrence. | Field | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `currency` | integer | ISO 4217 numeric currency code. Example: `840` = USD. | | `value` | decimal | The full charge amount per cycle, inclusive of all taxes, fees, and discounts. Range: `0.01` to `999999999.99`. Example: `49.99` | ### Example Request ```json theme={null} { "label": "Monthly Premium Plan", "cycle": { "unit": "month", "interval": 1, "day_of_cycle": 1 }, "amount": { "currency": "USD", "value": 49.99 } } ``` *** ## Enrolling a Customer in a Subscription **`POST /v1/customers/{Customer}/subscriptions`** Once a subscription plan exists and the customer has a populated wallet, use this endpoint to activate the subscription for a specific customer. | Field | Type | Description | | -------------------- | ----------------- | ----------------------------------------------------------- | | `subscription_id` | string | The ID of the subscription plan to assign. | | `start` | date-time | The billing start date -- when the first charge will occur. | | `skip_first_payment` | boolean | If `true`, the first scheduled billing cycle is skipped. | | `wallet` | string (required) | The wallet ID of the stored payment method to charge. | | `initiated_by` | string | Indicates who initiated the transaction. | *** ## Checkout Page Subscription Object When using the Dynamic Checkout page (`POST /v1/dynamiccheckout`), include the `subscription` object to handle the full enrollment flow automatically. This is the simpler path for new customers. | Field | Type | Description | | --------------- | --------- | ------------------------------------------------------------------ | | `billing_cycle` | integer | Pre-defined billing cycle. See values below. | | `billing_date` | date-time | The start date for the subscription and first charge is scheduled. | | `label` | string | A label for the subscription. | **Billing Cycle Values** | Value | Cycle | | ----- | --------------------------- | | `10` | Daily | | `20` | Weekly | | `30` | BiWeekly | | `50` | SemiMonthly (1st and 15th) | | `52` | SemiMonthly (15th and Last) | | `70` | Monthly | | `71` | Monthly (1st) | | `73` | Quarterly | | `79` | Monthly (Last) | | `90` | SemiAnnually | | `95` | Annually | *** ## Subscription Management Once active, a customer subscription can be managed via the following endpoints. See the Customer Subscription section in the API reference. * **Modify Price** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}` * **Suspend** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}/suspend` * **Resume** -- `PUT /v1/customers/{Customer}/subscriptions/{Subscription}/resume` * **Cancel** -- `DELETE /v1/customers/{Customer}/subscriptions/{Subscription}` * **Delete Plan** -- `DELETE /v1/subscriptions/{Subscription}` # Surcharging Source: https://docs.ecrypt.com/guides/surcharge Surcharging allows merchants to pass some or all of their credit card processing costs on to customers who choose to pay by credit card. Surcharging must be enabled during merchant onboarding with ECRYPT. If you would like to enable surcharging on your account, contact your ECRYPT representative. Surcharging is a regulated practice governed by card network rules and state law. Review the requirements below and consult legal counsel before enabling surcharges. ## Rules & Restrictions ### Credit cards only Surcharges may only be applied to **credit card** transactions. Debit cards, prepaid cards and ACH transactions cannot be surcharged under card network rules, even when a debit cardholder selects "credit" at the point of sale. The card is still processed as a debit transaction, and the surcharge restriction applies. ECRYPT performs a BIN lookup on every transaction and automatically drops the surcharge amount if a debit or prepaid card is detected. This applies across all checkout channels, including the hosted iframe, checkout page, physical terminal and direct API transactions. No additional handling is required on your end. ### Maximum surcharge rate The surcharge amount cannot exceed the lower of: * Your **merchant discount rate (MDR)** for the applicable credit card, or * **3%** of the transaction total (Visa's current cap, effective April 2023) Mastercard's cap is 4%, but because Visa's 3% limit applies across your program when Visa cards are accepted, 3% is the effective ceiling for most merchants. Surcharges are intended to offset processing costs, not to generate profit. ### State restrictions Surcharge laws vary by state and are subject to change. As of early 2026: **Surcharging is prohibited in:** Connecticut, Maine, Massachusetts, California (as of July 1, 2024), and Puerto Rico. **Surcharging is permitted with restrictions in:** Colorado (max 2%), New York (cannot exceed actual cost of acceptance, strict disclosure rules), New Jersey (cannot exceed actual cost of acceptance), Nevada (max 1.5% without additional documentation), Oklahoma (max 2% or actual cost, whichever is lower), and Minnesota (surcharge must be incorporated into the advertised price as of January 1, 2025). Texas has a statutory prohibition that has been challenged in federal courts; its enforceability remains uncertain. This is not a comprehensive legal reference. Surcharge laws change frequently. Verify current requirements in your state with legal counsel before implementing surcharges. ### Disclosure requirements Regardless of state, card network rules require merchants to: * Display a surcharge notice at the **point of entry** and **point of sale** (both in-store and online) * List the surcharge as a **separate line item** on the transaction receipt * Apply the surcharge as a percentage of the transaction total, not a flat fee ECRYPT's Hosted Checkout Page and Cloud Terminal automatically display the surcharge percentage, subtotal and total when surcharging is enabled. ## Passing a Surcharge via the API The `surcharge` field is available on the `order` object for card transactions, and on the `amount` object when modifying subscription pricing. Pass the surcharge as a decimal value representing the dollar amount to be added. ### Sale with surcharge ```json theme={null} POST /v1/transactions/sale { "payment": { "token": "{{token}}" }, "amount": { "value": 103.00 }, "order": { "subtotal": 100.00, "surcharge": 3.00, "total": 103.00 } } ``` The `amount.value` must equal the full amount charged to the customer, including the surcharge. The `order.surcharge` field is used for reporting and receipt purposes. ### Checkout page When creating a Dynamic Checkout session, pass the surcharge at the top level of the request: ```json theme={null} POST /v1/dynamiccheckout { "total": 103.00, "subtotal": 100.00, "surcharge": 3.00, "items": [...] } ``` ### Subscription pricing update When modifying a customer subscription's billing amount, the `surcharge` field is available within the `amount` object: ```json theme={null} PUT /v1/customers/{Customer}/subscriptions/{Subscription} { "amount": { "subtotal": 100.00, "surcharge": 3.00, "total": 103.00 } } ``` ## Transaction Response Surcharge amounts are returned in the `surchargeAmount` field on the `TransactionDto` object when retrieving transactions: ```json theme={null} { "transactionId": 123456789, "amount": 103.00, "surchargeAmount": 3.00, "status": "SETTLED" } ``` # Testing Source: https://docs.ecrypt.com/guides/testing Testing your implementation will ensure your integration will successfully run transactions for common payment flows and prepare you for certification before going live. Failure to run these basic test cases will result in your integration potentially not working correctly and creating issues down the road. ## Basic Test Cases * Authorization * Authorization, capture * Authorization, partial capture * Sale * Refund * Credit * Void ## Test Cards (U.S.) | Card Type | Value | | ---------------- | ---------------- | | Visa | 4111111111111111 | | MasterCard | 5431111111111111 | | Discover | 6011000991300009 | | American Express | 341111111111111 | ## Test Cards (Canada) | Card Type | Value | | ---------------- | ---------------- | | Visa | 4242424242424242 | | MasterCard | 5454545454545454 | | Discover | 6011000992927602 | | American Express | 373599005095005 | ### Guidelines for Testing U.S. Credit Cards * Credit card expiration dates should be any month and year in the future. * To cause a declined message, pass an amount less than `1.00`. * To trigger a fatal error message, pass an invalid card number. * To simulate an AVS match, pass `888` in the `address1` field and `77777` for zip. * To simulate a CVV match, pass `999` in the `cvv` field. ### Guidelines for Testing Canadian Credit Cards * Credit card expiration dates should be any month and year in the future. * Transactions in the test environment must not exceed `$11.00`. * To cause a declined message, pass a transaction amount of `$0.05`. * To trigger a fatal error message, pass an invalid card number. *** ## Test ACH (U.S. Only) | Account Data | Value | | -------------------------- | --------- | | ACH Direct Deposit Account | 123123123 | | ACH Routing Number | 123123123 | ### Triggering Errors in Test Mode for ACH * To cause a declined message, pass an amount less than `1.00`. * To trigger a fatal error message, pass an invalid card number. *** ## Test Credit Card Terminal Transactions There are two methods of testing terminal transactions: using a physical terminal and using the Virtual Payment Terminal (VPT). ### Physical Terminal You can initiate a terminal transaction with ECRYPT's POS modal. Your device must be registered to your ECRYPT account before initiating a sale. Follow the steps below to run your first test transaction: 1. Navigate to the quick action button on the top left of the ECRYPT dashboard. 2. Select **+POS**. 3. Select **Sale** for transaction type and complete the rest of the form fields. 4. Click **Send to Terminal**. 5. Your terminal device will display a request for the transaction and sale amount. Complete the transaction by following the steps on the device. 6. Once the transaction is complete, navigate to **Open Transactions** in the ECRYPT dashboard — your transaction will appear at the top of the table. ### Virtual Payment Terminal (VPT) VPT is a fully functioning virtual payment terminal designed to expedite integration times and remove the requirement for "beta" payment terminals. VPT registration and transaction processing simulates physical payment terminal interactions for auditing, reporting, and testing. > **Note:** VPT is currently limited to VISA EMV. VPT does not support handling "prompts" at this time, though sending the variables in your request will not cause errors. Visit the [terminal reference page](https://docs.ecrypt.com/api-reference/gateway/terminals/create) to access the API endpoint for creating terminals. #### Test Data Registration requests can be submitted using the following information: * **Registration Code:** `T00001` — Successful * **Registration Code:** `T00002` — Failed * **Amount:** `1.00` (amounts under `1.00` generate a failure) #### Triggering Errors in Test Mode * To cause a declined response, pass an amount less than `1.00`. * To trigger a fatal error message in processing, pass an invalid Payment Terminal ID. # Tokens Source: https://docs.ecrypt.com/guides/tokens Tokenizing card and ACH payment data before sending it to your server. ## Overview A token is a secure, single-use reference to raw payment data. Instead of passing card numbers or bank account details through your server, you tokenize them first using your **Public API key** from the browser or client. The resulting token is a UUID you can pass to any transaction endpoint. Tokenization keeps sensitive payment data off your servers, reducing your PCI scope. Tokens are created client-side using your **Public API key**. All transaction endpoints use your **Private API key** server-side. *** ## Create a Token ```bash Card theme={null} curl -X POST https://api.ecrypt.com/v1/tokens \ -H "X-Api-Key: {{public_api_key}}" \ -H "Content-Type: application/json" \ -d '{ "credit_card": { "name_on_card": "Jane Smith", "account_number": "4111111111111111", "expires": "1235", "verification_value": "123", "postal_code": "90210" } }' ``` ```bash ACH theme={null} curl -X POST https://api.ecrypt.com/v1/tokens \ -H "X-Api-Key: {{public_api_key}}" \ -H "Content-Type: application/json" \ -d '{ "check": { "name": "Jane Smith", "account_number": "123456789", "routing_number": "021000021", "account_type": "Checking" } }' ``` ### Request Body Submit either a `creditCard` or `check` object. Do not submit both. #### Credit Card | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------- | | `account_number` | string | Yes | Card PAN. 13-20 digits. | | `expires` | string | Yes | Expiration in `MMYY` format. Example: `1235` = December 2035. | | `verification_value` | string | No | CVV or CVC. 3 or 4 digits. | | `postal_code` | string | No | Billing postal code. Used for AVS. | | `name_on_card` | string | No | Cardholder name as it appears on the card. | #### ACH / Check | Field | Type | Required | Description | | ---------------- | ------- | -------- | --------------------------------- | | `account_number` | string | Yes | Bank account number. 7-20 digits. | | `routing_number` | string | Yes | ABA routing number. 8-20 digits. | | `account_type` | integer | No | `0` = Checking, `1` = Savings. | | `name` | string | No | Name on the bank account. | | `check_number` | string | No | Check number. Up to 8 digits. | *** ## Response ```json theme={null} { "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "metadata": { "credit_card_number": "4***********1111", "credit_card_network": "visa", "credit_card_type": "credit" }, "request_id": "abc123xyz" } ``` | Field | Description | | --------------------- | ------------------------------------------------------------------------ | | `token` | UUID to use in transaction or wallet requests. | | `credit_card_number` | Masked card number. | | `credit_card_network` | Card network: `visa`, `mastercard`, `discover card`, `american express`. | | `credit_card_type` | Card type: `credit`, `debit`, or `pre-paid`. | | `account_number` | Masked ACH account number (ACH tokens only). | *** ## Using a Token Pass the token in the `payment.token` field of any transaction request. ```json Sale with token theme={null} { "payment": { "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "amount": { "value": 49.99, "currency": 840 } } ``` Tokens are valid for a single transaction. If you need to charge the same payment method again, store it to a customer wallet instead. *** ## Storing a Token to a Wallet To reuse a payment method, add the token to a customer's wallet. Wallet entries are stored securely in ECRYPT's vault and can be charged at any time. ```bash theme={null} curl -X POST https://api.ecrypt.com/v1/customers/{{customer_id}}/wallet \ -H "X-Api-Key: {{private_api_key}}" \ -H "Content-Type: application/json" \ -d '{ "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "default": true }' ``` Once stored, charge the customer by referencing the `customer` or `wallet` ID in `payment.stored` rather than a token. Learn how to manage stored payment methods and charge customers on file. *** ## Integration Patterns **Hosted Checkout**-- ECRYPT's hosted iframe and Dynamic Checkout Page tokenizes card data automatically and returns a token. You never handle raw card data. **Terminal** -- Card-present transactions via ECRYPT terminals do not use the token endpoint. The terminal handles card data capture and communicates directly with the gateway. See the [Terminal Guide](/guides/cloud-terminal) for details. *** ## Security Notes * Always create tokens client-side. Never send raw card numbers to your server. * Your Public API key can only be used to create tokens. It cannot initiate transactions or access account data. * Tokens are single-use. A token that has already been used in a transaction cannot be used again. * To meet PCI DSS requirements, do not log or store raw card numbers at any point in your integration. # Transactions Source: https://docs.ecrypt.com/guides/transactions The Reporting API lets you fetch transaction details directly from ECRYPT and display in your own environment. ## Authentication All Reporting API requests require a **Reporting API key** passed in the request header. This is a separate key from your standard private API key. ```http theme={null} X-Api-Key: {{reporting_api_key}} ``` Reporting API keys can be created in the ECRYPT Dashboard under **Settings** > **Account Settings** > **Developer Tools** > **API/Security Keys**. *** ## Get a Transaction Fetch the details of a single transaction by its ID. ```http theme={null} GET https://reportinguiapi.v2.ecrypt.com/api/transactions/{{transaction_id}} ``` ### Request ```http theme={null} GET /api/transactions/230021901 HTTP/1.1 Host: reportinguiapi.v2.ecrypt.com X-Api-Key: {{reporting_api_key}} ``` ### Response ```json theme={null} { "transactionId": 230021901, "type": "SALE", "tender": "CREDITCARD", "paymentName": "A TEST", "paymentNetwork": "MC", "paymentAccount": "5***********1111", "paymentAccountExpiry": "1025", "amount": 29.95, "authorizationAmount": 29.95, "capturedAmount": 29.95, "gratuityAmount": 0.00, "surchargeAmount": 0.00, "settlementAmount": 29.95, "approvalCode": "123456", "avsCode": "N", "cvvCode": "M", "status": "SETTLED", "created": "2024-09-30T17:55:23" } ``` ### Response Fields | Field | Description | | ------------------------ | --------------------------------------------------- | | `transactionId` | Unique transaction identifier | | `type` | Transaction type (e.g., `SALE`, `REFUND`, `VOID`) | | `tender` | Payment method used (e.g., `CREDITCARD`, `ACH`) | | `paymentName` | Name on the payment method | | `paymentNetwork` | Card network (e.g., `VI` = Visa, `MC` = Mastercard) | | `paymentAccount` | Masked account or card number | | `paymentAccountExpiry` | Card expiration in `MMYY` format | | `paymentAccountRouting` | Bank routing number (ACH transactions) | | `amount` | Total transaction amount | | `authorizationAmount` | Amount authorized | | `capturedAmount` | Amount captured | | `gratuityAmount` | Tip amount | | `surchargeAmount` | Surcharge amount | | `settlementAmount` | Amount settled | | `voidedAmount` | Amount voided | | `referenceTransactionId` | ID of the original transaction, if applicable | | `approvalCode` | Issuer approval code | | `avsCode` | AVS response code | | `cvvCode` | CVV response code | | `enhanced` | Whether Level 2/3 data was submitted | | `status` | Transaction status (e.g., `SETTLED`, `VOIDED`) | | `created` | Timestamp the transaction was created (UTC) | # Webhooks Source: https://docs.ecrypt.com/guides/webhooks-setup Webhooks let ECRYPT notify your server in real time when events occur in your account. When a subscribed event fires, ECRYPT sends an HTTP `POST` request containing a JSON payload to the URL you configure. *** ## Register a Webhook Webhooks are managed from the ECRYPT Dashboard. 1. Log in to the ECRYPT Dashboard. 2. Navigate to **Settings** > **Account Settings** > **Developer Tools**. 3. Under **Developer Tools**, locate the **Webhooks** section and click **Edit**. 4. Click **+ Webhook** in the top-right corner to open the **New Webhook** modal. *** ## Configure the Webhook ### Webhook URL Enter the publicly accessible HTTPS endpoint on your server that will receive webhook events. ```text theme={null} https://www.yourdomain.com/webhooks ``` ECRYPT sends a `POST` request to this URL each time a subscribed event occurs. ### Headers If your endpoint requires authentication or custom headers, click **+ Add** to attach key/value header pairs. These headers are included on every outbound request to your endpoint. A common pattern is to pass a shared secret for request verification: | Key | Value | | --------------- | ------------------------------ | | `Authorization` | `Bearer {{your_secret_token}}` | ### Event Subscriptions Select the events you want to receive. Events are grouped by category: | Category | Events | | ----------------- | ----------------------------- | | **Transactions** | Approved, Declined | | **Subscriptions** | Created, Suspended, Cancelled | | **Customers** | Created | You can subscribe to any combination of events on a single webhook endpoint, or create separate webhooks for different event groups. ### Enable / Disable Use the **Disable/Enable** toggle to activate or deactivate a webhook without deleting it. Disabled webhooks do not receive event deliveries. Click **Save Webhook** when finished. *** ## Webhook Payload All webhook events share a common envelope: ```json theme={null} { "event": "", "action": "", "data": { ... } } ``` | Field | Description | | -------- | ----------------------------------------------------------------------- | | `event` | Event category (`transaction`, `subscription`, `customer`) | | `action` | Specific action that occurred (`approved`, `declined`, `created`, etc.) | | `data` | Event-specific payload | ### Transaction Approved ```json theme={null} { "event": "transaction", "action": "approved", "data": { "Transaction": { "TransactionId": "258377101", "AuthCode": "123456", "ResponseCode": "APPROVED", "ResponseText": "Approved", "Latency": 2938, "Avs": { "Code": "", "Text": "" }, "Cvv": { "Code": "N", "Text": "CVV2/CVC2 no match" }, "Amount": 1.50, "Metadata": { "credit_card_network": "visa", "credit_card_number": "4xxxxxxxxxxx1111", "credit_card_expires": "0132", "order_tax": 0, "order_tip": 0 }, "RequestId": "0HN9PI9AU09HO00000004", "Errors": null }, "ReferenceTransactionId": "", "Path": "/v1/transactions/sale" } } ``` ### Transaction Declined ```json theme={null} { "event": "transaction", "action": "declined", "data": { "Transaction": { "TransactionId": "258378101", "AuthCode": "", "ResponseCode": "DECLINED", "ResponseText": "Transaction Rejected", "Latency": 658, "Avs": { "Code": "", "Text": "" }, "Cvv": { "Code": "", "Text": "" }, "Amount": 1.50, "Metadata": { "credit_card_network": "visa", "credit_card_number": "4xxxxxxxxxxx1111", "credit_card_expires": "0132", "order_tax": 0, "order_tip": 0 }, "RequestId": "0HN9PI9ATUN5100000003", "Errors": null }, "ReferenceTransactionId": "", "Path": "/v1/transactions/sale" } } ``` *** ## Best Practices **Respond quickly.** Return an HTTP `200` status as soon as your endpoint receives the request. Perform any processing asynchronously to avoid timeouts. **Verify the source.** Use a shared secret passed via a custom header to confirm requests are coming from ECRYPT. Reject any requests that fail this check. **Handle duplicates.** Webhooks may be delivered more than once in rare cases. Use `RequestId` or `TransactionId` to deduplicate events on your end. **Use HTTPS.** Your endpoint must be accessible over HTTPS. Plain HTTP endpoints are not supported.