Evervault Payments API
The Payments API from Evervault — 17 operation(s) for payments.
OpenAPI Specification
openapi: 3.1.0
info:
title: Evervault Payments 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: Payments
x-category: true
paths:
/insights/cards:
post:
summary: Card Insights
description: '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.
'
operationId: createCardInsight
tags:
- Payments
security:
- ApiKey:
- insights:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
card:
type: object
description: The card details.
properties:
number:
type: string
description: The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.
example: '4111111111111111'
expiry:
type: object
description: The card expiry. Required if the `address`, `cardholder`, or `cvv` extensions are requested.
properties:
month:
type: string
description: The card expiry month
example: '12'
year:
type: string
description: The card expiry year
example: '29'
cvv:
type: string
description: The card security code. This should be a valid Evervault encrypted CVV or a valid plaintext CVV. Required if the `cvv` extension is requested.
example: '123'
required:
- number
extensions:
type: array
description: The extensions to the card insight request.
items:
type: string
description: The extensions
enum:
- capabilities
- cvv
- cardholder
- address
x-enum-description:
capabilities: Check the card's push and pull transaction capabilities
cvv: Check the card's CVV verification
cardholder: Check the cardholder's name verification
address: Check the cardholder's address verification
cardholder:
type: object
description: Details about the cardholder that the name verification (ANI) is for. Required if the `cardholder` extension is requested.
properties:
firstName:
type: string
description: The first name of the cardholder
example: John
lastName:
type: string
description: The last name of the cardholder
example: Doe
address:
type: object
description: Details about the cardholder's address that the address verification (AVS) is for. Required if the `address` extension is requested.
properties:
postalCode:
type: string
description: The ZIP or postal code.
example: '10001'
line1:
type: string
description: Street address line 1
example: 123 Main Street
line2:
type: string
description: Street address line 2
example: Apt 4B
city:
type: string
description: The city name
example: New York
state:
type: string
description: The state or province code. Required when `country` is `us`, `ca`, or `au`.
format: iso-3166-2-subdivision
example: ny
country:
type: string
description: The country code.
format: iso-3166-1-alpha-2
example: us
required:
- postalCode
required:
- card
examples:
SimpleExample:
value:
card:
number: '4111111111111111'
expiry:
month: 09
year: '29'
cvv: '123'
extensions:
- capabilities
- cvv
- address
- cardholder
cardholder:
firstName: John
lastName: Doe
address:
postalCode: '10001'
line1: 123 Main Street
line2: Apt 4B
city: New York
state: ny
country: us
responses:
'201':
description: Returns the Card Insight object
content:
application/json:
schema:
$ref: '#/components/schemas/CardInsight'
examples:
Success:
summary: Successful Card Insight createFunctionRun
value:
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: null
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
/payments/bin-lookups:
post:
summary: BIN Lookup
description: 'Performs a BIN lookup for the provided card number and retrieves associated information such as the card brand, country, issuer, and more.
'
operationId: createBinLookup
tags:
- Payments
security:
- ApiKey:
- binLookup:create
requestBody:
description: 'The BIN (Bank Identification Number) lookup request body, which includes the card number.
'
required: true
content:
application/json:
schema:
type: object
properties:
number:
type: string
description: '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.
'
required:
- number
examples:
BinLookupExample:
summary: Example BIN lookup request
value:
number: '4242424242424242'
responses:
'201':
description: Returns BIN details for the provided card number.
x-content: 'Returns the [BIN Lookup object](#the-bin-lookup-object) that was created.
'
content:
application/json:
schema:
$ref: '#/components/schemas/BinLookup'
examples:
SuccessfulLookup:
summary: Successful BIN lookup
value:
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
/payments/merchants:
post:
summary: Create a Merchant
description: '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
'
operationId: createMerchant
tags:
- Payments
security:
- ApiKey:
- merchant:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 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.
pattern: ^[a-zA-Z0-9 ]{1,60}$
example: Acme
shortName:
type: string
description: 'A shorter version of the Merchant''s name. Optional. When creating a 3D Secure session that references this Merchant by ID, `shortName` is used in place of `name` if `name` exceeds the 40-character limit imposed by the 3D Secure specification.
'
pattern: ^[a-zA-Z0-9 ]{1,40}$
example: Acme
website:
type: string
description: The official website URL of the Merchant. The domain must use a valid IANA top-level domain. See https://data.iana.org/TLD/tlds-alpha-by-domain.txt
example: https://www.acme.com
categoryCode:
type: string
description: The 4-digit Merchant Category Code (MCC).
example: '5945'
business:
type: object
description: The business details of the Merchant.
properties:
legalName:
type: string
description: The legal name under which the Merchant's business is registered.
pattern: ^[a-zA-Z0-9 ]{1,60}$
example: Acme Corp
address:
$ref: '#/components/schemas/Address'
description: The physical address of the Merchant's principal place of business.
required:
- legalName
- address
networkTokens:
type: object
description: 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).
properties:
enrolment:
type: array
items:
type: object
properties:
cardBrand:
type: string
description: The Card Brand for which the configuration belongs to.
example: mastercard
tokenRequestorIdentifier:
type:
- string
- 'null'
description: The existing Token Requestor ID assigned by the Card Brand.
example: '50165156978'
applePay:
type: object
description: The Merchant's Apple Pay configuration.
properties:
domains:
type: array
description: 'The domains the Merchant wants registered with Apple Pay. Only the domain name is required, without the protocol or path. For example, `example.com` is a valid domain, but `https://example.com` is not.
'
items:
type: string
example: ollivanders.co.uk
required:
- name
- website
- categoryCode
- business
examples:
SimpleExample:
value:
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
applePay:
domains:
- ollivanders.co.uk
responses:
'201':
description: Returns a Merchant object.
content:
application/json:
schema:
$ref: '#/components/schemas/Merchant'
examples:
SuccessfulCreation:
summary: Merchant successfully created
value:
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
get:
x-section: Payments
x-group: Merchants
summary: List Merchants
description: 'Lists all Merchants that have been created.
'
operationId: listMerchants
tags:
- Payments
security:
- ApiKey:
- merchant:read
parameters:
- name: page
in: query
description: The page number to retrieve.
required: false
schema:
type: integer
default: 0
- name: pageSize
in: query
description: The number of Merchants to retrieve per page (default is 50).
required: false
schema:
type: integer
default: 50
- name: q
in: query
description: Filter the Merchants by name.
required: false
schema:
type: string
responses:
'200':
description: Returns a list of Merchant objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Merchant'
pageSize:
type: integer
description: The number of Merchants retrieved per page.
nextPage:
type:
- integer
- 'null'
description: The next page number to retrieve. If there are no additional Merchants, this will be `null`.
total:
type: integer
description: The total count of all Merchants, after any filters.
required:
- data
- pageSize
- nextPage
- total
examples:
SuccessfulCreation:
summary: Successful List
description: The Merchants were retrieved successfully.
value:
data:
- 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
pageSize: 50
nextPage: null
total: 1
/payments/merchants/{merchant_id}:
get:
x-section: Payments
x-group: Merchants
summary: Retrieve a Merchant
description: 'Retrieves a Merchant by its unique identifier.
'
operationId: getMerchant
tags:
- Payments
security:
- ApiKey:
- merchant:read
parameters:
- name: merchant_id
in: path
description: The unique identifier of the merchant.
required: true
schema:
type: string
responses:
'200':
description: Returns a Merchant object.
content:
application/json:
schema:
$ref: '#/components/schemas/Merchant'
examples:
SuccessfulCreation:
summary: Merchant successfully created
value:
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
patch:
x-section: Payments
x-group: Merchants
summary: Update a Merchant
description: 'Updates a Merchant by its unique identifier.
'
operationId: updateMerchant
tags:
- Payments
security:
- ApiKey:
- merchant:update
parameters:
- name: merchant_id
in: path
description: The id of the Merchant to be updated.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
shortName:
type: string
description: 'A shorter version of the Merchant''s name. When creating a 3D Secure session that references this Merchant by ID, `shortName` is used in place of `name` if `name` exceeds the 40-character limit imposed by the 3D Secure specification.
'
pattern: ^[a-zA-Z0-9 ]{1,40}$
example: Acme
applePay:
type: object
description: The Merchant's Apple Pay configuration.
properties:
domains:
type: array
description: 'The domains the Merchant wants registered with Apple Pay. To remove a domain previously registered with Apple Pay, exclude it from the list. Only the domain name is required, without the protocol or path. For example, `example.com` is a valid domain, but `https://example.com` is not.
'
items:
type: string
example: ollivanders.co.uk
examples:
SimpleExample:
value:
shortName: Ollivanders
applePay:
domains:
- ollivanders.co.uk
responses:
'200':
description: Returns the updated Merchant object.
content:
application/json:
schema:
$ref: '#/components/schemas/Merchant'
examples:
SuccessfulCreation:
summary: Merchant successfully updated
value:
id: merchant_eead1d640d7c
name: Ollivanders Wand Shop
shortName: Ollivanders
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:
summary: Delete a Merchant
description: 'Deletes a Merchant by its unique identifier.
'
operationId: deleteMerchant
tags:
- Payments
security:
- ApiKey:
- merchant:delete
parameters:
- name: merchant_id
in: path
description: The id of the Merchant to be deleted.
required: true
schema:
type: string
responses:
'204':
description: Merchant successfully deleted.
/payments/acquirers:
post:
summary: Create an Acquirer
description: 'Creates an Acquirer to be used with 3DS sessions.
'
operationId: createAcquirer
tags:
- Payments
security:
- ApiKey:
- acquirer:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the Acquirer.
description:
type: string
description: The description of the Acquirer.
default:
type: boolean
description: 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](/api#acquirers) for details.
configurations:
type: array
description: The Acquirer configurations. Configurations are set according to each card network the Acquirer is associated with, and each `network` can only appear once. To use a different `bin`, `acquirerMerchantIdentifier`, or `country` for the same network, create a separate Acquirer.
items:
type: object
properties:
network:
type: string
enum:
- visa
- mastercard
- american-express
- discover
description: The card network of the Acquirer. `discover` covers Discover, Diners Club, and JCB (US only).
example: mastercard
bin:
type: string
pattern: ^[0-9]{6,11}$
minLength: 6
maxLength: 11
description: The Bank Identification Number (BIN) of the Acquirer. Must be 6 to 11 digits.
example: '424242'
acquirerMerchantIdentifier:
type: string
description: The merchant identifier associated with the configuration.
example: '38191048173'
country:
type: string
format: iso-3166-1-alpha-2
description: The country of the Acquirer configuration, used when creating 3DS sessions.
example: ie
required:
- network
- bin
- acquirerMerchantIdentifier
- country
required:
- name
- configurations
responses:
'201':
description: Returns the created Acquirer object.
content:
application/json:
schema:
$ref: '#/components/schemas/AcquirerConfiguration'
examples:
SimpleExample:
summary: Acquirer created successfully
value:
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
get:
summary: List Acquirers
description: 'Lists all Acquirers that have been created.
'
operationId: listAcquirers
tags:
- Payments
security:
- ApiKey:
- acquirer:read
parameters:
- name: page
in: query
description: The page number to retrieve.
required: false
schema:
type: integer
default: 0
- name: pageSize
in: query
description: The number of Acquirers to retrieve per page. The default is 50, which is also the maximum.
required: false
schema:
type: integer
default: 50
maximum: 50
responses:
'200':
description: Returns a list of Acquirer objects.
x-content: 'Returns an array of [Acquirer objects](#the-acquirer-object).
'
# --- truncated at 32 KB (159 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/evervault/refs/heads/main/openapi/evervault-payments-api-openapi.yml