Skip to main content

Documentation Index

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

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

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.

​
Supported Card Brands

ECRYPT supports the following card networks:
BrandBIN Prefix(es)CVV Name
Visa4CVV
Mastercard51-55, 2221-2720CVC
American Express34, 37CID (4 digits)
Discover (includes JCB, UnionPay)6011, 622, 644-649, 65CID
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. 
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"
  }
}
'

{
  "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 for recurring billing or returning customers), add the token to a customer wallet after creation. See Customer Wallet for details on storing payment methods. 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 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. 
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:
BrandTypical Hold Duration
Visa7 days
Mastercard7 days
American Express7 days
Discover10 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. 
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.00butonlyneedtocharge42.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. 
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. 
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. 
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. 
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.
TimingActionFunds Move?
Pre-settlementVoidNo
Pre-settlementCapture (auth-only)Queued
Post-settlementRefund (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. 
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.
ConfigurationFields RequiredFraud ProtectionDecline Risk
Zip Only (default)postalCodeModerateLow
Full Addressline1, postalCodeHighModerate
NoneNoneNoneNone
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. For a complete list of AVS response codes, see Response Codes.

​
Next Steps