Evervault Network Tokens API
The Network Tokens API from Evervault — 5 operation(s) for network tokens.
OpenAPI Specification
openapi: 3.1.0
info:
title: Evervault Network Tokens API
version: 0.0.1
description: The Evervault API allows developers to interact programmatically with their Evervault apps using HTTP requests.
contact:
email: support@evervault.com
name: Evervault Support Team
url: https://evervault.com
servers:
- url: https://api.evervault.com
description: The Evervault API server
tags:
- name: Network Tokens
paths:
/payments/network-tokens:
post:
x-section: Payments
x-group: Network Tokens
summary: Create a Network Token
description: 'Create a Network Token for a given card.
'
operationId: createNetworkToken
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
card:
description: The card to tokenize. Either an inline card object or the unique identifier of a Card created with the [Cards API](/api#cards).
oneOf:
- type: object
description: An inline card object.
properties:
number:
type: string
description: The card number. Needs to be an Evervault-encrypted card number or a plaintext card number.
example: '4242424242424242'
expiry:
allOf:
- $ref: '#/components/schemas/CardExpiry'
description: The card expiry date. The expiry must be in the current month or later. Expired cards are rejected before tokenization.
cvc:
type: string
description: The card security code. Needs to be an Evervault-encrypted CVV or a plaintext CVV.
example: '123'
required:
- number
- expiry
- type: string
description: The unique identifier of a Card created with the [Cards API](/api#cards).
example: card_eead1d640d7c
merchant:
type: string
description: 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.
example: merchant_ddsaJsda9d86
required:
- card
- merchant
examples:
EvervaultEncryptedExample:
value:
card:
number: ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$
expiry:
month: 09
year: '26'
cvc: ev:debug:Tk9D:number:2GW8Nk96yfb2UXcw:A4UOUDGNb16Q//uBYVPibmfJ2734IrvPAoVY+8PvGG0C:5jtAu8KN1HiPeCNqSDCKMapfpg==:$
merchant: merchant_ddsaJsda9d86
PlaintextCardExample:
value:
card:
number: '4242424242424242'
expiry:
month: 09
year: '26'
cvc: '123'
merchant: merchant_ddsaJsda9d86
responses:
'201':
description: Returns a Network Token object.
x-content: 'Returns the [Network Token object](#the-network-token-object) that was created.
'
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkToken'
examples:
EvervaultEncryptedExample:
summary: Network Token created with encrypted card details
value:
id: network_token_eead1d640d7c
number: '4498004918463434'
expiry:
month: '13'
year: '25'
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
country: us
currency: usd
funding: debit
segment: consumer
issuer: Gringotts Wizarding Bank and Trust Company
paymentAccountReference: 512381d9f8e0629211e3949a08002
tokenRequestorIdentifier: '40020248564'
tokenServiceProvider: vts
merchant: merchant_ddsaJsda9d86
status: active
createdAt: 1692972623233
updatedAt: 1692972623768
PlaintextCardExample:
summary: Network Token created with plaintext card details
value:
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
'400':
description: 'The request was invalid or cannot be otherwise served.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
IneligibleCard:
summary: Ineligible Card
value:
code: payments/network-tokens/ineligible-card
title: Ineligible Card
detail: The card is not eligible for tokenization. This may be due to the card issuer not supporting tokenization.
InvalidCard:
summary: Ineligible Card
value:
code: payments/network-tokens/invalid-card
title: Invalid Card
detail: The provided card details did not pass verification checks. This may be due to an invalid card number, an incorrect CVC, or a discrepancy between the provided and actual card expiry date.
ExpiredCard:
summary: Expired Card
value:
code: payments/network-tokens/expired-card
title: Expired Card
detail: The card has expired.
DeclinedTokenization:
summary: Declined Tokenization
value:
code: payments/network-tokens/declined-tokenization
title: Declined Tokenization
detail: Tokenization for the given card was declined by the card issuer. This may be due to restrictions related to the card type, issuer policies, or the card's current status
'422':
description: 'Unprocessable Entity
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantNotReady:
summary: Merchant Not Ready
value:
code: payments/network-tokens/merchant-not-ready
title: Merchant Not Ready
detail: The merchant is not yet ready for tokenizing cards. Enrolling a merchant for network tokenization can take up to 48 hours. Please try again later.
TokenServiceProviderProvisioning:
summary: Token Service Provider Provisioning
value:
code: payments/network-tokens/token-service-provider-provisioning
title: Token Service Provider Provisioning
detail: The Token Service Provider is currently provisioning. This may take up to 48 hours to complete. Please try again later. Contact support@evervault.com if this continues after 48 hours.
'500':
description: 'An error occurred while processing the request.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnavailableTokenServiceProvider:
summary: Unavailable Token Service Provider
value:
code: payments/network-tokens/unavailable-token-service-provider
title: Unavailable Token Service Provider
detail: The Token Service Provider is unavailable. Please try again later.
/payments/network-tokens/{network_token_id}:
get:
x-section: Payments
x-group: Network Tokens
summary: Retrieve a Network Token
description: 'Retrieves a Network Token by its unique identifier.
'
operationId: getNetworkToken
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:read
parameters:
- name: network_token_id
in: path
description: The unique identifier of the Network Token.
required: true
schema:
type: string
responses:
'200':
description: Returns a Network Token object.
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkToken'
examples:
SuccessfulRetrieval:
summary: Successful Retrieval
value:
id: network_token_eead1d640d7c
number: '4498004918463434'
expiry:
month: '13'
year: '25'
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
country: us
currency: usd
funding: debit
segment: consumer
issuer: Gringotts Wizarding Bank and Trust Company
paymentAccountReference: 512381d9f8e0629211e3949a08002
tokenRequestorIdentifier: '40020248564'
tokenServiceProvider: vts
merchant: merchant_ddsaJsda9d86
status: active
createdAt: 1692972623233
updatedAt: 1692972623768
delete:
x-section: Payments
x-group: Network Tokens
summary: Delete a Network Token
description: 'Deletes a Network Token by its unique identifier.
'
operationId: deleteNetworkToken
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:delete
parameters:
- name: network_token_id
in: path
description: The unique identifier of the Network Token.
required: true
schema:
type: string
responses:
'204':
description: Deletes a Network Token object.
content:
application/json:
examples:
SuccessfulDeletion:
summary: Network Token successfully deleted
value: {}
/payments/network-tokens/{network_token_id}/cryptograms:
post:
x-section: Payments
x-group: Network Tokens
summary: Create a Cryptogram
description: 'Creates a Network Token Cryptogram.
'
operationId: createNetworkTokenCryptogram
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:createCryptogram
parameters:
- name: network_token_id
in: path
description: The unique identifier of the Network Token.
required: true
schema:
type: string
responses:
'201':
description: Returns a Network Token Cryptogram object.
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTokenCryptogram'
examples:
SuccessfulCreation:
summary: Network Token Cryptogram created
value:
id: network_token_cryptogram_eead1d640d7c
cryptogram: NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE=
createdAt: 1692972623233
/payments/network-tokens/{network_token_id}/simulate:
post:
x-section: Payments
x-group: Network Tokens
summary: Simulate a Network Token Update
description: 'Simulates an update to a Network Token so that you can test your integration. Sandbox only.
'
operationId: simulateNetworkTokenUpdate
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:create
parameters:
- name: network_token_id
in: path
description: The id of the Network Token
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
updateType:
type: string
description: The type of update to simulate.
enum:
- new-token-status
- new-card-expiry-and-last-four
- new-token-expiry-and-number
examples:
NewTokenExpiryAndNumberExample:
value:
updateType: new-token-expiry-and-number
NewCardExpiryAndLastFourExample:
value:
updateType: new-card-expiry-and-last-four
NewTokenStatusExample:
value:
updateType: new-token-status
responses:
'200':
description: Returns the updated Network Token object.
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkToken'
examples:
NewTokenExpiryAndNumberExample:
summary: New token expiry and number
value:
id: network_token_eead1d640d7c
number: '4498004918463434'
expiry:
month: '13'
year: '25'
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
country: us
currency: usd
funding: debit
segment: consumer
issuer: Gringotts Wizarding Bank and Trust Company
paymentAccountReference: 512381d9f8e0629211e3949a08002
tokenRequestorIdentifier: '40020248564'
tokenServiceProvider: vts
merchant: merchant_ddsaJsda9d86
status: active
createdAt: 1692972623233
updatedAt: 1692972623768
NewCardExpiryAndLastFourExample:
summary: New card expiry and last four
value:
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
DeactivateTokenExample:
summary: Inactive token
value:
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: inactive
createdAt: 1692972623233
updatedAt: 1692972623768
/payments/network-tokens/{network_token_id}/card-art:
get:
summary: Retrieve Card Art
description: 'Retrieves the card art for a Network Token by its unique identifier.
'
operationId: getCardArt
tags:
- Network Tokens
security:
- ApiKey:
- networkToken:read
parameters:
- name: network_token_id
in: path
description: The unique identifier of the Network Token.
required: true
schema:
type: string
responses:
'200':
description: Returns the card art for the Network Token.
content:
application/json:
schema:
$ref: '#/components/schemas/CardArt'
examples:
SuccessfulRetrieval:
summary: Successful Retrieval
value:
type: image/png
data: dGhlIGJhc2U2NCBlbmNvZGVkIGltYWdlIGRhdGE=
width: 1536
height: 969
components:
schemas:
CardArt:
type: object
properties:
type:
type: string
description: The MIME type of the card art image.
example: image/png
data:
type: string
description: The base64-encoded image data of the card art.
example: dGhlIGJhc2U2NCBlbmNvZGVkIGltYWdlIGRhdGE=
width:
type: integer
description: The width of the card art image in pixels.
example: 1536
height:
type: integer
description: The height of the card art image in pixels.
example: 969
required:
- type
- data
- width
- height
NetworkTokenCryptogram:
type: object
properties:
id:
type: string
description: A unique identifier representing a specific Network Token Cryptogram.
example: network_token_cryptogram_eead1d640d7c
cryptogram:
type: string
description: The value of the Network Token Cryptogram. This is the value that is used embedded in the Authorization request.
example: NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE=
createdAt:
type: integer
format: int64
description: The exact time, in epoch milliseconds, when this Network Token Cryptogram was created.
example: 1692972623233
required:
- id
- cryptogram
- createdAt
Error:
type: object
properties:
code:
type: string
description: A distinct error code, presented in slug format, that identifies a specific error.
example: invalid-request
title:
type: string
description: A short, human-readable summary of the error.
example: Invalid Request
status:
type: integer
description: The HTTP status code for the error.
example: 400
detail:
type: string
description: A human-readable explanation of the error.
example: The provided action was invalid
fields:
type: array
items:
type: object
properties:
pointer:
type: string
description: The JSON pointer to the field that caused the error.
example: /card/number
reason:
type: string
description: A human-readable explanation of the error for this field.
example: The card number is required
example:
- pointer: /card/number
reason: The card number is required
NetworkToken:
summary: The Network Token Object
type: object
properties:
id:
type: string
description: A unique identifier representing a specific Network Token.
example: network_token_eead1d640d7c
number:
type: string
description: The unique number of the Network Token.
example: '4545454545454545'
expiry:
type: object
description: The expiry details of the Network Token.
properties:
month:
type: string
description: The month of the Network Token's expiry date, in MM format (e.g. 12 for December)
example: '12'
year:
type: string
description: The year of the Network Token's expiry date, in YY format (e.g. 26 for 2026)
example: '23'
card:
type: object
description: The details of the underlying encrypted card.
properties:
lastFour:
type: string
description: The last four digits of the card number.
example: '4545'
expiry:
type: object
description: The expiry details of the card.
properties:
month:
type: string
description: The month of the card's expiry date, in MM format (e.g. 12 for December)
example: '12'
year:
type: string
description: The year of the card's expiry date, in YY format (e.g. 26 for 2026)
example: '23'
brand:
type: string
enum:
- visa
- mastercard
- american-express
description: The card brand associated with the payment card.
example: visa
tokenRequestorIdentifier:
type: string
description: The identifier of the Token Requestor (TRID) that requested the Network Token.
example: '50165156978'
tokenServiceProvider:
type: string
description: The Token Service Provider (TSP) that issued the Network Token.
enum:
- mdes
- vts
- aets
paymentAccountReference:
type: string
description: The unique identifier of the Payment Account associated with this Network Token.
example: 512381d9f8e0629211e3949a08002
status:
type: string
enum:
- active
- inactive
- blocked
- provisioning
- suspended
- deleted
- expired
description: The status of the Network Token. Active means the token is valid and can be used for payments. Inactive means the token exists but is not currently active. Blocked and provisioning are reserved for future use. Suspended means the token is temporarily unusable but may be reactivated by the issuer or transition to deleted. Deleted is a terminal state where the token is permanently removed and a new credential must be obtained. Expired means the token has passed its expiration date and should not be used for transactions.
example: active
merchant:
type: string
description: The unique identifier of the Merchant associated with this Network Token.
example: merchant_eead1d640d7c
createdAt:
type: integer
format: int64
description: The exact time, in epoch milliseconds, when this Network Token was created.
example: 1692972623233
updatedAt:
type: integer
format: int64
description: The exact time, in epoch milliseconds, when this Network Token was last updated.
example: 1692972623768
required:
- id
- number
- expiry
- card
- tokenRequestorIdentifier
- tokenServiceProvider
- status
- merchant
- createdAt
example:
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
CardExpiry:
type: object
properties:
month:
type: string
description: The card expiry month, in MM format (e.g. 12 for December)
example: 09
year:
type: string
description: The card expiry year, in YY format (e.g. 26 for 2026)
example: '26'
required:
- month
- year
securitySchemes:
ApiKey:
type: http
scheme: basic
description: Authentication using an API key. The username is the App ID and the password is the Api Key.
TokenAuth:
type: http
scheme: bearer
bearerFormat: RunToken
description: 'Authentication using a short lived run token that you can share with clients. The Authorization header must be formatted as follow: "RunToken <Function Run Token>"'
ClientSideToken:
type: http
scheme: bearer
bearerFormat: Token
description: 'Authentication using a short lived token that you can share with clients. The Authorization header must be formatted as follow: "Token <Client-Side Token>"'