Tokens

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

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"
    }
  }'

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

{
  "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.

Sale with token

{
  "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.

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.

Customer Wallet

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

Getting Started

Accept Payments

Payment Operations

Customers

Reporting

Developer Resources

Overview

Create a Token

Request Body

Credit Card

ACH / Check

Response

Using a Token

Storing a Token to a Wallet

Customer Wallet

Integration Patterns

Security Notes

​Overview

​Create a Token

​Request Body

​Credit Card

​ACH / Check

​Response

​Using a Token

​Storing a Token to a Wallet

Customer Wallet

​Integration Patterns

​Security Notes

Overview

Create a Token

Request Body

Credit Card

ACH / Check

Response

Using a Token

Storing a Token to a Wallet

Integration Patterns

Security Notes