@cybersource/flex-sdk-node/README.md

Easily create keys for use in a Flex API integration and verifying Flex token contents

@cybersource/flex-sdk-node
=============

This Node SDK helps with server side aspects of a Flex integration:

- Requesting a transaction specific key
- Verifying the token response

# Installation

Using npm:
```
npm install @cybersource/flex-sdk-node --save
```

Then in node scripts require the sdk:
```js
var FlexSDKNode = require('@cybersource/flex-sdk-node');
```

# Initializing the SDK

To request a transaction specific key, you must supply:
- authentication credentials
- production or test environment
- Optional params passed directly to underlying request object. See docs for [usage](https://www.npmjs.com/package/request)
  - `proxy`

## Using credentials obtained through [CyberSource Business Center](https://ebc2.cybersource.com/ebc2):
```js
var flex = FlexSDKNode({
  // auth credentials
  mid: '__YOUR_MERCHANT_ID__',
  keyId: '__YOUR_KEY_ID__',
  sharedSecret: '__YOUR_SHARED_SECRET__',

  // live environment
  production: true
});
```

## Using credentials obtained through [Visa Developer Center](https://developer.visa.com):
```js
var flex = FlexSDKNode({
  // auth credentials
  apiKey: '__YOUR_API_KEY__',
  sharedSecret: '__YOUR_SHARED_SECRET__',

  // test environment
  production: false
});
```

## Addtional Options
```js
// CGK test environment with proxy
// Proxy with credentials can be supplied as
// 'http://username:password@localproxy.com'

var flex = FlexSDKNode({
  mid: '__YOUR_MERCHANT_ID__',
  keyId: '__YOUR_KEY_ID__',
  sharedSecret: '__YOUR_SHARED_SECRET__',
  production: false,

  proxy: 'http://localproxy.com'
});
```

# Debug Settings

Debug logging is used for the keys request and response.
See docs for [usage](https://www.npmjs.com/package/debug#usage)

# Request a key

Flex encrypts the card number in transit, for additional protection against [MitM attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) where the cardholder's network connection is compromised.

The following encryption methods are supported:

- `RsaOaep256`
- `RsaOaep` (Recommended for widest browser compatibility)
- `None` (No encryption of the card number)

```js
var options = {
  encryptionType: flex.constants.encryptionType.RsaOaep
};

flex.createKey(options, function(err, resp, key) {
  if (err) {
    // handle error
    console.error(err);
    return;
  }

  // you can now pass this key to your front end client for token creation. Ensure to persist
  // this somewhere so you can verify the signatures on any created tokens later on!
  mySavedKey = key;
});
```

If you are requesting a key for use with Flex Microform then you must also supply the origin of the website in which Flex Microform will be embedded:

```js
var options = {
  encryptionType: flex.constants.encryptionType.RsaOaep,
  targetOrigin: 'https://shop.merchant.com'
};
```

Additional optional settings may also be supplied:

```js
var options = {
  encryptionType: flex.constants.encryptionType.RsaOaep,
  settings: {
    currency: 'USD', // Currency to be used with the token
    enableAutoAuth: true, // Whether an automatic authorization should be performed prior to generating a token
    enableBillingAddress: true, // Whether dummy address data should be supplied for the token
    unmaskedLeft: 6, // The number of unmasked digits to be shown at the beginning of the card number (BIN)
    unmaskedRight: 4 // The number of unmasked digits to be shown at the end of the card number
  }
};
```

# Verify a token response

There is a possibility that the token response can be tampered with as it passes through the client. Therefore you should always verify the integrity of the response using the SDK.

```js
if (!flex.verifyToken(publicKey, token)) {
  // Reject token
}
```

- `publicKey` can be:
	- a `jwk` js object
	- a pem formatted string
	- the base64 encoded pem contents (sans header & footer)
- `token` as a js object

## Copyright and license

Code and documentation copyright 2018 [CyberSource](http://www.cybersource.com/). Released under the CyberSource SDK License Agreement as detailed in `./LICENSE.md`.