CardSavr REST API | API Reference

CardSavr REST API API Reference

The CardSavr REST API provides methods for managing the circulation of payment cards on merchant websites. It uses REST principles and built-in HTTP features, such as HTTP verbs, as well as several layers of security to protect sensitive data.

HTTP responses and requests currently support JSON; support for XML will also be available in future versions.

Endpoints

Each tenant has its own endpoints in the CardSavr REST API. Endpoints use the following base format:

https://{tenant-name}.cardsavr.io/

Each tenant must receive its own tenant name, secret key, and application identifier from Switch prior to accessing the CardSavr REST API.

API Endpoint

https://{tenant-name}.cardsavr.io

Contact: kehni@switchme.com

Schemes: https

Version: 1.0.0

Pagination

CardSavr uses a paging object (embedded in a Paging header) with calls that can return multiple results. Any call to such a method will return a single page of results. The Paging header in the response specifies the page number, page length, and sorting order of the returned page.

To request a specific page of results, submit the paging header in the request body. If no paging header is submitted with the Request body, default values will be applied to the page of results returned.

Paging Header Example

{
"Paging": "page: 2, page_length: 25, sort: "id", is_descending: true"
}

Versioning

Each API version is backwards-compatible for all methods that are still supported by CardSavr. The response header APIbaseVersion gives the version of the method called in the request.

Backwards Compatibility

Methods are immutable syntactically and semantically across all versions until they are abandoned.

Deprecation

When a deprecated method is called, the response header APIDeprecatedBy provides the path of the replacement method. Similarly, when a replacement method is called, the response header APIObsoletes gives the deprecated method that has been replaced.

Abandonment

When an abandoned method is called, the response body will contain a migration path that the client can use for code refactoring.

Example Response Headers

{
"APIDeprecatedBy": "https://{tenant}.cardsavr.io/replacement-method",
"APIbaseVersion": 1.0
}

{
"APIObsoletes": "https://{tenant}.cardsavr.io/replaced-method"
}

Keys and Identifiers

CardSavr uses a shared secret key to encrypt and sign requests and responses. Follow the instructions below to obtain the secret key.

Initial Shared Key

You will receive an initial secret key from Switch, along with your tenant and application names. This initial key should be used as the secret key for the /start and /login endpoints. The /login endpoint will respond with the server's public key, which must then be used to compute the shared secret key to be used for all other calls to CardSavr.

Diffie-Hellman (DH) Shared Secret Key

CardSavr uses a a Diffie-Hellman key exchange to generate a secret key known to only Switch and the client. This key is used to encrypt, decrypt, and sign all requests and responses to and from CardSavr. The diagram below shows how a Diffie-Hellman key exchange is used to generate a shared secret key. {{ './pics/dh-key' | image_tag }} To obtain your DH key, you must first generate your own public and private keys. Most major languages have a library or built-in class that allows you to do this (please see the built-in Node Class for an example).

You must submit your own public key in your request to /login. /login will then respond with Switch's public key in the payload. Use Switch's public key, along with your own private and public keys, to compute the shared secret key. Since Switch will execute the same process on the server, both parties will generate the same secret key, known only to them. This shared secret key MUST be used to encrypt and sign your requests. Please see encryption for details on encrypting your requests.

Diffie-Hellman Client Key Generation Example (Node.js)

let ecdh = crypto.createECDH('secp256k1');

ecdh.generateKeys();

let clientPublicKey = ecdh.getPublicKey('base64', 'uncompressed');

let clientPrivateKey = ecdh.getPrivateKey('base64', 'uncompressed');

Application Identifiers

You must obtain your tenant name and application name from Switch in order to sign your requests.

Safe Key

The partner will be issued a safe key for each cardholder. This safe key will be combined with an internal switch ops key to derive a new key that must be used to access all cardholder safe information.

Encryption

CardSavr protects data using symmetric encryption via a
CardSavr API users and Switch will encrypt request and response bodies, respectively, using their shared secret key. As a result, the encrypted payloads can only be decrypted by Switch or the user.

You must encrypt the body of your request using 256-bit, Advanced Encryption Standard cipher block chaining (i.e. AES-CBC-256), a 16-byte, cryptographically strong initilization vector, and your shared secret key. Please see the code at right for an example of how to encrypt a request body in Node.js

The encrypted request body must be combined with the Base64-encoded initialization vector used to encrypt the body. The request body must be separated from the initialization vector with a '$' delimiter, illustrated below:

Base64-Encrypted-JSON-Body$Base64-IV

Finally, to send your request, put the encrypted request into your request body object in the property "encryptedBody".

Request Body Encryption Code Example (Node.js)


let binaryEncryptionKey = new Buffer(32);

//converts shared secret key into binary
binaryEncryptionKey.write(sharedSecretKey, 'base64');

//creates initialization vector
let IV = crypto.randomBytes(16);

bodyJSON = JSON.stringify(requestBody);

//converts request body object into binary
let bufferJSON = new Buffer(bodyJSON.length);
bufferJSON.write(bodyJSON, 'utf8');

//encrypts request body using the AES-CBC-256 algorithm, shared secret key, and initialization vector

let encryptor = crypto.createCipheriv('aes-256-cbc', binaryEncryptionKey, IV);
try {
  let encryptedJSON = Buffer.concat([encryptor.update(bufferJSON), encryptor.final()]);

  // Create new request body with the encrypted body as an object attribute (converted to binary)
  let newBody = {
    'encryptedBody' : encryptedJSON.toString('base64') + '$' + IV.toString('base64')
  }
  return(newBody);
} catch (err) {
  return (null);
}

Request signing

CardSavr requires HMAC signing for all requests and responses. This allows for identity authentication and integrity verification for each request and response. HMAC signing requires your application name and shared secret key. Please follow the algorithm below.

HMAC Signature Algorithm

All CardSavr requests must be signed with an HMAC signature according to the instructions below. Please see the code at right for an implementation of this procedue in Node.js.

First, create the string-to-sign, which references two required request headers, Authorization and Nonce:

The Authorization header contains the shared secret key and your application name.

The Nonce header contains the current UTC time in milliseconds, and therefore provides protection against replay attacks (see the example at right).

The string-to-sign format is: StringToSign = URL-Path + Headers.Authorization + Headers.Nonce + Request Body, where URL-Path is the endpoint you are calling.

The string-to-sign is then passed to an SHA256 algorithm along with the secret key.

The signature then goes in the "signature" request header, following the format below:

"Signature": HMAC-SHA256(Shared-Secret-Key, StringToSign)

Request Headers

{
    "Authorization": Shared-Secret-Key + App-Name,
    "Nonce": 1525373034656,
    "Signature": HMAC-SHA256(Shared-Secret-Key, StringToSign)
}

HMAC Signing Code Example (Node.js)


let signedString;

if ((typeof(requestBody) !== 'undefined') && requestBody !== null ) {
signedString = endpoint-URL + headers.authorization + headers.nonce + JSON.stringify(requestBody);
} else {
signedString = endpoint-URL + headers.authorization + headers.nonce;
}

buffer_signing_key.write(sharedSecretKey, 'base64');

let hmac = crypto.createHmac('sha256', buffer_signing_key);

hmac.update(signedString);

let signature = hmac.digest('base64');

Signed Salt

Rather than storing cleartext passwords on the server, CardSavr stores password keys for each user, which are derived from the format below (where usernameSalt is an SHA-256 hashed salt of your username):

password_key = PBKDF(password, usernameSalt, 5000, 32, 'sha256')

In order to login as a principal user, you must submit an HMAC signature of the session salt (returned by /start) on your password key.

Once you have derived your password key, you can derive the signed salt using the format below:

SHA-256(password_key, sessionSalt)

See the example at right for an implementation of this in code.

Password Key Generation Example (Node.js)


let hash = crypto.createHash('sha256');

hash.update(user.username);

let salt = hash.digest();

let password_key = crypto.pbkdf2Sync(password, usernameSalt, 5000, 32, 'sha256');

Signed Session Salt Generation Example (Node.js)


buffer_session_salt.write(session_salt, 'base64');

password_key.write(user.password, 'base64');

let hmac = crypto.createHmac('sha256', password_key);

hmac.update(buffer_session_salt);

b64_hmac_signature = hmac.digest('base64');

Data Protection

Two types of sensitive data are stored by CardSavr:

Card holder sensitive data includes name, address, phone number and site credentials.

Card issuer sensitive data includes the Primary Account Number (PAN), Card Verification Value (CVV) and expiration date.

Both types of sensitive data are stored in a separate, encrypted Personal Identifiable Information (PII)/Card Data Environment (CDE) safe within a card holder profile.

While all data stored by CardSavr is protected at rest by database encryption, sensitive data is additionally protected by TwoFish encryption at rest and in memory until just in time for conversion to clear text within the CardSavr infrastructure. In order to access the safe, a TwoFish-encrypted safe key is derived by combining an internal partner safe key with an internal switch ops key. Once a method is completed, the derived key and the clear text PII/CDE safe data is zeroized in the service infrastructure, so it cannot be used again.

CardSavr uses external reference handles to operate on card and card holder site credentials. All PII/CDE data is write-only within this API.

Merchant Sites

Returns all merchant sites supported by CardSavr

Merchant Sites

Get merchant sites

GET /merchant-sites

Returns merchant sites that match the provided parameters. If no query parameters are provided, all supported sites will be returned. The first 25 results will be returned if no page length is specified in the Paging request header.

paging

in header

string

Stringified JSON object that specifies the range of results returned and how the results are sorted.

In the example at right, results 11-15 would be returned, sorted in descending order by ID.

Page (integer): the page to be returned.
Page_length (integer): length of each page
Sort (string): field you wish to sort by
Descending (boolean): if true, will sort results in descending order; otherwise, will sort in ascending order.

ids

in query

integer[]

ID(s) of merchant site. Multiple IDs must be separated by commas.

Example:

?ids=aaa,bbb,ccc

site_name

in query

string

Name of merchant.

site_hostname

in query

string

Domain name of merchant site.

alternate_site_hostnames

in query

string

Alternate domain names associated with site.

alexa_rank_max

in query

integer

The maximum Alexa rank (a metric for website traffic, with a higher rank corresponding to higher traffic) for returned results. Merchant sites with a higher Alexa rank will not be returned.

alexa_rank_min

in query

integer

The minimum Alexa rank for returned results. Merchant sites with a lower Alexa rank will not be returned.

created_on_min

in query

string

The earliest date of creation for returned results. Merchant sites created earlier than created_on_min will not be returned.

created_on_max

in query

string

The latest date a merchant site was added to CardSavr for returned results. Merchant sites created later than created_on_max will not be returned.

updated_on_max

in query

integer

The latest date a merchant site was updated in the CardSavr database. Merchant sites updated later than updated_on_max will not be returned.

updated_on_min

in query

string

The earliest date a merchant site was updated in the CardSavr database. Merchant sites updated earlier than updated_on_min will not be returned.

Request Headers

{
    "Paging": "page: 3, page_length: 5, sort: "id", is_descending: true"
}

200 OK

OK. Array of merchant sites in body. Paging object in header.

400 Bad Request

Invalid parameters. Extra information in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

[
  {
    "id": 10,
    "created_on": "2018-04-09T00:00:00.000Z",
    "last_updated_on": "2018-04-09T00:00:00.000Z",
    "site_name": "Test",
    "site_hostname": "www.test.com",
    "alexa_rank": 6,
    "tags": "Shopping,Entertainment,General Merchandise,Major Retailers,Shopping,Books",
    "image_list_normal": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-128.png ",
    "image_list_normal_gray": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/list-gray-32.png ",
    "image_tile_normal": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-128.png ",
    "image_tile_normal_gray": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-gray-128.png ",
    "alternate_site_hostnames": null,
    "manual_override_actions": false,
    "manual_override_images": false,
    "site_dominant_color": " 0,0,0 "
  }
]

Response Headers (200 OK)

{
  "Paging": "page: 3, page_length: 5, sort: "id", is_descending: true, total_results: 115"
}

Merchant Sites

Get merchant site by ID

GET /merchant-sites/{id}

Returns the merchant site that corresponds to the provided ID.

in path

integer

ID of merchant site.

200 OK

OK. Retrieved site info in body.

404 Not Found

No merchant site found that matches the provided parameters.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 10,
  "created_on": "2018-04-09T00:00:00.000Z",
  "last_updated_on": "2018-04-09T00:00:00.000Z",
  "site_name": "Changed name",
  "site_hostname": "www.test.com",
  "alexa_rank": 6,
  "tags": "Sample tag",
  "image_list_normal": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-128.png ",
  "image_list_normal_gray": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/list-gray-32.png ",
  "image_tile_normal": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-128.png ",
  "image_tile_normal_gray": "https://swch-site-images.s3.amazonaws.com/53bd7ab57f982c1e8821fcf9/tile-gray-128.png ",
  "alternate_site_hostnames": null,
  "manual_override_actions": false,
  "manual_override_images": false,
  "site_dominant_color": "0,0,0"
}

Session

Start new CardSavr session

GET /start/

Starts new CardSavr session. Returns a session salt to be used for user login.

200 OK

Session successfully started. Session salt returned in body.

400 Bad Request

Validation error. More info in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "sessionSalt": "kz2R3qexAkZqhoCalnNX9+6CLAMZ+lEDRLICPcOnTc4="
}

Session

User login

POST /login/

Logs in principal API user.

clientPublicKey

in body

string

The public key issued by Switch.

userName

in body

string

Username associated with account.

signedSalt

in body

string

Signed session salt; 256-bit hash, 44 characters long. Consists of the session salt (issued in /start response) signed by user password key and username. See signing for details.

Request Example


{
  "clientPublicKey": "sample_public_key",
  "userName": "john_doe_123",
  "signedSalt": "sample_signed_salt"
}

200 OK

Successfully logged in. Server public key returned in body.

400 Bad Request

Invalid parameters. Extra info in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "serverPublicKey": "sample_public_key"
}

Session

End current session

GET /end/

Ends current CardSavr session.

200 OK

Session sucessfully ended.

400 Bad Request

Validation error. Extra info in body.

500 Internal Server Error

Database error. Extra info in body.

Cards

Access and manage payment cards

Cards

Get payment cards

GET /cards/

Returns payment cards that match the provided parameters.

paging

in header

string

Stringified JSON object that specifies the range of results returned and how the results are sorted. If no paging header is submitted with the request, default values will be applied.

In the example at right, results 26-50 would be returned, sorted in descending order by ID.

Property	Description	Default
page (integer)	the page to be returned	1
page_length (integer)	length of each page	25
sort (string)	property to sort by	null
is_descending (boolean)	true if sort order is descending	false

ids

in query

integer

ID(s) in CardSavr database.

cardholder_id

in query

integer

ID of the CardSavr user who owns this card.

bin_id

in query

integer

BIN associated with this card.

safe_id

in query

integer

ID number of the CardSavr safe containing this card.

par

in query

integer

PAR number of this card.

card_color

in query

string

Color of physical card.

created_on_max

in query

string (date)

Latest date that card was added to CardSavr.

created_on_min

in query

string (date)

Earliest date that card was added to CardSavr.

updated_on_max

in query

integer

The latest date a card was updated in the CardSavr database. Cards updated later than updated_on_max will not be returned.

updated_on_min

in query

string

The earliest date a card was updated in the CardSavr database. Cards updated earlier than updated_on_min will not be returned.

Request Headers (optional)

{
  "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true"
}

200 OK

OK. Array of matching cards returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

[
  {
    "cardholder_id": 3,
    "bin_id": 1234,
    "safe_id": 3,
    "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
    "card_color": "#BBBBBB"
  }
]

Response Headers (200 OK)

{
    "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true, total_results: 249"
  }

Cards

Create payment card

POST /cards/

Creates existing payment card.

cardholder_id

in body

integer

ID of the CardSavr user who owns the card.

bin_id

in body

integer

BIN associated with this card.

safe_id

in body

integer

ID number of the safe containing this card.

par

in body

integer

Payment Acount Reference number of the card.

card_color

in body

string

Color of physical card.

Example

{
  "cardholder_id": 3,
  "bin_id": 1234,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#BBBBBB"
}

200 OK

Successfully updated. Updated payment card in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 5,
  "cardholder_id": 3,
  "bin_id": 1234,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#BBBBBB"
}

Cards

Update payment card

PUT /cards/

Updates existing payment card.

in body

integer

ID in CardSavr database.

cardholder_id

in body

integer

ID of the CardSavr user who owns the card.

bin_id

in body

integer

BIN associated with this card.

safe_id

in body

integer

ID number of the safe containing this card.

par

in body

integer

Payment Acount Reference number of the card.

card_color

in body

string

Color of physical card.

Request Example

{
  "id": 5,
  "card_color": "#BBBBBB"
}

200 OK

Successfully updated. Updated payment card returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 5,
  "cardholder_id": 3,
  "bin_id": 4321,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#BBBBBB"
}

Cards

Get payment card by ID

GET /cards/{id}

Returns card that matches the provided ID.

in path

integer

200 OK

OK. Card returned in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 5,
  "cardholder_id": 3,
  "bin_id": 4321,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#BBBBBB"
}

Cards

Update payment card by ID

PUT /cards/{id}

Updates card that matches the provided ID.

in path

integer

ID in CardSavr database.

cardholder_id

in body

integer

ID of the CardSavr user who owns the card.

bin_id

in body

integer

BIN associated with this card.

safe_id

in body

integer

ID number of the safe containing this card.

par

in body

integer

Payment Acount Reference number of the card.

card_color

in body

string

Color of physical card.

Request Example

{
  "card_color": "#EEEEEE"
}

200 OK

Successfully updated. Updated card returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 5,
  "cardholder_id": 3,
  "bin_id": 4321,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#EEEEEE"
}

Cards

Delete payment card

DELETE /cards/{id}

Deletes card that matches the provided ID.

in path

integer

(no description)

200 OK

Successfully deleted. Deleted card returned in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 5,
  "cardholder_id": 3,
  "BIN_id": 4321,
  "safe_id": 9,
  "par": "Q1J4AwSWD4Dx6q1DTo0MB21XDAV76",
  "card_color": "#EEEEEE"
}

BINs

Access and manage BINs

BINs

Get BINs

GET /cardsavr_bins/

Returns BINs that match provided parameters.

paging

in header

string

Stringified JSON object that specifies the range of results returned and how the results are sorted. If no paging header is submitted with the request, default values will be applied.

In the example at right, results 26-50 would be returned, sorted in descending order by ID.

Property	Description	Default
page (integer)	the page to be returned	1
page_length (integer)	length of each page	25
sort (string)	property to sort by	null
is_descending (boolean)	true if sort order is descending	false

ids

in query

integer

Bank Identification Number.

brand

in query

string

E.g. Visa, American Express.

issuer

in query

string

The issuing institution.

type

in query

string

E.g. debit, credit, prepaid.

level

in query

string

E.g. platinum, silver.

country_code

in query

string

Country code associated with issuer of this BIN.

is_deprecated

in query

boolean

True if new cards are no longer being issued under this BIN.

Request Headers (optional)

{
    "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true"
}

200 OK

OK. Array of matching BINs returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

[
  {
    "id": 1234,
    "country_code": "DK",
    "level": "Platinum",
    "type": "Credit",
    "brand": "Visa",
    "issuer": "Main Street Bank",
    "is_deprecated": false
  }
]

Response Headers (200 OK)

{
    "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true, total_results: 899"
}

BINs

Create BIN

POST /cardsavr_bins/

Create new BIN.

in query

integer

Bank Identification Number.

brand

in query

string

E.g. Visa, American Express.

issuer

in query

string

The issuing institution.

type

in query

string

E.g. debit, credit, prepaid.

level

in query

string

E.g. platinum, silver.

country_code

in query

string

Country code associated with issuer of this BIN.

is_deprecated

in query

boolean

True if new cards are no longer being issued under this BIN.

Request Example

{
  "brand": "Visa",
  "issuer": "Main Street Bank",
  "type": "Credit",
  "level": "Platinum",
  "country_code": "DK",
  "is_deprecated": false
}

200 OK

Successfully created. New bin returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 1234,
  "brand": "Visa",
  "issuer": "Main Street Bank",
  "type": "Credit",
  "level": "Platinum",
  "country_code": "DK",
  "is_deprecated": false
}

BINs

Update BIN

PUT /cardsavr_bins/

Updates BIN.

in query

integer

Bank Identification Number.

brand

in query

string

E.g. Visa, American Express.

issuer

in query

string

The issuing institution.

type

in query

string

E.g. debit, credit, prepaid.

level

in query

string

E.g. platinum, silver.

country_code

in query

string

Country code associated with issuer of this BIN.

is_deprecated

in query

boolean

True if new cards are no longer being issued under this BIN.

Request Example

{
  "id": 1234,
  "issuer": "Updated Main Street Bank"
}

200 OK

Successfully updated. Updated BIN returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No BIN could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 1234,
  "brand": "Visa",
  "issuer": "Updated Main Street Bank",
  "type": "Credit",
  "level": "Silver",
  "country_code": "DK",
  "is_deprecated": false
}

BINs

Get BIN

GET /cardsavr_bins/{id}

Returns bin that matches the specified ID.

in path

integer

(no description)

200 OK

OK. BIN returned in body.

404 Not Found

No BIN could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 1234,
  "brand": "Visa",
  "issuer": "Updated Main Street Bank",
  "type": "Credit",
  "level": "Silver",
  "country_code": "DK",
  "is_deprecated": false
}

BINs

Update BIN

PUT /cardsavr_bins/{id}

Updates BIN.

in path

integer

Bank Identification Number.

brand

in query

string

E.g. Visa, American Express.

issuer

in query

string

The issuing institution.

type

in query

string

E.g. debit, credit, prepaid.

level

in query

string

E.g. platinum, silver.

country_code

in query

string

Country code associated with issuer of this BIN.

is_deprecated

in query

boolean

True if new cards are no longer being issued under this BIN.

Request Example

{
  "id": 1234,
  "issuer": "Updated Main Street Bank"
}

200 OK

Successfully updated. Updated BIN returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No BIN could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 1234,
  "brand": "Visa",
  "issuer": "Updated Main Street Bank",
  "type": "Credit",
  "level": "Silver",
  "country_code": "DK",
  "is_deprecated": false
}

BINs

Delete BIN

DELETE /cardsavr_bins/{id}

Deletes BIN.

in path

integer

Bank Identification Number.

200 OK

Successfully deleted. Deleted BIN returned in body.

404 Not Found

No BIN could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 1234,
  "brand": "Visa",
  "issuer": "Updated Main Street Bank",
  "type": "Credit",
  "level": "Silver",
  "country_code": "DK",
  "is_deprecated": false
}

CardSavr Users

Access and manage CardSavr user accounts

CardSavr Users

Get CardSavr users

GET /cardsavr_users/

Returns CardSavr users that match the provided parameters. If no query parameters are provided, all CardSavr users associated with the tenant will be returned.

paging

in header

string

Stringified JSON object that specifies the range of results returned and how the results are sorted. If no paging header is submitted with the request, default values will be applied.

In the example at right, results 26-50 would be returned, sorted in descending order by ID.

Property	Description	Default
page (integer)	the page to be returned	1
page_length (integer)	length of each page	25
sort (string)	property to sort by	null
is_descending (boolean)	true if sort order is descending	false

ids

in query

integer

username

in query

string

Username of CardSavr user.

first_name

in query

string

First name of CardSavr user.

last_name

in query

string

Last name of CardSavr user.

proxy_login_token

in query

string

Token to be used in proxy login.

TFA_SS

in query

string

Code used for Two-Factor Authentication of user.

TFA_SMS

in query

string

SMS number used for Two-Factor Authentication of user.

TFA_type

in query

string

Two-Factor Authentication method enabled for user.

TFA_frequency

in query

string

Frequency with which Two-Factor Authentication is required for user.

remember_username

in query

boolean

True if username is set to be remembered by tenant.

is_internal

in query

boolean

True if user is an internal user (e.g. an admin).

TFA

in query

boolean

True if Two-Factor Authentication is enabled for user.

is_locked

in query

boolean

True if user account has been locked for security reasons.

proxy_login_token_expiration

in query

string

Token to be used in proxy login.

last_login_time_max

in query

string (date)

Latest date of user's last login time.

last_login_time_min

in query

string (date)

Earliest date of user's last login time.

TFA_timeout_max

in query

string (date)

Latest date of Two-Factor Authentication timeout.

TFA_timeout_min

in query

string (date)

Latest date of Two-Factor Authentication timeout.

created_on_max

in query

string (date)

Latest date that user was added to CardSavr.

created_on_min

in query

string (date)

Earliest date that user was added to CardSavr.

Request Headers (optional)

{
  "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true"
}

200 OK

OK. Returns array of all users that match submitted parameters.

400 Bad Request

Invalid parameters. Extra info in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

[
  {
    "id": 123,
    "username": "john_doe_123",
    "first_name": "John",
    "last_name": "Smith",
    "proxy_login_token": "proxy_login_token",
    "TFA_SS": "tfa_ss_123,",
    "TFA_SMS": "tfa_sms_5,",
    "TFA_type": "tfa_4",
    "TFA_frequency": "2",
    "failed_attempts": "555,",
    "remember_username": false,
    "is_internal": false,
    "TFA": false,
    "is_locked": true,
    "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
    "last_login_time": "2006-06-06T06:06:06.006Z",
    "TFA_timeout": "2010-10-10T10:10:10.100Z",
    "created_on": "2018-04-19T23:10:36.657Z",
    "last_updated_on": "null"
  }
]

Response Headers (200 OK)

{
  "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true, total_results: 382"
}

CardSavr Users

Create new CardSavr user

POST /cardsavr_users/

Creates new CardSavr user.

username

in query

string

Username of CardSavr user.

first_name

in query

string

First name of CardSavr user.

last_name

in query

string

Last name of CardSavr user.

proxy_login_token

in query

string (date)

Token used for login via proxy.

TFA_SS

in query

string

Code used for Two-Factor Authentication of user.

TFA_SMS

in query

string

SMS number used for Two-Factor Authentication of user.

TFA_type

in query

string

Two-Factor Authentication method enabled for user.

TFA_frequency

in query

string

Frequency with which Two-Factor Authentication is required for user.

remember_username

in query

boolean

True if username is set to be remembered by tenant.

is_internal

in query

boolean

True if user is an internal user (e.g. an admin).

TFA

in query

boolean

True if two-factor authentication is enabled.

TFA_timeout

in query

string (date)

Date of Two-Factor Authentication timeout.

Request Example

{
  "id": 123,
  "TFA_SS": "tfa_ss_123,",
  "proxy_login_token": "proxy_login_token",
  "is_locked": true,
  "is_internal": false,
  "last_login_time": "2006-06-06T06:06:06.006Z",
  "failed_attempts": "555,",
  "last_name": "Smith",
  "remember_username": false,
  "TFA": false,
  "TFA_timeout": "2010-10-10T10:10:10.100Z",
  "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "TFA_SMS": "tfa_sms_5,",
  "TFA_type": "tfa_4",
  "last_updated_on": "null",
  "first_name": "John",
  "username": "john_doe_123"
}

200 Created

Successfully created. New CardSavr user returned in body.

400 Bad Request

Invalid parameters. Extra info in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (201 Created)


{
  "id": 123,
  "username": "john_smith_123",
  "first_name": "John",
  "last_name": "Smith",
  "TFA_SS": "tfa_ss_123,",
  "TFA_SMS": "tfa_sms_5,",
  "TFA_type": "tfa_4",
  "TFA_frequency": "tfa_4",
  "failed_attempts": "555,",
  "remember_username": false,
  "is_internal": false,
  "TFA": false,
  "is_locked": true,
  "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
  "last_login_time": "2006-06-06T06:06:06.006Z",
  "TFA_timeout": "2010-10-10T10:10:10.100Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "2018-04-25T20:03:26.387Z",
}

CardSavr Users

Update CardSavr users

PUT /cardsavr_users/

Updates specified CardSavr user information.

in query

string

ID of CardSavr user.

username

in body

string

Username of CardSavr user.

first_name

in body

string

First name of CardSavr user.

last_name

in body

string

Last name of CardSavr user.

proxy_login_token

in body

string (date)

Token used for proxy login.

TFA_SS

in body

string

Code used for Two-Factor Authentication of user.

TFA_SMS

in body

string

SMS number used for Two-Factor Authentication of user.

TFA_type

in body

string

Two-Factor Authentication method enabled for user.

TFA_frequency

in body

string

Frequency with which Two-Factor Authentication is required for user.

remember_username

in body

boolean

True if username is set to be remembered by tenant.

is_internal

in body

boolean

True if user is an internal user (e.g. an admin).

TFA

in body

boolean

True if Two-Factor Authentication is enabled for user.

is_locked

in body

boolean

True if user account has been locked for security reasons.

proxy_login_token_expiration

in body

string (date)

Expiration date of proxy login token.

last_login

in body

string (date)

Date of user's last login time.

TFA_timeout

in body

string (date)

Date of Two-Factor Authentication timeout.

Request Example

{
  "id": 123,
  "first_name": "John Updated"
}

200 OK

OK. Updated cardholder returned in body.

400 Bad Request

Invalid parameters. Extra info in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


{
  "id": 123,
  "username": "john_smith_123",
  "first_name": "John Updated",
  "last_name": "Smith",
  "TFA_SS": "tfa_ss_123,",
  "TFA_SMS": "tfa_sms_5,",
  "TFA_type": "tfa_4",
  "TFA_frequency": "tfa_4",
  "failed_attempts": "555,",
  "remember_username": false,
  "is_internal": false,
  "TFA": false,
  "is_locked": true,
  "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
  "last_login_time": "2006-06-06T06:06:06.006Z",
  "TFA_timeout": "2010-10-10T10:10:10.100Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "2018-04-25T20:03:26.387Z",
}

CardSavr Users

Get CardSavr user

GET /cardsavr_users/{id}

Returns specific CardSavr user.

in path

integer

Database ID of CardSavr user.

200 OK

OK. Updated CardSavr user returned in body.

404 Not Found

No CardSavr user with the provided ID could be found.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


{
  "id": 123,
  "username": "john_smith_123",
  "first_name": "John Updated",
  "last_name": "Smith",
  "TFA_SS": "tfa_ss_123,",
  "TFA_SMS": "tfa_sms_5,",
  "TFA_type": "tfa_4",
  "TFA_frequency": "tfa_4",
  "failed_attempts": "555,",
  "remember_username": false,
  "is_internal": false,
  "TFA": false,
  "is_locked": true,
  "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
  "last_login_time": "2006-06-06T06:06:06.006Z",
  "TFA_timeout": "2010-10-10T10:10:10.100Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "2018-04-25T20:03:26.387Z"
}

CardSavr Users

Update CardSavr user by ID

PUT /cardsavr_users/{id}

Updates specified CardSavr user.

in path

integer

Database ID of CardSavr user.

username

in body

string

Username of CardSavr user.

first_name

in body

string

First name of CardSavr user.

last_name

in body

string

Last name of CardSavr user.

proxy_login_token

in body

string (date)

Token used for proxy login.

TFA_SS

in body

string

Code used for Two-Factor Authentication of user.

TFA_SMS

in body

string

SMS number used for Two-Factor Authentication of user.

TFA_type

in body

string

Two-Factor Authentication method enabled for user.

TFA_frequency

in body

string

Frequency with which Two-Factor Authentication is required for user.

remember_username

in body

boolean

True if username is set to be remembered by tenant.

is_internal

in body

boolean

True if user is an internal user (e.g. an admin).

TFA

in body

boolean

True if Two-Factor Authentication is enabled for user.

is_locked

in body

boolean

True if user account has been locked for security reasons.

proxy_login_token_expiration

in body

string (date)

Expiration date of proxy login token.

last_login

in body

string (date)

Date of user's last login time.

TFA_timeout

in body

string (date)

Date of Two-Factor Authentication timeout.

Request Example

{
  "username": "john_smith_123_changed"
}

200 OK

OK. Updated CardSavr user returned in body.

400 Bad Request

Invalid parameters. Extra info in body.

404 Not Found

No card could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


  {
    "id": 123,
    "username": "john_smith_123_changed",
    "first_name": "John Updated",
    "last_name": "Smith",
    "TFA_SS": "tfa_ss_123,",
    "TFA_SMS": "tfa_sms_5,",
    "TFA_type": "tfa_4",
    "TFA_frequency": "tfa_4",
    "failed_attempts": "555,",
    "remember_username": false,
    "is_internal": false,
    "TFA": false,
    "is_locked": true,
    "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
    "last_login_time": "2006-06-06T06:06:06.006Z",
    "TFA_timeout": "2010-10-10T10:10:10.100Z",
    "created_on": "2018-04-19T23:10:36.657Z",
    "last_updated_on": "2018-04-25T20:03:26.387Z",
  }

CardSavr Users

Delete CardSavr user

DELETE /cardsavr_users/{id}

Deletes specified CardSavr user.

in path

integer

Database ID of CardSavr user.

200 OK

Successfully deleted. Deleted CardSavr user returned in body.

404 Not Found

CardSavr user with that ID not found.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


{
  "id": 123,
  "username": "john_smith_123_changed",
  "first_name": "John Updated",
  "last_name": "Smith",
  "TFA_SS": "tfa_ss_123,",
  "TFA_SMS": "tfa_sms_5,",
  "TFA_type": "tfa_4",
  "TFA_frequency": "tfa_4",
  "failed_attempts": "555,",
  "remember_username": false,
  "is_internal": false,
  "TFA": false,
  "is_locked": true,
  "proxy_login_token_expiration": "2001-01-01T01:01:01.001Z",
  "last_login_time": "2006-06-06T06:06:06.006Z",
  "TFA_timeout": "2010-10-10T10:10:10.100Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "2018-04-25T20:03:26.387Z",
}

CardSavr Accounts

Access and manage CardSavr user accounts on merchant sites

CardSavr Accounts

Get CardSavr user merchant accounts

GET /cardsavr_accounts/

Returns CardSavr user accounts on merchant sites.

paging

in header

string

Stringified JSON object that specifies the batch of results returned and how the results are sorted. If no paging header is submitted with the request, default values will be applied.

In the example at right, results 26-50 would be returned, sorted in descending order by ID.

Property	Description	Default
page (integer)	the page to be returned	1
page_length (integer)	length of each page	25
sort (string)	property to sort by	null
is_descending (boolean)	true if sort order is descending	false

ids

in query

integer

ID(s) in CardSavr database.

cardholder_ids

in query

integer

CardSavr user ID.

merchant_site_ids

in query

integer

ID(s) of merchant sites.

username

in query

string

CardSavr user username for merchant site.

custom_display_text

in query

string

Custom name for merchant site (to be displayed on client apps/websites)

last_saved_card_max

in query

string (date)

Latest date that card was last saved on account.

last_saved_card_min

in query

string (date)

Earliest date that card was last saved on account.

last_password_update_max

in query

string (date)

Latest date that password was last updated.

last_password_update_min

in query

string (date)

Earliest date that password was last updated.

last_login_max

in query

string (date)

Latest date that user last logged in to merchant site.

last_login_min

in query

string (date)

Earliest date that user last logged in to merchant site.

Request Headers (optional)

{
  "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true"
}

200 OK

Successfully created. New account returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

[
  {
    "id": 123,
    "cardholder_id": 11,
    "merchant_site_id": 5,
    "username": "john_smith123",
    "custom_display_text": "Best Buy",
    "require_master_password": false,
    "auto_login": false,
    "last_login": "2018-04-30T17:57:34.876Z",
    "last_password_update": "2018-04-30T17:57:34.876Z",
    "last_saved_card": "2018-04-30T17:57:34.876Z",
    "created_on": "2018-04-19T23:10:36.657Z",
    "last_updated_on": "2018-04-30T17:21:08.089Z"
  }
]

Response Headers (200 OK)

{
  "Paging": "page: 2, page_length: 25, sort: "id", is_descending: true, total_results: 2080"
}

CardSavr Accounts

Creates CardSavr user merchant site account

POST /cardsavr_accounts/

Returns CardSavr user accounts on merchant sites.

cardholder_id

in body

integer

CardSavr user id.

merchant_site_id

in body

integer

ID of merchant.

username

in body

string

CardSavr user username for merchant site.

custom_display_text

in body

string

Custom name for merchant site (to be displayed on client apps/websites)

last_saved_card

in body

string (date)

Date that card was last saved on account.

last_password_update

in body

string (date)

Date that password was last updated.

last_login

in body

string (date)

Date that user last logged in to merchant site.

Request Example


{
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith123"
}

200 OK

Successfully created. New account returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


{
  "id": 123,
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith123",
  "custom_display_text": "Best Buy",
  "require_master_password": false,
  "auto_login": false,
  "last_login": "2018-04-30T17:57:34.876Z",
  "last_password_update": "2018-04-30T17:57:34.876Z",
  "last_saved_card": "2018-04-30T17:57:34.876Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "null"
}

CardSavr Accounts

Update CardSavr user merchant account

PUT /cardsavr_accounts/

in body

integer

Account ID.

cardholder_id

in body

integer

CardSavr user ID.

merchant_site_id

in body

integer

Merchant site ID.

username

in body

string

CardSavr user username for merchant site.

custom_display_text

in body

string

Custom name for merchant site (to be displayed on client apps/websites)

last_saved_card

in body

string (date)

Date that card was last saved on account.

last_password_update

in body

string (date)

Date that password was last updated.

last_login

in body

string (date)

Date that user last logged in to merchant site.

Request Example

{
  "id": 123,
  "username": "john_smith_updated123"
}

200 OK

Successfully created. New account returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No CardSavr account could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)


{
  "id": 123,
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith_updated123",
  "custom_display_text": "Best Buy",
  "require_master_password": false,
  "auto_login": false,
  "last_login": "2018-04-30T17:57:34.876Z",
  "last_password_update": "2018-04-30T17:57:34.876Z",
  "last_saved_card": "2018-04-30T17:57:34.876Z",
  "created_on": "2018-04-19T23:10:36.657Z",
  "last_updated_on": "2018-04-30T17:21:08.089Z"
}

CardSavr Accounts

Returns CardSavr user merchant account

GET /cardsavr_accounts/{id}

Returns CardSavr user merchant account specified by ID.

in path

integer

200 OK

Successfully created. New account returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No CardSavr account could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 123,
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith_updated123",
  "custom_display_text": "Best Buy",
  "auto_login": false,
  "last_saved_card": "2018-04-30T17:57:34.876Z",
  "last_password_update": "2018-04-30T17:57:34.876Z",
  "last_login": "2018-04-30T17:57:34.876Z"
  "created_on": "2018-04-29T15:31:34.876Z",
  "last_updated_on": "null"
}

CardSavr Accounts

Update CardSavr user merchant account

PUT /cardsavr_accounts/{id}

Updates the CardSavr user merchant account specified by the provided ID.

in path

integer

cardholder_id

in body

integer

CardSavr user ID.

merchant_site_id

in body

integer

Merchant site ID.

username

in body

string

CardSavr user username for merchant site.

custom_display_text

in body

string

Custom name for merchant site (to be displayed on client apps/websites)

last_saved_card

in body

string (date)

Date that card was last saved on account.

last_password_update

in body

string (date)

Date that password was last updated.

last_login

in body

string (date)

Date that user last logged in to merchant site.

Request Example

{
  "id": 123,
  "username": "john_smith_updated456"
}

200 OK

Successfully updated. Updated account returned in body.

400 Bad Request

Invalid parameters. Extra info provided in body.

404 Not Found

No CardSavr account could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 123,
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith_updated456",
  "custom_display_text": "Best Buy",
  "auto_login": false,
  "require_master_password": false,
  "last_login": "2018-04-30T17:57:34.876Z",
  "last_password_update": "2018-04-30T17:57:34.876Z",
  "last_saved_card": "2018-04-30T17:57:34.876Z",
  "created_on": "2018-04-29T15:31:34.876Z",
  "last_updated_on": "2018-04-30T15:21:52.876Z"
}

CardSavr Accounts

Delete CardSavr user merchant account

DELETE /cardsavr_accounts/{id}

Deletes the CardSavr user merchant account specified by the provided ID.

in path

integer

200 OK

Successfully deleted. Deleted account returned in body.

404 Not Found

No CardSavr account could be found that matches the provided ID.

500 Internal Server Error

Database error. Extra info in body.

Response Example (200 OK)

{
  "id": 123,
  "cardholder_id": 11,
  "merchant_site_id": 5,
  "username": "john_smith123",
  "custom_display_text": "Best Buy",
  "auto_login": false,
  "last_login": "2018-04-30T17:57:34.876Z",
  "last_password_update": "2018-04-30T17:57:34.876Z",
  "last_saved_card": "2018-04-30T17:57:34.876Z",
  "created_on": "2018-04-29T15:31:34.876Z",
  "last_updated_on": "2018-04-30T15:21:52.876Z"
}

Documentation by Spectacle

Invalid State Error