How Payments Work

Documentation Index

Fetch the complete documentation index at: https://docs.ecrypt.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

---

---

​

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.

​

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.

​

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:

---

​

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

---

​

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.

---

​

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

​

ACH Transaction Types

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

---

​

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:

Ready to test? Log in to your ECRYPT sandbox account at developer.ecrypt.com and use test card numbers to simulate the full transaction lifecycle.