API Reference

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.

Authentication

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.

API keys are sensitive and should always be kept secret. You should not store API keys in publically accessible code such as public Github repositories or client-side code.

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:

Combine the app ID and API key into a single string separated by a colon. e.g app_123:api_key_123
Base64 encode the combined string.
Use the base64 encoded string as the value of the Authorization header. Authorization: Basic YXBwXzUyMzQ6...

All requests to the Evervault API must authenticated and made over https.

Example

1const credentials = btoa('<app_id>:<api_key>');
2
3fetch('https://api.evervault.com/encrypt', {
4  method: 'POST',
5  headers: {
6    'Content-Type': 'application/json',
7    Authorization: `Basic ${credentials}`
8  },
9  body: JSON.stringify({
10    message: 'Hello, World!'
11  })
12})

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.

Attributes

code
A short unique code for the returned error. This can be used for handling errors programatically.
title
A human-readable summary of the error.
status
The HTTP status code.
detail
A human-readable explanation of the problem that has occurred.

Example

{
  "code": "functions/request-timeout",
  "title": "Request Timeout",
  "status": 408,
  "detail": "Function execution exceeded the allotted time and has timed out. Please review your code to ensure it finishes within the time limit set in function.toml."
}

Encrypt

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.

Request Body

The JSON value to be encrypted. This can be any valid JSON value: Dictionaries, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

Response Body

The encrypted JSON value.

1curl https://api.evervault.com/encrypt \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "phoneNumber": "555-2368"
7}'

Response

{
  "phoneNumber": "ev:debug:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$"
}

Decrypt

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.

Request Body

The JSON value to be decrypted. This can be any valid JSON value: Dictionaries, Arrays or Strings (strings should be enclosed in double quotes). Non-encrypted values are returned unaltered.

Response Body

The decrypted JSON value.

1curl https://api.evervault.com/decrypt \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "phoneNumber": "ev:debug:Tk9D:cvuknWyEBK9VT1Dv:AzyAK0mI+KP8PU5SqjRHqVSXxTkWUDwotj7qht9/Y8X6:5azjL53LkeIMdfwp4zJoApNpWJ2hJ8NKhSF5OdGejexerv8Pz7i7WDo=:$"
7}'

Response

{
  "phoneNumber": "555-2368"
}

Inspect

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.

Request Body

tokenRequiredstring
The encrypted data to be inspected.

Response Body

typestring
The type of the encrypted value.
Can be one of integer, float, boolean, string
categorystring
The category or specific nature of the encrypted value.
Can be one of card-number
encryptedAtinteger
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.
rolestring
The data role of the encrypted value.
fingerprintstring
A unique identifier for the encrypted value.
metadata
Further metadata about the encrypted value. Returns different information based on the category of the data.

1curl https://api.evervault.com/inspect \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "token": "ev:debug:Tk9D:HBpzdbFWXbX/N2cC:AyjMY/SKO49SlkXcDPtCGs+DxnUn/F8/lAtajCYZ/xT7:KV7AUn9vJJkZDtL8PKdOc8Y11yTL2vZQasFuHqM=:$"
7}'

Response

{
  "type": "string",
  "category": "card-number",
  "encryptedAt": 1700067122000,
  "role": "payment-data",
  "fingerprint": "WUlcOAgQcTN1GEUaoaKrLH1wL2PZrjsUS7byUGZyUEA",
  "metadata": {
    "bin": "424242",
    "lastFour": "4242",
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp",
    "issuer": "Gringotts Wizarding Bank and Trust Company"
  }
}

Functions

Evervault Functions are secure serverless functions which allow you to process data encrypted by Evervault products. When you pass encrypted data to a Function, it is automatically decrypted. You can then process this data by running custom logic written in Node.js or Python as you usually would, but without ever handling it in plaintext on your infrastructure.

Endpoints

post/functions/:function_name/runsRun a Function

Run a Function

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.

Parameters

function_nameRequiredstring
The name of the Function to be executed.

Request Body

payloadRequiredobject
The data payload that the Function will use during its execution. Any encrypted values will be decrypted before being passed to the function.
asyncboolean
If you want your Function to run asynchronously and notify a callback URL, this can be set to true and the API will queue your Function run and return a 202 response code.

Response Body

idstring
A unique identifier representing this specific Function execution instance.
statusstring
The outcome of the Function execution. A 'success' denotes successful execution, whereas a 'failure' indicates that the Function encountered an error.
Can be one of success, failure, scheduled
resultobject
This field represents the output returned by the Function. This is provided only when the Function execution status is 'success'.
errorobject | null
This field details any error that occurred during Function execution. This is present only if the status is 'failure'.
createdAtinteger
The exact time, in epoch milliseconds, when this Function execution was triggered.

1curl 'https://api.evervault.com/functions/{function_name}/runs' \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "payload": {
7    "name": "ev:Tk9D:oVPHsPvwFHNk73DU:AglNWOgZekolcrxdxSpZJOusBgE+C9eWSapGIZkgTsUj:JKeSkdhVE9SCXqQINID4oBRCE/VhTb56VWGqyObP:$"
8  }
9}'

Response

{
  "id": "func_run_eead1d640d7c",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name"
  },
  "createdAt": 1692972623233
}

Client Tokens

Client-Side Tokens are short-lived tokens that can be used to perform actions from your frontend applications.

Endpoints

post/client-side-tokensCreate a Client Token

Create a Client 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.

Request Body

actionRequiredstring
The action that the token should permit
Can be one of api:decrypt
payloadobject
The payload that the token must be used with
expiryinteger
The expiry of the token in milliseconds format. Must be less than 10 minutes from now.

Response Body

idstring
The id of the token
tokenstring
The token
expiryinteger
The expiry of the token in unix millis format
createdAtinteger
The creation time of the token in unix millis format

1curl https://api.evervault.com/client-side-tokens \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "action": "api:decrypt",
7  "payload": {
8    "phoneNumber": "ev:Tk9D:GWgxSXezEFNw10b/:A6JZWe29uiZpP72w+nc0RXOdWdvgCulNqJv8aJpLE/gH:3V/PD54obBv0j+EJMaNNa/ny2tmZq7QM:$"
9  }
10}'

Response

{
  "id": "client_side_token_TDbEef6lgIs",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJzaW9uIjoxLCJhcHBfdXVpZCI6ImFwcF82YWJlZDM1ZDc2YjkiLCJ0ZWFtX3V1aWQiOiJ0ZWFtX2FiZjU1YTk5MTY0NSIsImp0aSI6ImNsaWVudF9zaWRlX3Rva2VuX1REYkVlZjZsZ0lzIiwiZXhwIjoxNzA3MjMzODQxOTgxLCJhY3Rpb24iOiJhcGk6ZGVjcnlwdCIsInJlc291cmNlIjpudWxsLCJoYXNoZWRfYm9keSI6IlJCTnZvMVd6WjRvUlJxMFc5LWhrbnBUN1Q4SWY1MzZERU1CZzloeXFfNG8iLCJjbGllbnRfaXAiOm51bGx9.ea1w3TlZ7p-OLVs-NOAUMij4V5w-9vMAD8W2WEoklsDwwgy8HANXP4e8eAjTA0CkELoUL2FgNesS6S77Z-coG1Yw9TGnkEchgkA6RAXqF65t1bLrW0rvl2AzwFZNwJpEbJc37YqyC2xGeermmYKZCu6in97_fe4rAXSYQiuVtN6V8uLSlAgP9Mr0BmNIf49fnskbc0y2-2qewvZfRM7mPQ6NXcQE_jhUjy3OhaohdvU1FpaLs3OrzW2Ej8wE1hOjc5hRtT2cslaY4Bl2x4YNMRVObWg7GYCdETG280ilXTUu9jIPmkXt8QBzouZOP5nuhCjYxFJ2fYZMLj7vYukwdiyBtiUADXDzmnFyh7icAWib76z_hW3VLRjQSlq-fgvQJfM71j5RGBEmLrQNAPRREYjCiM8cwmOh5sFaLdmu4wM6-lgPn8dvHSqENwggs_nfxPyavHChNn8KOo4FS64YYeB28hqSvBAMT-umCdv7n2I-YF6fJOpgJrQOK35MPt4kKfqULJ45wpSnzsSpT9kTrLw0-9-6JpMtsQio0UJ27aXHMPErFcNMcW2hEhPdNsjSfIEmK7lCaUOed-wETkkfIaoTe5ly051baj-VWbAbNXH2jduia2rCZoofXTABADRzeBrFyDNRZXNQ205n0xh3PpIcazKw_vCAD_EDXmcCsFo",
  "expiry": 1707233841981,
  "createdAt": 1707233541981
}

Relays

Relay is a network proxy that can be configured to encrypt or decrypt sensitive data as it passes between a client and a destination server. Relay can be used with your own API or with third-party APIs. It is designed to be easy to use and requires minimal changes to your existing code.

Endpoints

post/relaysCreate a Relay
get/relaysList all Relays
get/relays/:idRetrieve a Relay
patch/relays/:idUpdates a Relay
delete/relays/:idDelete a Relay
post/relays/:relay_id/custom-domainsCreate a Custom Domain
get/relays/:relay_id/custom-domainsList all Custom Domains
get/relays/:relay_id/custom-domains/:idRetrieve a Custom Domain
delete/relays/:relay_id/custom-domains/:idDelete a Custom Domain

Create a Relay

Creates a new Relay.

Request Body

destinationDomainRequiredstring
The domain in front of which you would like to configure a Relay
routesRequiredarray
A collection of route configurations for the Relay.
encryptEmptyStringsboolean
Whether or not empty strings should be encrypted. Defaults to true.
authenticationstring | null
The type of authentication required for the Relay. Set this to 'api-key' to enable API key authentication.
Can be one of api-key,

Response Body

idstring
The unique identifier for the Relay.
destinationDomainstring
The domain in front of which the Relay should be configured.
evervaultDomainstring
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
routesarray
A collection of route configurations for the Relay.
authenticationstring | null
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
Can be one of api-key,
encryptEmptyStringsboolean
Whether or not empty strings should be encrypted.
appstring
The unique identifier for the app to which the Relay belongs.
createdAtinteger
The exact time, in epoch milliseconds, when this Relay was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Relay was updated.

1curl https://api.evervault.com/relays \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "destinationDomain": "example.com",
7  "encryptEmptyStrings": true,
8  "authentication": null,
9  "routes": [
10    {
11      "method": "POST",
12      "path": "/checkout",
13      "request": [
14        {
15          "action": "encrypt",
16          "selections": [
17            {
18              "type": "json",
19              "selector": "$.cardNumber"
20            }
21          ]
22        }
23      ],
24      "response": [
25        {
26          "action": "decrypt",
27          "selections": [
28            {
29              "type": "json",
30              "selector": "$..*"
31            }
32          ]
33        }
34      ]
35    }
36  ]
37}'

Response

{
  "id": "relay_destination_d4ja57js9lnh",
  "destinationDomain": "example.com",
  "evervaultDomain": "example-com.app-12345.relay.evervault.app",
  "encryptEmptyStrings": true,
  "routes": [
    {
      "method": "POST",
      "path": "/checkout",
      "request": [
        {
          "action": "encrypt",
          "selections": [
            {
              "type": "json",
              "role": "pci",
              "selector": "$.cardNumber"
            }
          ]
        }
      ],
      "response": [
        {
          "action": "decrypt",
          "selections": [
            {
              "type": "json",
              "selector": "$..*"
            }
          ]
        }
      ]
    }
  ],
  "app": "app_cc7fcd533649",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623234
}

List all Relays

Lists all Relays for the App.

Response Body

dataarray
An array of Relays belonging to the App.

1curl https://api.evervault.com/relays \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "data": [
    {
      "id": "relay_destination_d4ja57js9lnh",
      "destinationDomain": "example.com",
      "evervaultDomain": "example-com.app-12345.relay.evervault.app",
      "encryptEmptyStrings": true,
      "authentication": "api-key",
      "routes": [
        {
          "method": "POST",
          "path": "/checkout",
          "request": [
            {
              "action": "encrypt",
              "selections": [
                {
                  "type": "json",
                  "role": "pci",
                  "selector": "$.cardNumber"
                }
              ]
            }
          ],
          "response": [
            {
              "action": "decrypt",
              "selections": [
                {
                  "type": "json",
                  "selector": "$..*"
                }
              ]
            }
          ]
        }
      ],
      "app": "app_cc7fcd533649",
      "createdAt": 1692972623233,
      "updatedAt": 1692972623234
    }
  ]
}

Retrieve a Relay

Retrieves a Relay by its ID.

Parameters

idRequiredstring
The id of the Relay to be fetched.

Response Body

idstring
The unique identifier for the Relay.
destinationDomainstring
The domain in front of which the Relay should be configured.
evervaultDomainstring
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
routesarray
A collection of route configurations for the Relay.
authenticationstring | null
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
Can be one of api-key,
encryptEmptyStringsboolean
Whether or not empty strings should be encrypted.
appstring
The unique identifier for the app to which the Relay belongs.
createdAtinteger
The exact time, in epoch milliseconds, when this Relay was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Relay was updated.

1curl 'https://api.evervault.com/relays/{id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "relay_destination_d4ja57js9lnh",
  "destinationDomain": "example.com",
  "evervaultDomain": "example-com.app-12345.relay.evervault.app",
  "encryptEmptyStrings": true,
  "authentication": "api-key",
  "routes": [
    {
      "method": "POST",
      "path": "/checkout",
      "request": [
        {
          "action": "encrypt",
          "selections": [
            {
              "type": "json",
              "role": "pci",
              "selector": "$.cardNumber"
            }
          ]
        }
      ],
      "response": []
    }
  ],
  "app": "app_cc7fcd533649",
  "createdAt": 1692972623233
}

Updates a Relay

Updates a Relay. Any properties not provided are left unchanged.

Parameters

idRequiredstring
The id of the Relay to be updated.

Request Body

routesarray
A collection of route configurations for the Relay. Any existing route configurations will be replaced with the new configurations.
encryptEmptyStringsboolean
Whether or not empty strings should be encrypted.
authentication
The type of authentication required for the Relay.

Response Body

idstring
The unique identifier for the Relay.
destinationDomainstring
The domain in front of which the Relay should be configured.
evervaultDomainstring
The Evervault managed domain to which requests to be relayed to the destination domain should be sent.
routesarray
A collection of route configurations for the Relay.
authenticationstring | null
The type of authentication required for the Relay. If this is null then the Relay is unauthenticated.
Can be one of api-key,
encryptEmptyStringsboolean
Whether or not empty strings should be encrypted.
appstring
The unique identifier for the app to which the Relay belongs.
createdAtinteger
The exact time, in epoch milliseconds, when this Relay was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Relay was updated.

1curl 'https://api.evervault.com/relays/{id}' \
2  --request PATCH \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "routes": [
7    {
8      "method": "POST",
9      "path": "/checkout",
10      "request": [
11        {
12          "action": "encrypt",
13          "selections": [
14            {
15              "type": "json",
16              "selector": "$.cardNumber"
17            }
18          ]
19        }
20      ],
21      "response": []
22    }
23  ]
24}'

Response

{
  "id": "relay_destination_d4ja57js9lnh",
  "destinationDomain": "example.com",
  "evervaultDomain": "example-com.app-12345.relay.evervault.app",
  "encryptEmptyStrings": true,
  "authentication": null,
  "routes": [
    {
      "method": "POST",
      "path": "/checkout",
      "request": [
        {
          "action": "encrypt",
          "selections": [
            {
              "type": "json",
              "role": "pci",
              "selector": "$.cardNumber"
            }
          ]
        }
      ],
      "response": []
    }
  ],
  "app": "app_cc7fcd533649",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623234
}

Delete a Relay

Deletes a Relay. This action cannot be undone and the Relay domain will no longer forward requests to its destination domain.

Parameters

idRequiredstring
The id of the Relay to be deleted.

Create a Custom Domain

Creates a custom domain for the Relay

Parameters

relay_idRequiredstring
The id of the Relay to which the custom domain should be added.

Request Body

customDomainRequiredstring
The customer managed domain to which requests to be relayed to your domain should be sent.

Response Body

idstring
The unique identifier for the custom domain.
customDomainstring
The customer managed domain to which requests to be relayed to your domain should be sent.
relaystring
The ID of the Relay with which this custom domain is associated.
statusstring
The status of the domains DNS verification.
Can be one of active, inactive
validationRecordstring
Validation TXT record to be added on the _ev-custom-relay subdomain of your custom domain
createdAtinteger
The exact time, in epoch milliseconds, when this custom domain was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this custom domain was last updated.

1curl 'https://api.evervault.com/relays/{relay_id}/custom-domains' \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "customDomain": "subdomain.example.com"
7}'

Response

{
  "id": "custom_domain_j3od9Bl0WV1n",
  "customDomain": "subdomain.example.com",
  "status": "active",
  "validationRecord": "986f3008-86e7-4caf-bd8b-a5d312844153",
  "relay": "relay_destination_d4ja57js9lnh",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623233
}

List all Custom Domains

Lists all custom domains for a Relay.

Parameters

relay_idRequiredstring
The id of the Relay whose custom domains should be fetched.

Response Body

dataarray

1curl 'https://api.evervault.com/relays/{relay_id}/custom-domains' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "data": [
    {
      "id": "custom_domain_j3od9Bl0WV1n",
      "customDomain": "subdomain.example.com",
      "status": "active",
      "validationRecord": "986f3008-86e7-4caf-bd8b-a5d312844153",
      "relay": "relay_destination_d4ja57js9lnh",
      "createdAt": 1692972623233,
      "updatedAt": 1692972623234
    }
  ]
}

Retrieve a Custom Domain

Retrieves a custom domain for a Relay.

Parameters

relay_idRequiredstring
The id of the Relay to which the custom domain belongs.
idRequiredstring
The id of the custom domain to be fetched.

Response Body

idstring
The unique identifier for the custom domain.
customDomainstring
The customer managed domain to which requests to be relayed to your domain should be sent.
relaystring
The ID of the Relay with which this custom domain is associated.
statusstring
The status of the domains DNS verification.
Can be one of active, inactive
validationRecordstring
Validation TXT record to be added on the _ev-custom-relay subdomain of your custom domain
createdAtinteger
The exact time, in epoch milliseconds, when this custom domain was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this custom domain was last updated.

1curl 'https://api.evervault.com/relays/{relay_id}/custom-domains/{id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "custom_domain_j3od9Bl0WV1n",
  "customDomain": "subdomain.example.com",
  "status": "active",
  "validationRecord": "986f3008-86e7-4caf-bd8b-a5d312844153",
  "relay": "relay_destination_d4ja57js9lnh",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623233
}

Delete a Custom Domain

Deletes a custom domain for a Relay. This action cannot be undone.

Parameters

relay_idRequiredstring
The id of the Relay to which the custom domain belongs.
idRequiredstring
The id of the custom domain to be deleted.

1curl 'https://api.evervault.com/relays/{relay_id}/custom-domains/{id}' \
2  --request DELETE \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Insights

The Evervault API provides several endpoints which can be used to retrieve additional information for cards and bin ranges. This can be used for tasks such as fraud detection and payment routing.

Endpoints

post/insights/cardCard Insights
post/payments/bin-lookupsBIN Lookup

Card Insights

The Card Insights API allows you to perform address verification (AVS), name verification (ANI), and CVV verification checks. You can also check the card's push and pull transaction capabilities, as well as network and interchange fee estimates.

Request Body

cardRequiredobject
The card details.
extensionsarray
The extensions to the card insight request. Example with all possible values - ["address", "cardholder", "cvv", "fees", "capabilities"]
transactionobject
Details of the transaction. Required if the fees extension is requested.
cardholderobject
Details about the cardholder that the name verification (ANI) is for. Required if the cardholder extension is requested.
addressRequiredobject
Details about the cardholder's address that the address verification (AVS) is for. Required if the address extension is requested.

Response Body

idRequiredstring
The unique identifier for the Card Insight
fingerprintRequiredstring
A unique, cryptographically secure identifier for the card number. Useful for deduplication.
binRequiredobject
The BIN details for the supplied card. This includes details such as the card brand, funding type, issuer, 3D Secure support and more.
capabilitiesobject
The push and pull capabilities of the card
feesobject
The estimated network and interchange fees for push and pull transactions
cardholderobject
addressobject
cvvobject
The result of the CVV verification check
paymentAccountReferencestring
The unique identifier of the Payment Account associated with this card.
createdAtRequiredinteger
Unix timestamp of when the card insight was created

1curl https://api.evervault.com/insights/card \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "card": {
7    "number": "4111111111111111",
8    "expiry": {
9      "month": "09",
10      "year": "29"
11    },
12    "cvv": "123"
13  },
14  "extensions": [
15    "capabilities",
16    "fees",
17    "cvv",
18    "address",
19    "cardholder"
20  ],
21  "transaction": {
22    "amount": 2500,
23    "currency": "usd"
24  },
25  "cardholder": {
26    "firstName": "John",
27    "lastName": "Doe"
28  },
29  "address": {
30    "postalCode": "10001",
31    "line1": "123 Main Street",
32    "line2": "Apt 4B",
33    "city": "New York",
34    "state": "NY",
35    "country": "us"
36  }
37}'

Response

{
  "id": "card_insight_1234567890",
  "fingerprint": "WUlcOAgQcTN1GEUaoaKrLH1wL2PZrjsUS7byUGZyUEA",
  "bin": {
    "brand": "visa",
    "funding": "credit",
    "segment": "consumer",
    "country": "us",
    "currency": "usd",
    "issuer": "Gringotts Wizarding Bank and Trust Company",
    "productName": "Visa Credit",
    "fastFunds": {
      "domestic": true,
      "crossBorder": true
    },
    "threeDS": {
      "supportedVersions": {
        "accessControlServer": [
          "2.2.0"
        ],
        "directoryServer": [
          "2.2.0",
          "2.3.1"
        ]
      },
      "acsInfoIndicators": [
        {
          "code": "acs-auth-available",
          "indicator": "01",
          "description": "Authentication Available at ACS"
        }
      ]
    },
    "type": "card"
  },
  "capabilities": {
    "push": {
      "enabled": true,
      "network": "visa",
      "type": "credit",
      "availability": "immediate",
      "regulated": true,
      "currency": {
        "alphaCode": "usd",
        "numericCode": "840"
      },
      "country": {
        "alphaCode": "us",
        "numericCode": "840"
      }
    },
    "pull": {
      "enabled": true,
      "network": "visa",
      "type": "credit",
      "regulated": true,
      "currency": {
        "alphaCode": "usd",
        "numericCode": "840"
      },
      "country": {
        "alphaCode": "us",
        "numericCode": "840"
      }
    }
  },
  "fees": {
    "currency": {
      "alphaCode": "usd",
      "numericCode": "840"
    },
    "push": {
      "interchange": 5,
      "network": 5
    },
    "pull": {
      "interchange": 5,
      "network": 5
    }
  },
  "cvv": {
    "code": "match",
    "value": "M"
  },
  "address": {
    "avsIdentifier": "aBcdeFGhIJKlmnoPqR",
    "networkIdentifier": "1234567890",
    "networkResponseCode": {
      "value": "85"
    },
    "result": {
      "value": "Y",
      "address": "match",
      "zip": "match"
    }
  },
  "cardholder": {
    "result": {
      "value": "M",
      "code": "match-performed"
    },
    "fullName": {
      "value": "M",
      "code": "match"
    },
    "firstName": {
      "value": "M",
      "code": "match"
    },
    "lastName": {
      "value": "M",
      "code": "match"
    }
  },
  "paymentAccountReference": "V0010011111111111111111111111",
  "createdAt": 169297262323
}

BIN Lookup

Performs a BIN lookup for the provided card number and retrieves associated information such as the card brand, country, issuer, and more.

Request Body

numberRequiredstring
The card number for which the BIN lookup is being requested. It can be a plaintext Card number (FPAN) / Network Token number (DPAN), an encrypted Card number / Network Token number or simply just a BIN (6-10 first digits of a Card Number) for range lookup.

Response Body

idstring
The unique identifier for the BIN lookup
brandstring
The card brand associated with the payment card.
Can be one of visa, mastercard, american-express, discover, diners-club, jcb, unionpay
fundingstring
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.
Can be one of debit, credit, prepaid, deferred-debit, charge
segmentstring
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.
Can be one of consumer, commercial, business, government, payouts, all
countrystring
The country associated with the card (ISO 3166-1 alpha-2)
currencystring
The currency associated with the card (ISO 4217)
issuerstring
The name of the issuer bank
typenull | string
Type of card range identified during the lookup (card or network-token).
Can be one of , card, network-token
productNamestring
The name of the product associated with the card
fastFundsobject
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.
threeDSobject
Metadata about 3DS capabilities, including supported versions and ACS (Access Control Server) indicators.
createdAtinteger
Unix timestamp of when the BIN lookup was created

1curl https://api.evervault.com/payments/bin-lookups \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "number": "4242424242424242"
7}'

Response

{
  "id": "bin_lookup_1234567890",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "productName": "Visa Debit",
  "fastFunds": {
    "domestic": true,
    "crossBorder": true
  },
  "threeDS": {
    "supportedVersions": {
      "accessControlServer": [
        "2.2.0"
      ],
      "directoryServer": [
        "2.2.0",
        "2.3.1"
      ]
    },
    "acsInfoIndicators": [
      {
        "code": "acs-auth-available",
        "indicator": "01",
        "description": "Authentication Available at ACS"
      }
    ]
  },
  "type": "card",
  "createdAt": 169297262323
}

Merchants

Endpoints

post/payments/merchantsCreate a Merchant
get/payments/merchantsList Merchants
get/payments/merchants/:merchant_idRetrieve a Merchant
patch/payments/merchants/:merchant_idUpdate a Merchant
delete/payments/merchants/:merchant_idDelete a Merchant

Create a Merchant

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

Request Body

nameRequiredstring
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.
websiteRequiredstring
The official website URL of the Merchant.
categoryCodeRequiredstring
The 4-digit Merchant Category Code (MCC).
businessRequiredobject
The business details of the Merchant.
networkTokensobject
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).
applePayobject
The Merchant's Apple Pay configuration.

Response Body

idRequiredstring
A unique identifier assigned to each Merchant.
nameRequiredstring
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.
websiteRequiredstring
The official website URL of the Merchant.
businessobject
The business details of the Merchant.
categoryCodestring
The 4-digit Merchant Category Code (MCC).
networkTokensobject
The Merchant's Network Token configuration.
applePayobject
The Merchant's Apple Pay configuration.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Merchant was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Merchant was last updated.

1curl https://api.evervault.com/payments/merchants \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "name": "Ollivanders Wand Shop",
7  "website": "https://www.ollivanders.co.uk",
8  "categoryCode": "5945",
9  "business": {
10    "legalName": "Ollivanders Wand Shop Ltd.",
11    "address": {
12      "line1": "Diagon Alley",
13      "city": "London",
14      "postalCode": "WD1 1AA",
15      "country": "gb"
16    }
17  },
18  "applePay": {
19    "domains": [
20      "ollivanders.co.uk"
21    ]
22  }
23}'

Response

{
  "id": "merchant_eead1d640d7c",
  "name": "Ollivanders Wand Shop",
  "website": "https://www.ollivanders.co.uk",
  "categoryCode": "5945",
  "business": {
    "legalName": "Ollivanders Wand Shop Ltd.",
    "address": {
      "line1": "Diagon Alley",
      "city": "London",
      "postalCode": "WD1 1AA",
      "country": "gb"
    }
  },
  "networkTokens": {
    "enrolment": [
      {
        "cardBrand": "mastercard",
        "tokenRequestorIdentifier": "50165156978",
        "status": "active"
      },
      {
        "cardBrand": "visa",
        "tokenRequestorIdentifier": "40238123804",
        "status": "active"
      },
      {
        "cardBrand": "american-express",
        "tokenRequestorIdentifier": null,
        "status": "inactive"
      }
    ]
  },
  "applePay": {
    "domains": [
      {
        "domain": "ollivanders.co.uk",
        "status": "pending"
      }
    ]
  },
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

List Merchants

Lists all Merchants that have been created.

Parameters

pageinteger
The page number to retrieve.

Response Body

merchantsarray

1curl https://api.evervault.com/payments/merchants \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "merchants": [
    {
      "id": "merchant_eead1d640d7c",
      "name": "Ollivanders Wand Shop",
      "website": "https://www.ollivanders.co.uk",
      "categoryCode": "5945",
      "business": {
        "legalName": "Ollivanders Wand Shop Ltd.",
        "address": {
          "line1": "Diagon Alley",
          "city": "London",
          "postalCode": "WD1 1AA",
          "country": "gb"
        }
      },
      "networkTokens": {
        "enrolment": [
          {
            "cardBrand": "mastercard",
            "tokenRequestorIdentifier": "50165156978",
            "status": "active"
          },
          {
            "cardBrand": "visa",
            "tokenRequestorIdentifier": "40238123804",
            "status": "active"
          },
          {
            "cardBrand": "american-express",
            "tokenRequestorIdentifier": null,
            "status": "inactive"
          }
        ]
      },
      "createdAt": 1692972623233,
      "updatedAt": 1692972623768
    }
  ]
}

Retrieve a Merchant

Retrieves a Merchant by its unique identifier.

Parameters

merchant_idRequiredstring
The unique identifier of the merchant.

Response Body

idRequiredstring
A unique identifier assigned to each Merchant.
nameRequiredstring
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.
websiteRequiredstring
The official website URL of the Merchant.
businessobject
The business details of the Merchant.
categoryCodestring
The 4-digit Merchant Category Code (MCC).
networkTokensobject
The Merchant's Network Token configuration.
applePayobject
The Merchant's Apple Pay configuration.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Merchant was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Merchant was last updated.

1curl 'https://api.evervault.com/payments/merchants/{merchant_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "merchant_eead1d640d7c",
  "name": "Ollivanders Wand Shop",
  "website": "https://www.ollivanders.co.uk",
  "categoryCode": "5945",
  "business": {
    "legalName": "Ollivanders Wand Shop Ltd.",
    "address": {
      "line1": "Diagon Alley",
      "city": "London",
      "postalCode": "WD1 1AA",
      "country": "gb"
    }
  },
  "networkTokens": {
    "enrolment": [
      {
        "cardBrand": "mastercard",
        "tokenRequestorIdentifier": "50165156978",
        "status": "active"
      },
      {
        "cardBrand": "visa",
        "tokenRequestorIdentifier": "40238123804",
        "status": "active"
      },
      {
        "cardBrand": "american-express",
        "tokenRequestorIdentifier": null,
        "status": "inactive"
      }
    ]
  },
  "applePay": {
    "domains": [
      {
        "domain": "ollivanders.co.uk",
        "status": "active"
      }
    ]
  },
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Update a Merchant

Updates a Merchant by its unique identifier.

Parameters

merchant_idRequiredstring
The id of the Merchant to be updated.

Request Body

applePayobject
The Merchant's Apple Pay configuration.

Response Body

idRequiredstring
A unique identifier assigned to each Merchant.
nameRequiredstring
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.
websiteRequiredstring
The official website URL of the Merchant.
businessobject
The business details of the Merchant.
categoryCodestring
The 4-digit Merchant Category Code (MCC).
networkTokensobject
The Merchant's Network Token configuration.
applePayobject
The Merchant's Apple Pay configuration.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Merchant was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Merchant was last updated.

1curl 'https://api.evervault.com/payments/merchants/{merchant_id}' \
2  --request PATCH \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "applePay": {
7    "domains": [
8      "ollivanders.co.uk"
9    ]
10  }
11}'

Response

{
  "id": "merchant_eead1d640d7c",
  "name": "Ollivanders Wand Shop",
  "website": "https://www.ollivanders.co.uk",
  "categoryCode": "5945",
  "business": {
    "legalName": "Ollivanders Wand Shop Ltd.",
    "address": {
      "line1": "Diagon Alley",
      "city": "London",
      "postalCode": "WD1 1AA",
      "country": "gb"
    }
  },
  "networkTokens": {
    "enrolment": [
      {
        "cardBrand": "mastercard",
        "tokenRequestorIdentifier": "50165156978",
        "status": "active"
      },
      {
        "cardBrand": "visa",
        "tokenRequestorIdentifier": "402338123804",
        "status": "active"
      },
      {
        "cardBrand": "american-express",
        "tokenRequestorIdentifier": null,
        "status": "inactive"
      }
    ]
  },
  "applePay": {
    "domains": [
      {
        "domain": "ollivanders.co.uk",
        "status": "pending"
      }
    ]
  },
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Delete a Merchant

Deletes a Merchant by its unique identifier.

Parameters

merchant_idRequiredstring
The id of the Merchant to be deleted.

1curl 'https://api.evervault.com/payments/merchants/{merchant_id}' \
2  --request DELETE \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Acquirers

The Acquirer API allows you to enroll Acquirer details with Card Networks to enable use of other payment APIs such as 3D Secure.

Endpoints

post/payments/acquirersCreate an Acquirer
get/payments/acquirersList Acquirers
get/payments/acquirers/:acquirer_idRetrieve an Acquirer
patch/payments/acquirers/:acquirer_idUpdate an Acquirer
delete/payments/acquirers/:acquirer_idDelete an Acquirer

Create an Acquirer

Creates an Acquirer to be used with 3DS sessions.

Request Body

nameRequiredstring
The name of the Acquirer.
descriptionstring
The description of the Acquirer.
defaultboolean
Specifies whether this Acquirer is the default. Only one default Acquirer configuration can exist at a time; setting a new one clears the previous default. If none is defined, the first Acquirer created becomes the default. See the Acquirers API for details.
configurationsRequiredarray
The configurations of the Acquirer.

Response Body

idRequiredstring
The unique identifier of the acquirer configuration.
nameRequiredstring
The name of the acquirer configuration.
descriptionRequiredstring
The description of the acquirer configuration.
defaultRequiredboolean
configurationsRequiredarray
The acquirer configuration settings.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Acquirer was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Acquirer was last updated.

1curl https://api.evervault.com/payments/acquirers \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Response

{
  "id": "acquirer_adk3kdljc3",
  "name": "Ollivanders Wand Shop Production Configuration",
  "description": "Ollivanders Wand Shop Production Configuration",
  "default": true,
  "configurations": [
    {
      "network": "mastercard",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    },
    {
      "network": "visa",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    }
  ],
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

List Acquirers

Lists all Acquirers that have been created.

Parameters

pageinteger
The page number to retrieve.

Response Body

acquirersarray

1curl https://api.evervault.com/payments/acquirers \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "acquirers": [
    {
      "id": "acquirer_adk3kdljc3",
      "name": "Ollivanders Wand Shop Production Configuration",
      "description": "Ollivanders Wand Shop Production Configuration",
      "default": true,
      "configurations": [
        {
          "network": "mastercard",
          "bin": "424242",
          "acquirerMerchantIdentifier": "38191048173",
          "state": "active",
          "country": "ie"
        },
        {
          "network": "visa",
          "bin": "424242",
          "acquirerMerchantIdentifier": "38191048173",
          "state": "active",
          "country": "ie"
        }
      ],
      "createdAt": 1692972623233,
      "updatedAt": 1692972623768
    }
  ]
}

Retrieve an Acquirer

Retrieves an Acquirer by its unique identifier.

Parameters

acquirer_idRequiredstring
The unique identifier of the Acquirer.

Response Body

idRequiredstring
The unique identifier of the acquirer configuration.
nameRequiredstring
The name of the acquirer configuration.
descriptionRequiredstring
The description of the acquirer configuration.
defaultRequiredboolean
configurationsRequiredarray
The acquirer configuration settings.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Acquirer was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Acquirer was last updated.

1curl 'https://api.evervault.com/payments/acquirers/{acquirer_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "acquirer_adk3kdljc3",
  "name": "Ollivanders Wand Shop Production Configuration",
  "description": "Ollivanders Wand Shop Production Configuration",
  "default": true,
  "configurations": [
    {
      "network": "mastercard",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    },
    {
      "network": "visa",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    }
  ],
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Update an Acquirer

Updates an Acquirer by its unique identifier.

Parameters

acquirer_idRequiredstring
The id of the Acquirer to be updated.

Request Body

namestring
The name of the Acquirer.
descriptionstring
The description of the Acquirer.
defaultboolean
Specifies whether this Acquirer is the default. Only one default Acquirer configuration can exist at a time; setting a new one clears the previous default. See the Acquirers API for details.
configurationsarray
The configurations of the Acquirer. The configuration is identified by its network.

Response Body

idRequiredstring
The unique identifier of the acquirer configuration.
nameRequiredstring
The name of the acquirer configuration.
descriptionRequiredstring
The description of the acquirer configuration.
defaultRequiredboolean
configurationsRequiredarray
The acquirer configuration settings.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Acquirer was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Acquirer was last updated.

1curl 'https://api.evervault.com/payments/acquirers/{acquirer_id}' \
2  --request PATCH \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Response

{
  "id": "acquirer_adk3kdljc3",
  "name": "Ollivanders Wand Shop Production Configuration",
  "description": "Ollivanders Wand Shop Production Configuration",
  "default": true,
  "configurations": [
    {
      "network": "mastercard",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    },
    {
      "network": "visa",
      "bin": "424242",
      "acquirerMerchantIdentifier": "38191048173",
      "state": "active",
      "country": "ie"
    }
  ],
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Delete an Acquirer

Deletes an Acquirer by its unique identifier.

Parameters

acquirer_idRequiredstring
The id of the Acquirer to be deleted.

1curl 'https://api.evervault.com/payments/acquirers/{acquirer_id}' \
2  --request DELETE \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Network Tokens

Endpoints

post/payments/network-tokensCreate a Network Token
get/payments/network-tokens/:network_token_idRetrieve a Network Token
delete/payments/network-tokens/:network_token_idDelete a Network Token
post/payments/network-tokens/:network_token_id/cryptogramsCreate a Cryptogram
post/payments/network-tokens/:network_token_id/simulateSimulate a Network Token Update
get/payments/network-tokens/:network_token_id/card-artRetrieve Card Art

Create a Network Token

Create a Network Token for a given card.

Request Body

cardRequiredobject
merchantRequiredstring
The unique identifier of the Merchant previously created using the Evervault API. It denotes the Merchant to which the Network Token should be associated with.

Response Body

idRequiredstring
A unique identifier representing a specific Network Token.
numberRequiredstring
The unique number of the Network Token.
expiryRequiredobject
The expiry details of the Network Token.
cardRequiredobject
The details of the underlying encrypted card.
tokenRequestorIdentifierRequiredstring
The identifier of the Token Requestor (TRID) that requested the Network Token.
tokenServiceProviderRequiredstring
The Token Service Provider (TSP) that issued the Network Token.
Can be one of mdes, vts, aets
paymentAccountReferencestring
The unique identifier of the Payment Account associated with this Network Token.
statusRequiredstring
The status of the Network Token. Active means the Network Token is valid and can be used for payments.
Can be one of active, inactive
merchantRequiredstring
The unique identifier of the Merchant associated with this Network Token.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Network Token was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Network Token was last updated.

1curl https://api.evervault.com/payments/network-tokens \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "card": {
7    "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
8    "expiry": {
9      "month": "09",
10      "year": "26"
11    },
12    "cvc": "ev:debug:Tk9D:number:2GW8Nk96yfb2UXcw:A4UOUDGNb16Q//uBYVPibmfJ2734IrvPAoVY+8PvGG0C:5jtAu8KN1HiPeCNqSDCKMapfpg==:$"
13  },
14  "merchant": "merchant_ddsaJsda9d86"
15}'

Response

{
  "id": "network_token_eead1d640d7c",
  "number": "4498004918463434",
  "expiry": {
    "month": "13",
    "year": "25"
  },
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "09",
      "year": "26"
    },
    "brand": "visa"
  },
  "paymentAccountReference": "512381d9f8e0629211e3949a08002",
  "tokenRequestorIdentifier": "40020248564",
  "tokenServiceProvider": "vts",
  "merchant": "merchant_ddsaJsda9d86",
  "status": "active",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Retrieve a Network Token

Retrieves a Network Token by its unique identifier.

Parameters

network_token_idRequiredstring
The unique identifier of the Network Token.

Response Body

idRequiredstring
A unique identifier representing a specific Network Token.
numberRequiredstring
The unique number of the Network Token.
expiryRequiredobject
The expiry details of the Network Token.
cardRequiredobject
The details of the underlying encrypted card.
tokenRequestorIdentifierRequiredstring
The identifier of the Token Requestor (TRID) that requested the Network Token.
tokenServiceProviderRequiredstring
The Token Service Provider (TSP) that issued the Network Token.
Can be one of mdes, vts, aets
paymentAccountReferencestring
The unique identifier of the Payment Account associated with this Network Token.
statusRequiredstring
The status of the Network Token. Active means the Network Token is valid and can be used for payments.
Can be one of active, inactive
merchantRequiredstring
The unique identifier of the Merchant associated with this Network Token.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Network Token was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Network Token was last updated.

1curl 'https://api.evervault.com/payments/network-tokens/{network_token_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "network_token_eead1d640d7c",
  "number": "4498004918463434",
  "expiry": {
    "month": "13",
    "year": "25"
  },
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "09",
      "year": "26"
    },
    "brand": "visa"
  },
  "paymentAccountReference": "512381d9f8e0629211e3949a08002",
  "tokenRequestorIdentifier": "40020248564",
  "tokenServiceProvider": "vts",
  "merchant": "merchant_ddsaJsda9d86",
  "status": "active",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Delete a Network Token

Deletes a Network Token by its unique identifier.

Parameters

network_token_idRequiredstring
The unique identifier of the Network Token.

1curl 'https://api.evervault.com/payments/network-tokens/{network_token_id}' \
2  --request DELETE \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Create a Cryptogram

Creates a Network Token Cryptogram.

Parameters

network_token_idRequiredstring
The unique identifier of the Network Token.

Response Body

idRequiredstring
A unique identifier representing a specific Network Token Cryptogram.
cryptogramRequiredstring
The value of the Network Token Cryptogram. This is the value that is used embedded in the Authorization request.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Network Token Cryptogram was created.

1curl 'https://api.evervault.com/payments/network-tokens/{network_token_id}/cryptograms' \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'

Response

{
  "id": "network_token_cryptogram_eead1d640d7c",
  "cryptogram": "NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE=",
  "createdAt": 1692972623233
}

Simulate a Network Token Update

Simulates an update to a Network Token so that you can test your integration. Sandbox only.

Parameters

network_token_idRequiredstring
The id of the Network Token

Request Body

updateTypestring
The type of update to simulate.
Can be one of deactivate-token, new-card-expiry-and-last-four, new-token-expiry-and-number

Response Body

idRequiredstring
A unique identifier representing a specific Network Token.
numberRequiredstring
The unique number of the Network Token.
expiryRequiredobject
The expiry details of the Network Token.
cardRequiredobject
The details of the underlying encrypted card.
tokenRequestorIdentifierRequiredstring
The identifier of the Token Requestor (TRID) that requested the Network Token.
tokenServiceProviderRequiredstring
The Token Service Provider (TSP) that issued the Network Token.
Can be one of mdes, vts, aets
paymentAccountReferencestring
The unique identifier of the Payment Account associated with this Network Token.
statusRequiredstring
The status of the Network Token. Active means the Network Token is valid and can be used for payments.
Can be one of active, inactive
merchantRequiredstring
The unique identifier of the Merchant associated with this Network Token.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this Network Token was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this Network Token was last updated.

1curl 'https://api.evervault.com/payments/network-tokens/{network_token_id}/simulate' \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "updateType": "new-token-expiry-and-number"
7}'

Response

{
  "id": "network_token_eead1d640d7c",
  "number": "4498004918463434",
  "expiry": {
    "month": "13",
    "year": "25"
  },
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "09",
      "year": "26"
    },
    "brand": "visa"
  },
  "paymentAccountReference": "512381d9f8e0629211e3949a08002",
  "tokenRequestorIdentifier": "40020248564",
  "tokenServiceProvider": "vts",
  "merchant": "merchant_ddsaJsda9d86",
  "status": "active",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Retrieve Card Art

Retrieves the card art for a Network Token by its unique identifier.

Parameters

network_token_idRequiredstring
The unique identifier of the Network Token.

Response Body

typeRequiredstring
The MIME type of the card art image.
dataRequiredstring
The base64-encoded image data of the card art.
widthRequiredinteger
The width of the card art image in pixels.
heightRequiredinteger
The height of the card art image in pixels.

1curl 'https://api.evervault.com/payments/network-tokens/{network_token_id}/card-art' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "type": "image/png",
  "data": "dGhlIGJhc2U2NCBlbmNvZGVkIGltYWdlIGRhdGE=",
  "width": 1536,
  "height": 969
}

3D Secure

3D Secure is a security protocol designed to prevent fraud in online card transactions. It adds an additional layer of authentication during the payment process.

Endpoints

post/payments/3ds-sessionsCreate a 3DS Session
get/payments/3ds-sessions/:3ds_session_idRetrieve a 3DS Session

Create a 3DS Session

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

Request Body

merchantRequiredobject
The merchant details.
cardRequiredobject
The card details.
acquirerstring
The identifier of the acquirer configuration. See the Acquirers API for details.
customerobject
The details of the customer who initiated the transaction.
paymentobject
The payment details of the 3D-Secure Authentication. This field is mandatory for transactions involving payment authentications but not required for non-payment authentications.
preferredVersionsarray
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
challengeRequiredobject
Details about the 3DS challenge.
initiatorobject
Details about the transaction initiation process.

Response Body

The 3D Secure API can be used in combination with our [Client-Side SDK's](/sdks/javascript#uithreedsecure) to authenticate cardholders using 3D Secure. This API allows you to create, retrieve and update 3D Secure sessions.

idRequiredstring
A unique identifier assigned to each 3DS Authentication.
cardRequiredobject
acquirerRequiredobject
The acquirer of the payment.
merchantRequiredobject
The merchant details.
paymentobject
The payment details of the 3D-Secure Authentication.
challengeRequiredobject
Details about the 3DS challenge.
initiatorobject
Details about the transaction initiation process.
accessControlServerobject
Details about the Access Control Server involved in the 3DS transaction.
directoryServerobject
Details about the Directory Server involved in the 3DS transaction.
threeDSServerobject
Details about the 3DS Server involved in the 3DS transaction.
versionRequiredstring
The 3D-Secure version used to authenticate the session.
Can be one of 2.2.0
statusRequiredstring
The status of the 3DS Authentication.
Can be one of action-required, success, failure
authenticationRequiredobject
The details of the 3DS Authentication. This field is present when the status is success.
nextActionRequiredobject
The next action required to complete the 3DS Authentication.
cryptogramstring
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.
eciobject
The details of the Electronic Commerce Indicator. This value is only present when the status is success.
failureReasonstring
The reason for the 3DS Authentication failure. This field is present when the status is failure and can be used for troubleshooting. Below are descriptions of each of the possible values:
- failed-authentication: The authentication failed. Typically this is due to the cardholder failing to provide the correct 3DS authentication details. This transaction should be considered as potentially fraudulent.
- card-not-enrolled: The card is not enrolled in 3DS and therefore cannot be authenticated.
- suspected-fraud: The transaction is suspected to be fraudulent. You should not process this transaction.
- invalid-acquirer-details: The acquirer details are invalid. Please check the acquirer object for the correct details.
- transaction-cancelled-by-cardholder: The cardholder explicitly cancelled the transaction.
- unsupported-3ds-version: The 3DS version is not supported.
- challenge-required: This failure mode indicates that the cardholder is required to complete a challenge but the SDK has been mounted with the failOnChallenge option set to true.
- authentication-timed-out: The authentication timed out. This is likely because the cardholder abandoned the transaction.
- acs-unavailable: The Access Control Server associated with the card issuer was unavailable. Please try again later.
- directory-server-unavailable: The Directory Server associated with the card network was unavailable. Please try again later.
- transient-system-failure: A transient system failure occurred. This is likely due to a technical issue with the 3DS authentication process. Please try again later.
- invalid-card-details: The card details are invalid. Please check the card object for the correct details and ensure the card is not expired.
- transaction-not-permitted: The current session configuration is not permitted for this card. For example, defining a merchant intiated transaction reason of secure-corporate-payment for non-commercial cards.
- protocol-error: A protocol error occurred. This is likely due to a technical issue with the 3DS authentication process. Please try again later.
Can be one of failed-authentication, card-not-enrolled, suspected-fraud, invalid-acquirer-details, transaction-cancelled-by-cardholder, unsupported-3ds-version, challenge-required, authentication-timed-out, acs-unavailable, directory-server-unavailable, transient-system-failure, invalid-card-details, transaction-not-permitted, required-data-element-missing, protocol-error
aresobject
The details of the 3DS Authentication Response (ARes).
cresnull | object
The details of the 3DS Challenge Response (CRes).
rreqnull | object
The result of the 3DS authentication when a challenge has occurred.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this 3DS-Session was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this 3DS-Session was last updated.

1curl https://api.evervault.com/payments/3ds-sessions \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "merchant": {
7    "name": "Ollivanders Wand Shop",
8    "website": "https://www.ollivanders.co.uk",
9    "categoryCode": "5945",
10    "country": "gb"
11  },
12  "card": {
13    "number": "4242424242424242",
14    "expiry": {
15      "month": "09",
16      "year": "26"
17    }
18  },
19  "payment": {
20    "type": "one-off",
21    "amount": 1000,
22    "currency": "eur"
23  }
24}'

Response

{
  "id": "tds_57aa862f8bf7",
  "merchant": {
    "name": "Ollivanders Wand Shop",
    "website": "https://www.ollivanders.co.uk",
    "categoryCode": "5945",
    "country": "gb"
  },
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "09",
      "year": "26"
    },
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp"
  },
  "initiator": {
    "type": "customer"
  },
  "challenge": {
    "preference": "no-preference",
    "reason": null
  },
  "acquirer": {
    "bin": "567834",
    "merchantIdentifier": "530249576123943",
    "country": "gb"
  },
  "payment": {
    "type": "one-off",
    "amount": 1000,
    "currency": "eur"
  },
  "version": "2.2.0",
  "status": "action-required",
  "nextAction": {
    "type": "use-sdk"
  },
  "ares": {
    "transStatus": {
      "value": "C",
      "detail": "Challenge Required; Additional authentication is required using the CReq/CRes"
    },
    "transStatusReason": null
  },
  "cres": null,
  "rreq": null,
  "accessControlServer": {
    "transactionIdentifier": "0f651348-c519-4cfb-b349-0b302af9861f",
    "referenceNumber": "3DS_LOA_ACS_STIN_020200_00417"
  },
  "directoryServer": {
    "transactionIdentifier": "71c5d726-5d4b-426c-9d7d-131970f41c5c",
    "referenceNumber": "3DS_LOA_DIS_VISA_020200_00828",
    "network": "visa"
  },
  "threeDSServer": {
    "transactionIdentifier": "a623edc1-54bc-455d-9dea-c909783a37c3"
  },
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Retrieve a 3DS Session

Retrieve a 3DS Session.

Parameters

3ds_session_idRequiredstring
The id of the session

Response Body

idRequiredstring
A unique identifier assigned to each 3DS Authentication.
cardRequiredobject
acquirerRequiredobject
The acquirer of the payment.
merchantRequiredobject
The merchant details.
paymentobject
The payment details of the 3D-Secure Authentication.
challengeRequiredobject
Details about the 3DS challenge.
initiatorobject
Details about the transaction initiation process.
accessControlServerobject
Details about the Access Control Server involved in the 3DS transaction.
directoryServerobject
Details about the Directory Server involved in the 3DS transaction.
threeDSServerobject
Details about the 3DS Server involved in the 3DS transaction.
versionRequiredstring
The 3D-Secure version used to authenticate the session.
Can be one of 2.2.0
statusRequiredstring
The status of the 3DS Authentication.
Can be one of action-required, success, failure
authenticationRequiredobject
The details of the 3DS Authentication. This field is present when the status is success.
nextActionRequiredobject
The next action required to complete the 3DS Authentication.
cryptogramstring
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.
eciobject
The details of the Electronic Commerce Indicator. This value is only present when the status is success.
failureReasonstring
The reason for the 3DS Authentication failure. This field is present when the status is failure and can be used for troubleshooting. Below are descriptions of each of the possible values:
- failed-authentication: The authentication failed. Typically this is due to the cardholder failing to provide the correct 3DS authentication details. This transaction should be considered as potentially fraudulent.
- card-not-enrolled: The card is not enrolled in 3DS and therefore cannot be authenticated.
- suspected-fraud: The transaction is suspected to be fraudulent. You should not process this transaction.
- invalid-acquirer-details: The acquirer details are invalid. Please check the acquirer object for the correct details.
- transaction-cancelled-by-cardholder: The cardholder explicitly cancelled the transaction.
- unsupported-3ds-version: The 3DS version is not supported.
- challenge-required: This failure mode indicates that the cardholder is required to complete a challenge but the SDK has been mounted with the failOnChallenge option set to true.
- authentication-timed-out: The authentication timed out. This is likely because the cardholder abandoned the transaction.
- acs-unavailable: The Access Control Server associated with the card issuer was unavailable. Please try again later.
- directory-server-unavailable: The Directory Server associated with the card network was unavailable. Please try again later.
- transient-system-failure: A transient system failure occurred. This is likely due to a technical issue with the 3DS authentication process. Please try again later.
- invalid-card-details: The card details are invalid. Please check the card object for the correct details and ensure the card is not expired.
- transaction-not-permitted: The current session configuration is not permitted for this card. For example, defining a merchant intiated transaction reason of secure-corporate-payment for non-commercial cards.
- protocol-error: A protocol error occurred. This is likely due to a technical issue with the 3DS authentication process. Please try again later.
Can be one of failed-authentication, card-not-enrolled, suspected-fraud, invalid-acquirer-details, transaction-cancelled-by-cardholder, unsupported-3ds-version, challenge-required, authentication-timed-out, acs-unavailable, directory-server-unavailable, transient-system-failure, invalid-card-details, transaction-not-permitted, required-data-element-missing, protocol-error
aresobject
The details of the 3DS Authentication Response (ARes).
cresnull | object
The details of the 3DS Challenge Response (CRes).
rreqnull | object
The result of the 3DS authentication when a challenge has occurred.
createdAtRequiredinteger
The exact time, in epoch milliseconds, when this 3DS-Session was created.
updatedAtinteger
The exact time, in epoch milliseconds, when this 3DS-Session was last updated.

1curl 'https://api.evervault.com/payments/3ds-sessions/{3ds_session_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "tds_57aa862f8bf7",
  "merchant": {
    "name": "Ollivanders Wand Shop",
    "website": "https://www.ollivanders.co.uk",
    "categoryCode": "5945",
    "country": "gb"
  },
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "09",
      "year": "26"
    },
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "country": "gb",
    "currency": "gbp"
  },
  "initiator": {
    "type": "customer"
  },
  "challenge": {
    "preference": "no-preference",
    "reason": null
  },
  "acquirer": {
    "bin": "567834",
    "merchantIdentifier": "530249576123943",
    "country": "gb"
  },
  "payment": {
    "type": "one-off",
    "amount": 1000,
    "currency": "eur"
  },
  "version": "2.2.0",
  "status": "action-required",
  "nextAction": {
    "type": "use-sdk"
  },
  "threeDSServer": {
    "transactionIdentifier": "a623edc1-54bc-455d-9dea-c909783a37c3"
  },
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Card Account Updates

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.

Endpoints

post/payments/cardsRegister a Card
get/payments/cards/:card_idRetrieve a Card
delete/payments/cards/:card_idDelete a Card
post/payments/cards/:card_id/simulateSimulate a Card Update

Register a Card

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.

Request Body

numberRequiredstring
The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.
expiryRequiredobject

Response Body

idstring
The unique identifier for the card.
numberRequiredstring
The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
expiryRequiredobject
The expiry date of the card.
binRequiredstring
The first 6 or 8 digits of the card number.
lastFourRequiredstring
The last 4 digits of the card number.
brandstring
The card brand associated with the payment card.
Can be one of visa, mastercard, american-express, discover, diners-club, jcb, unionpay
fundingstring
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.
Can be one of debit, credit, prepaid, deferred-debit, charge
segmentstring
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.
Can be one of consumer, commercial, business, government, payouts, all
countrystring
The country where the card was issued in lowercase ISO 3166-1 alpha-2 format.
currencystring
The currency of the card in lowercase ISO 4217 format.
issuerstring
The name of the card issuer.
statusstring
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.
Can be one of active, replaced, closed, invalid
replacementstring | null
The ID of the replacement card. This field is only present if the card has been replaced.
automaticUpdatesstring
The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
Can be one of enabled, issuer-not-enrolled, cardholder-opted-out, disabled
createdAtRequiredinteger
The Unix timestamp of when the card was created.
updatedAtinteger | null
The Unix timestamp of when the card was last updated.

1curl https://api.evervault.com/payments/cards \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
7  "expiry": {
8    "month": "09",
9    "year": "26"
10  }
11}'

Response

{
  "id": "card_eead1d640d7c",
  "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
  "expiry": {
    "month": "09",
    "year": "26"
  },
  "bin": "424242",
  "lastFour": "4242",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "status": "active",
  "replacement": null,
  "automaticUpdates": "enabled",
  "createdAt": 169297262323,
  "updatedAt": null
}

Retrieve a Card

Retrieves a Card by its unique identifier.

Parameters

card_idRequiredstring
The unique identifier of the Card.

Response Body

idstring
The unique identifier for the card.
numberRequiredstring
The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
expiryRequiredobject
The expiry date of the card.
binRequiredstring
The first 6 or 8 digits of the card number.
lastFourRequiredstring
The last 4 digits of the card number.
brandstring
The card brand associated with the payment card.
Can be one of visa, mastercard, american-express, discover, diners-club, jcb, unionpay
fundingstring
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.
Can be one of debit, credit, prepaid, deferred-debit, charge
segmentstring
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.
Can be one of consumer, commercial, business, government, payouts, all
countrystring
The country where the card was issued in lowercase ISO 3166-1 alpha-2 format.
currencystring
The currency of the card in lowercase ISO 4217 format.
issuerstring
The name of the card issuer.
statusstring
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.
Can be one of active, replaced, closed, invalid
replacementstring | null
The ID of the replacement card. This field is only present if the card has been replaced.
automaticUpdatesstring
The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
Can be one of enabled, issuer-not-enrolled, cardholder-opted-out, disabled
createdAtRequiredinteger
The Unix timestamp of when the card was created.
updatedAtinteger | null
The Unix timestamp of when the card was last updated.

1curl 'https://api.evervault.com/payments/cards/{card_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "card_eead1d640d7c",
  "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
  "expiry": {
    "month": "09",
    "year": "26"
  },
  "bin": "424242",
  "lastFour": "4242",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "status": "active",
  "replacement": null,
  "automaticUpdates": "enabled",
  "createdAt": 169297262323,
  "updatedAt": null
}

Delete a Card

Deletes a Card by its unique identifier.

Parameters

card_idRequiredstring
The unique identifier of the Card.

Simulate a Card Update

Simulates an update to a Card so that you can test your Card Account Updater integration. This endpoint is only available for Sandbox Apps.

Parameters

card_idRequiredstring
The id of the Card

Request Body

The request body for simulating a card update differs depending on the type of event you want to simulate.

Response Body

idstring
The unique identifier for the card.
numberRequiredstring
The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
expiryRequiredobject
The expiry date of the card.
binRequiredstring
The first 6 or 8 digits of the card number.
lastFourRequiredstring
The last 4 digits of the card number.
brandstring
The card brand associated with the payment card.
Can be one of visa, mastercard, american-express, discover, diners-club, jcb, unionpay
fundingstring
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.
Can be one of debit, credit, prepaid, deferred-debit, charge
segmentstring
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.
Can be one of consumer, commercial, business, government, payouts, all
countrystring
The country where the card was issued in lowercase ISO 3166-1 alpha-2 format.
currencystring
The currency of the card in lowercase ISO 4217 format.
issuerstring
The name of the card issuer.
statusstring
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.
Can be one of active, replaced, closed, invalid
replacementstring | null
The ID of the replacement card. This field is only present if the card has been replaced.
automaticUpdatesstring
The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
Can be one of enabled, issuer-not-enrolled, cardholder-opted-out, disabled
createdAtRequiredinteger
The Unix timestamp of when the card was created.
updatedAtinteger | null
The Unix timestamp of when the card was last updated.

1curl 'https://api.evervault.com/payments/cards/{card_id}/simulate' \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "updateType": "new-account-number",
7  "number": "4242424242424242",
8  "expiry": {
9    "month": "09",
10    "year": "26"
11  }
12}'

Response

{
  "id": "card_eead1d640d7c",
  "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
  "expiry": {
    "month": "09",
    "year": "26"
  },
  "bin": "424242",
  "lastFour": "4242",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "status": "replaced",
  "replacement": "card_eead1d640d7c",
  "automaticUpdates": "enabled",
  "createdAt": 169297262323,
  "updatedAt": 169297262376
}

Webhook Events

Webhook Events are notifications triggered by specific operations to which you can subscribe, allowing you to be alerted when those operations occur. These events might include scenarios such as a Network Token being updated, a successful 3DS session, or the completion of a function deployment. Each event is categorized by a type that defines the nature of the event, along with associated data relevant to that event.

Create a Webhook Endpoint

Request Body

urlRequiredstring
The URL of the Webhook Endpoint.
eventsRequiredarray
A list of Events that the Webhook Endpoint is subscribed to. The following events are supported:
- payments.merchant.updated: A Merchant was updated
- payments.network-token.updated: A Network Token was updated
- function.run.completed: An asynchronous Function Run was completed

Response Body

idstring
A unique identifier representing a specific Webhook Endpoint.
urlstring
The URL of the Webhook Endpoint.
eventsarray
A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
createdAtinteger
The exact time, in epoch milliseconds, when this Webhook Endpoint was created.
updatedAtinteger | null
The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

1curl https://api.evervault.com/webhook-endpoints \
2  --request POST \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "url": "https://example.com/webhook",
7  "events": [
8    "payments.merchant.updated",
9    "payments.networkToken.updated"
10  ]
11}'

Response

{
  "id": "webhook_endpoint_eead1d640d7c",
  "url": "https://example.com/webhook",
  "events": [
    "payments.merchant.updated",
    "payments.network-token.updated"
  ],
  "createdAt": 169297262323,
  "updatedAt": null
}

List all Webhook Endpoints

Lists all Webhook Endpoints

Parameters

limitinteger
The maximum number of Webhook Endpoints to return (Default is 10).
startingAfterstring
The identifier of the last Webhook Endpoint in the previous page of results.

Response Body

dataarray
hasMoreboolean
Indicates whether there are more Webhook Endpoints to retrieve.

1curl https://api.evervault.com/webhook-endpoints \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "data": [
    {
      "id": "webhook_endpoint_eead1d640d7c",
      "url": "https://example.com/webhook",
      "events": [
        "payments.merchant.updated",
        "payments.network-token.updated"
      ],
      "createdAt": 169297262323,
      "updatedAt": null
    }
  ],
  "hasMore": true
}

Retrieve a Webhook Endpoint

Retrieves a Webhook Endpoint

Parameters

webhook_endpoint_idRequiredstring
The identifier of the Webhook Endpoint to retrieve.

Response Body

idstring
A unique identifier representing a specific Webhook Endpoint.
urlstring
The URL of the Webhook Endpoint.
eventsarray
A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
createdAtinteger
The exact time, in epoch milliseconds, when this Webhook Endpoint was created.
updatedAtinteger | null
The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

1curl 'https://api.evervault.com/webhook-endpoints/{webhook_endpoint_id}' \
2  --user 'app_id:api_key' \
3  --header 'Content-Type: application/json'

Response

{
  "id": "webhook_endpoint_eead1d640d7c",
  "url": "https://example.com/webhook",
  "events": [
    "payments.merchant.updated",
    "payments.network-token.updated"
  ],
  "createdAt": 169297262323,
  "updatedAt": null
}

Update a Webhook Endpoint

Updates a Webhook Endpoint

Parameters

webhook_endpoint_idRequiredstring
The identifier of the Webhook Endpoint to update.

Request Body

eventsRequiredarray
A list of Events that the Webhook Endpoint is subscribed to. The following events are supported:
- *: All Events
- payments.merchant.updated: A Merchant was updated
- payments.network-token.updated: A Network Token was updated
- function.run.completed: An asynchronous Function Run was completed

Response Body

idstring
A unique identifier representing a specific Webhook Endpoint.
urlstring
The URL of the Webhook Endpoint.
eventsarray
A list of Events that the Webhook Endpoint is subscribed to. The Webhook will receive a POST request when any of these Events occur.
createdAtinteger
The exact time, in epoch milliseconds, when this Webhook Endpoint was created.
updatedAtinteger | null
The exact time, in epoch milliseconds, when this Webhook Endpoint was last updated.

1curl 'https://api.evervault.com/webhook-endpoints/{webhook_endpoint_id}' \
2  --request PATCH \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "events": [
7    "merchant.updated"
8  ]
9}'

Response

{
  "id": "webhook_endpoint_eead1d640d7c",
  "url": "https://example.com/webhook",
  "events": [
    "payments.merchant.updated"
  ],
  "createdAt": 169297262323,
  "updatedAt": 169297269867
}

Delete a Webhook Endpoint

Parameters

webhook_endpoint_idRequiredstring
The identifier of the Webhook Endpoint to delete.

1curl 'https://api.evervault.com/webhook-endpoints/{webhook_endpoint_id}' \
2  --request DELETE \
3  --user 'app_id:api_key' \
4  --header 'Content-Type: application/json'