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 Merchants API allows you to enroll Merchant details with Card Networks to enable use of other payment APIs such as Network Tokens and 3D Secure.
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.
Lists all Merchants that have been created.
Retrieve Merchant permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns an array of Merchant objects.
Enrolls a Merchant with Card Networks.
In rare cases it can take up to 48 hours to enroll a merchant with each of the card networks. If you are still unable to provision network tokens after this period, please contact support@evervault.com
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 Merchant's Network Tokens configuration. This field should only be populated if the Merchant has already been enrolled in one of the Card Network programs and can use an existing Token Requestor ID (TRID).
Returns the Merchant object that was created.
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.Returns the Merchant object.
Updates a Merchant by its unique identifier.
Update Merchant permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the Merchant object that was updated.
The 3D Secure API can be used in combination with UI Components to authenticate cardholders using 3D Secure. This API allows you to create, retrieve and update 3D Secure sessions.
The details of the 3DS Authentication. This field is present when the status is success.
The 3DS cryptogram (also called Authentication Value). This value must be retrieved and provided to the payment gateway when processing the payment. This value is only present when the status is success and is retained for one hour.
The details of the Electronic Commerce Indicator. This value is only present when the status is success.
The reason for the 3DS Authentication failure. This field is present when the status is failure and can be used for troubleshooting.
Creates a 3DS Session to initiate the 3DS Authentication process. The session ID must then be passed to our client-side SDK to complete the authentication process. Learn more
Create 3DS Session permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The payment details of the 3D-Secure Authentication. This field is mandatory for transactions involving payment authentications but not required for non-payment authentications.
A prioritized list of preferred 3DS versions. The first version in the list is the most preferred. If the first version is not supported, the next version in the list is attempted. If no preferred version is provided, the most optimal version will be automatically selected. If none of the specified versions are supported by the issuer, the session will fail.
Supported versions: 2.2.0
Returns the 3DS Session object that was created.
Retrieve a 3DS Session.
Retrieve 3DS Session permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the 3DS Session object.
The Network Tokens API allows you to provision Network Tokens for cards.
Before creating a Network Token, you must first create a Merchant.
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.
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.Returns the Network Token object that was created.
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.Returns the Network Token object.
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.
Simulates an update to a Network Token so that you can test your integration. Sandbox only.
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.
Retrieves the card art for 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 Bin Lookup API allows you to retrieve information about a card based on its BIN (Bank Identification Number). This includes details such as the card brand, funding type, country, currency, issuer, and more.
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.
Specifies the availability of instant payment capabilities for card transactions, indicating whether funds can be transferred immediately both within the same country and across international borders.
Performs a BIN lookup for the provided card number and retrieves associated information such as the card brand, country, issuer, and more.
Create BIN Lookup permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the BIN Lookup object that was created.
If your account has access to Card Account Updater you can use the Card Account Updater API to register cards for automatic updates. If an update is available for a card, the replacement field will be populated with the identifier of the new card.
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.invalid -- The card is invalid and cannot be used for transactions or updated.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. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
When registering a card, you can provide either an Evervault encrypted card number or a plaintext card number. If you provide a plaintext card number it will be encrypted and the encrypted value will be returned in the response.
Card registration is idempotent on card number and expiry date. Multiple requests to register a card containing the same request body will return the same Card object.
Create Card permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.
Returns the Card object that was created.
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.Returns the Card object.
Deletes a Card by its unique identifier.
Simulates an update to a Card so that you can test your Card Account Updater integration. This endpoint is only available for Sandbox Apps.
Create Card permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the Card object.
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.
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.
Returns a list of Relay objects.
Returns the Relay object that was created.
Returns the Relay object.
A collection of route configurations for the Relay. Any existing route configurations will be replaced with the new configurations.
Returns the updated Relay object.
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
Returns a list of Custom Domain objects.
Creates a custom domain for the Relay
Returns the Custom Domain object that was created.
Returns the Custom Domain object.
A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
Lists all Webhook Endpoints
List Webhook Endpoints permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns a list of Webhook Endpoint objects.
Create a Webhook Endpoint
Create Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the Webhook Endpoint object that was created.
Retrieves a Webhook Endpoint
Retrieve Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.Returns the Webhook Endpoint object.
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 completedReturns the Webhook Endpoint object that was updated.
Delete a Webhook Endpoint
Delete Webhook Endpoint permission. API key permissions can be managed in the App Settings section of the Evervault dashboard.