The Evervault API allows developers to interact programmatically with their Evervault apps using HTTP requests. The Evervault API is built around REST.
The API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Evervault API uses API keys to authenticate requests. You can view and manage your API keys in the App Settings section of the Evervault dashboard.
Requests are authenticated via HTTP Basic Auth. Provide your app ID as the basic auth username and your API key as the password.
If you are handling the Authorization header yourself, you will need to base64 encode the app ID and API key before sending the request:
app_1234:ev:key:1:abcdefd. YXBwXzEyMzQ6...Authorization: Basic YXBwXzUyMzQ6...Evervault uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate the request has failed. Codes in the 5xx range indicate an error with Evervaults’ servers.
Errors returned from the API follow the Problem JSON spec and will be returned as JSON with a Content-Type of application/problem+json.
The encrypt endpoint can be used to encrypt the values of a JSON object, or file. When encrypting the values of a JSON object the Content-Type header should be set to application/json, when encrypting files it should be set to application/octet-stream.
A JSON value or file to be encrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).
An encrypted JSON object or file. For JSON requests, The payload structure will be the same as the one in the request payload, with all of the values encrypted.
The decrypt endpoint can be used to decrypt the values of a JSON object, or file. When decrypting the values of a JSON object the Content-Type header should be set to application/json, when decrypting files it should be set to application/octet-stream.
Decrypt permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.api:decryptA JSON value or file to be decrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).
A decrypted JSON object or file. For JSON requests, The payload structure will be the same as the one in the request payload, with any encrypted values decrypted.
Retrieve metadata for an encrypted value such as the time of encryption, the type of data, the data role and category-specific metadata (e.g. card metadata) without accessing the plaintext value.
Inspect permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.A JSON-formatted string representing the encrypted data to be inspected. Ensure that the string is wrapped in double quotes.
The date and time when the value was encrypted. This is a Unix timestamp in milliseconds. This field is currently only populated for values encrypted with a Data Role.
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
A collection of route configurations for the Relay. Any existing route configurations will be replaced with the new configurations.
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
The customer managed domain to which requests to be relayed to your domain should be sent.
Validation TXT record to be added on the _ev-custom-relay subdomain of your custom domain
The customer managed domain to which requests to be relayed to your domain should be sent.
Validation TXT record to be added on the _ev-custom-relay subdomain of your custom domain
The Function run endpoint lets you invoke an Evervault Function. The body of the request should contain a payload, the value of which will be decrypted and passed as an argument to the Function.
The data payload that the Function will use during its execution. Any encrypted values will be decrypted before being passed to the function.
The outcome of the Function execution. A 'success' denotes successful execution, whereas a 'failure' indicates that the Function encountered an error.
This field represents the output returned by the Function. This is provided only when the Function execution status is 'success'.
This field details any error that occurred during Function execution. This is present only if the status is 'failure'.
Client-Side Tokens are versatile and short-lived tokens that frontend applications can utilize to perform various actions, like running Functions or decrypting data.
After creating a Client-Side Token, you can use it to authenticate requests to the Evervault API by providing it in the Authorization header. The token is a JWT, and should be included in the header in the format:
Authorization: Token <client-side-token>
Client-Side Tokens are restricted to specific payloads. By default, a Client-Side Token will expire after 5 minutes. The maximum expiration time of a token is 10 minutes. When using the REST API, the expiry field must be in epoch milliseconds.
Creates a Merchant. Creating a merchant is a prerequisite for the issuance of Network Tokens, as these tokens are uniquely associated with and scoped to a specific Merchant.
Create Merchant permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.
The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.
A boolean value indicating whether the Merchant is in live mode (true) or in test mode (false).
Retrieves a Merchant by its unique identifier.
Retrieve Merchant permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname.
A boolean value indicating whether the Merchant is in live mode (true) or in test mode (false).
Create a Network Token for a given card.
Create Network Token permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The identifier of the Token Requestor (TRID) that requested the Network Token.
The Token Service Provider (TSP) that issued the Network Token.
The unique identifier of the Payment Account associated with this Network Token.
The status of the Network Token. Active means the Network Token is valid and can be used for payments.
A boolean value indicating whether the Network Token is in live mode (true) or in test mode (false).
Retrieves a Network Token by its unique identifier.
Retrieve Network Token permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The identifier of the Token Requestor (TRID) that requested the Network Token.
The Token Service Provider (TSP) that issued the Network Token.
The unique identifier of the Payment Account associated with this Network Token.
The status of the Network Token. Active means the Network Token is valid and can be used for payments.
A boolean value indicating whether the Network Token is in live mode (true) or in test mode (false).
Deletes a Network Token by its unique identifier.
Delete Network Token permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Creates a Network Token Cryptogram.
Create Network Token Cryptogram permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The value of the Network Token Cryptogram. This is the value that is used embedded in the Authorization request.
A boolean value indicating whether the Network Token Cryptogram is in live mode (true) or in test mode (false).
Creates a Card.
Create Card permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
The card brand associated with the payment card.
The card funding type specifies the method by which transactions are financed. debit refers to cards that draw funds directly from a linked bank account, typically used for immediate payment. credit indicates cards that provide a line of credit from which users can borrow funds for transactions, to be repaid later under the terms of the credit agreement. prepaid are cards loaded with a set amount of funds in advance and can be used until the balance is depleted. deferred-debit cards combine aspects of debit and credit cards, allowing transactions to be debited from a linked account at a later date, usually monthly. charge cards require full payment of the balance at the end of each billing cycle, but do not have a pre-set spending limit.
The card segment indicates the primary market or usage category of the card. Each segment caters to specific needs and functionalities: consumer for personal use cards, offering rewards and benefits for everyday purchases; commercial for cards used by large organizations or corporations with features like higher credit limits and expense tracking; business for small to medium-sized business use, providing simpler accounting integration and business spending rewards; government for cards used by government entities, complying with governmental financial regulations and controls; payouts for cards designed to disburse payments like payroll or cashback; and all for general-purpose cards not confined to a specific segment.
The current status of the card:
active -- The card is active and can be used for transactions.replaced -- The card has been replaced by another card (e.g. expired, lost or stolen).closed -- The card account has been closed and can no longer be used for transactions.The ID of the replacement card. This field is only present if the card has been replaced.
The status of Card Account Updater on this card.
Retrieves a Card by its unique identifier.
Retrieve Card permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
The card brand associated with the payment card.
The card funding type specifies the method by which transactions are financed. debit refers to cards that draw funds directly from a linked bank account, typically used for immediate payment. credit indicates cards that provide a line of credit from which users can borrow funds for transactions, to be repaid later under the terms of the credit agreement. prepaid are cards loaded with a set amount of funds in advance and can be used until the balance is depleted. deferred-debit cards combine aspects of debit and credit cards, allowing transactions to be debited from a linked account at a later date, usually monthly. charge cards require full payment of the balance at the end of each billing cycle, but do not have a pre-set spending limit.
The card segment indicates the primary market or usage category of the card. Each segment caters to specific needs and functionalities: consumer for personal use cards, offering rewards and benefits for everyday purchases; commercial for cards used by large organizations or corporations with features like higher credit limits and expense tracking; business for small to medium-sized business use, providing simpler accounting integration and business spending rewards; government for cards used by government entities, complying with governmental financial regulations and controls; payouts for cards designed to disburse payments like payroll or cashback; and all for general-purpose cards not confined to a specific segment.
The current status of the card:
active -- The card is active and can be used for transactions.replaced -- The card has been replaced by another card (e.g. expired, lost or stolen).closed -- The card account has been closed and can no longer be used for transactions.The ID of the replacement card. This field is only present if the card has been replaced.
The status of Card Account Updater on this card.
Deletes a Card by its unique identifier.
Lists all Webhook Endpoints
List Webhook Endpoints permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Create a Webhook Endpoint
Create Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
Retrieves a Webhook Endpoint
Get Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
Updates a Webhook Endpoint
Update Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.A list of Events that the Webhook Endpoint is subscribed to. The following events are supported:
*: All Eventspayments.merchant.updated: A Merchant was updatedpayments.network-token.updated: A Network Token was updatedfunction.run.completed: An asynchronous Function Run was completedA list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
Delete a Webhook Endpoint
Delete Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.