If your account has access to [Card Account Updater](/cards/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.
openapi: 3.1.0
info:
title: Evervault Card Account Updates 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: Card Account Updates
description: 'If your account has access to [Card Account Updater](/cards/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.
'
paths:
/payments/cards:
post:
summary: Register a Card
description: '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. Registering the same card number a second time returns the existing Card object, rather than creating a new one. This means you can use the Card object `id` as a unique identifier. If you register an existing card number but with a different expiry date, the existing Card object is updated with the new date, and Evervault returns a `200 OK` response. A `201 Created` response indicates that a new Card object was created.
'
operationId: registerCard
tags:
- Card Account Updates
security:
- ApiKey:
- card:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
number:
type: string
description: The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.
example: '4242424242424242'
expiry:
$ref: '#/components/schemas/CardExpiry'
required:
- number
- expiry
examples:
EvervaultEncryptedExample:
value:
number: ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$
expiry:
month: 09
year: '26'
PlaintextCardExample:
value:
number: '4242424242424242'
expiry:
month: 09
year: '26'
responses:
'200':
description: Returns an existing Card object. If the card number is already registered but with a different expiry date, the date is updated to the value in the request before the Card object is returned.
x-content: 'Returns the [Card object](#the-card-object) that was created.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
examples:
SuccessfulCreation:
summary: Card successfully created
value:
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
'201':
description: Returns a new Card object.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
examples:
SuccessfulCreation:
summary: Card successfully created
value:
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
/payments/cards/{card_id}:
get:
summary: Retrieve a Card
description: 'Retrieves a Card by its unique identifier.
'
operationId: getCard
tags:
- Card Account Updates
security:
- ApiKey:
- card:read
parameters:
- name: card_id
in: path
description: The unique identifier of the Card.
required: true
schema:
type: string
responses:
'200':
description: Returns an existing Card object.
x-content: 'Returns the [Card object](#the-card-object).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
examples:
SuccessfulCreation:
summary: Card successfully created
value:
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:
summary: Delete a Card
description: 'Deletes a Card by its unique identifier.
'
operationId: deleteCard
tags:
- Card Account Updates
security:
- ApiKey:
- card:delete
parameters:
- name: card_id
in: path
description: The unique identifier of the Card.
required: true
schema:
type: string
responses:
'204':
description: Deletes a Card object.
content:
application/json:
examples:
SuccessfulDeletion:
summary: Card successfully deleted
value: {}
/payments/cards/{card_id}/simulate:
post:
summary: Simulate a Card Update
description: 'Simulates an update to a Card so that you can test your Card Account Updater integration. This endpoint is only available for [Sandbox Apps](/developers/sandbox).
'
operationId: simulateCardUpdate
tags:
- Card Account Updates
security:
- ApiKey:
- card:create
parameters:
- name: card_id
in: path
description: The id of the Card
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The request body for simulating a card update differs depending on the type of event you want to simulate.
oneOf:
- $ref: '#/components/schemas/CauNanUpdate'
- $ref: '#/components/schemas/CauNedUpdate'
- $ref: '#/components/schemas/CauAclUpdate'
examples:
NewAccountNumberExample:
value:
updateType: new-account-number
number: '4242424242424242'
expiry:
month: 09
year: '26'
NewExpiryDateExample:
value:
updateType: new-expiry-date
expiry:
month: 09
year: '26'
AccountClosureExample:
value:
updateType: account-closure
responses:
'200':
description: Returns the updated Card object.
x-content: 'Returns the [Card object](#the-card-object).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
examples:
NewAccountNumberExample:
summary: New account number
value:
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
NewExpiryDateExample:
summary: New expiry date
value:
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
AccountClosureExample:
summary: Account closure
value:
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: closed
replacement: null
automaticUpdates: enabled
createdAt: 169297262323
updatedAt: 169297262376
components:
schemas:
CauNedUpdate:
type: object
description: New expiry date
properties:
updateType:
type: string
description: The type of update to simulate.
enum:
- new-expiry-date
expiry:
$ref: '#/components/schemas/CardExpiry'
required:
- updateType
CardSegment:
type: string
enum:
- consumer
- commercial
- business
- government
- payouts
- all
x-enum-description:
consumer: Personal use cards
commercial: Cards used by large organizations or corporations
business: Small to medium-sized business use
government: Cards used by government entities
payouts: Cards designed to disburse payments like payroll or cashback
all: General-purpose cards not confined to a specific segment
description: 'The card segment indicates the primary market or usage category of the
card.
'
example: consumer
CauAclUpdate:
type: object
description: Account closure
properties:
updateType:
type: string
description: The type of update to simulate.
enum:
- account-closure
required:
- updateType
CauNanUpdate:
type: object
description: New account number
properties:
updateType:
type: string
description: The type of update to simulate.
enum:
- new-account-number
expiry:
$ref: '#/components/schemas/CardExpiry'
number:
type: string
description: The card number. Can be clear-text or an Evervault encrypted string.
example: '4242424242424242'
required:
- updateType
CardFunding:
type: string
enum:
- debit
- credit
- prepaid
- deferred-debit
- charge
x-enum-description:
debit: Draw funds directly from a linked bank account
credit: Provide a line of credit from which users can borrow funds for transactions
prepaid: Loaded with a set amount of funds in advance and can be used until the balance is depleted
deferred-debit: Combine aspects of debit and credit cards, allowing transactions to be debited from a linked account at a later date, usually monthly
charge: Require full payment of the balance at the end of each billing cycle, but do not have a pre-set spending limit
description: 'The card funding type specifies the method by which transactions are
financed.
'
example: debit
Card:
x-section: Payments
x-group: Cards
type: object
summary: The Card Object
properties:
id:
type: string
description: The unique identifier for the card.
example: card_eead1d640d7c
number:
type: string
description: The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
example: 'ev:'
expiry:
$ref: '#/components/schemas/CardExpiry'
description: The expiry date of the card.
bin:
type: string
description: The first 6 or 8 digits of the card number.
example: '424242'
lastFour:
type: string
description: The last 4 digits of the card number.
example: '4242'
brand:
$ref: '#/components/schemas/CardBrand'
funding:
$ref: '#/components/schemas/CardFunding'
segment:
$ref: '#/components/schemas/CardSegment'
country:
type: string
format: iso-3166-1-alpha-2
description: The country where the card was issued.
example: gb
currency:
type: string
format: iso-4217-alphabetic
description: The currency of the card.
example: gbp
issuer:
type: string
description: The name of the card issuer.
example: Gringotts Wizarding Bank and Trust Company
status:
type: string
description: The current status of the card.
enum:
- active
- replaced
- closed
- invalid
x-enum-description:
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.
example: active
replacement:
type:
- string
- 'null'
description: The ID of the replacement card. This field is only present if the card has been replaced.
example: card_eead1d640d7c
automaticUpdates:
type: string
description: 'The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
'
enum:
- enabled
- issuer-not-enrolled
- disabled
createdAt:
type: integer
description: The Unix timestamp of when the card was created.
example: 1692972623233
updatedAt:
type:
- integer
- 'null'
description: The Unix timestamp of when the card was last updated.
example: 1692972623768
required:
- number
- bin
- lastFour
- createdAt
example:
id: card_eead1d640d7c
number: ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$
expiry:
month: '9'
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
CardBrand:
type: string
enum:
- visa
- mastercard
- american-express
- discover
- diners-club
- jcb
- unionpay
description: The card brand associated with the payment card.
example: visa
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>"'