CyberSource.Flex.Server 0.2.2

CyberSource Secure Acceptance: Flex Server Side .NET SDK

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

• Requesting a transaction specific key
• Verifying the token response

Initialize credentials

To request a transaction specific key, you must to supply your authentication credentials.

Note: To help prevent the exposure of sensitive credentials through heap inspection the Flex SDK requires that such credentials are supplied using a SecureString instance.

Using credentials obtained through CyberSource Business Center:

using FlexServerSDK;
using FlexServerSDK.Authentication;

/* ... */

// Replace with your credentials
string merchantId = "__YOUR_MERCHANT_ID__";
string keyId = "__YOUR_KEY_ID__";
SecureString sharedSecret = "__YOUR_SHARED_SECRET__";

// Set your environment
// Environment environment = Environment.LIVE;
Environment environment = Environment.TEST;

// Authenticate via (test)flex.cybersource.com
IFlexCredentials flexCredentials = new CyberSourceFlexCredentials(
	environment,
	merchantId,
	keyId,
	sharedSecret
);

Using credentials obtained through Visa Developer Center:

using FlexServerSDK;
using FlexServerSDK.Authentication;

/* ... */

// Replace with your credentials
string apiKey = "__YOUR_API_KEY__";
SecureString sharedSecret = "__YOUR_SHARED_SECRET__";

// Set your environment
// Environment environment = Environment.LIVE;
Environment environment = Environment.TEST;

IFlexCredentials flexCredentials = new VisaDeveloperCenterCredentials(
	environment,
	apiKey,
	sharedSecret
);

Initialize configuration (optional)

The Flex SDK supports configuration of the following:

• Request timeout: Duration in milliseconds for which the Flex SDK will wait for a response from Flex API. Default value: 10000 (10 seconds)
• Request proxy: A proxy through which to connect to Flex API. Default value: no proxy
• Debug logging: Turn on debug logging using the System.Diagnostics.Debug framework. Default value: false

int requestTimeout = ...;
IWebProxy proxy = ...;
bool enableDebugLogging = ...;

FlexServiceConfiguration flexServiceConfiguration = new FlexServiceConfigurationBuilder()
	.SetRequestTimeout(requestTimeout)
	.SetProxy(proxy)
	.SetDebugLoggingEnabled(enableDebugLogging)
	.Build();

Initialize Flex Service

IFlexCredentials flexCredentials = ...;
FlexServiceConfiguration flexServiceConfiguration = ...;

IFlexService flexService = FlexServiceFactory.Create(flexCredentials, flexServiceConfiguration);

Note: All IFlexService operations are thread-safe. For performance reasons it is recommended to initialize only one instance of IFlexService per unique set of Flex credentials.

Request a key

Flex encrypts the card number in transit, for additional protection against MitM attacks 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)

An encryption type must be supplied when requesting a key:

FlexPublicKey flexPublicKey = await flexService.CreateKey(EncryptionType.RsaOaep);

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:

FlexPublicKey flexPublicKey = await flexService.CreateKey(
	EncryptionType.RsaOaep, 
	"https://shop.merchant.com/" // Your website which will host Flex Microform
);

Additional optional settings may be supplied:

KeyRequestSettings settings = new KeyRequestSettings
{
	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
};

KeysRequestParameters keysRequestParameters = new KeysRequestParameters(
	EncryptionType.RsaOaep256,
	"https://shop.merchant.com",
	settings
);

Verify a token response

There is a possibility that the token response can be tampered with as it passes through the client. You should check the integrity of the response using the SDK. You can provide the public key and token response to the Flex SDK in one of the following formats:

FlexPublicKey flexPublicKey = ...; // The key with which the token was generated
string flexTokenResponseBody = ...; // The raw response body returned by Flex API

if (!flexService.Verify(flexPublicKey, flexTokenResponseBody)) 
{
	// Reject token
}

FlexPublicKey flexPublicKey = ...; // The key with which the token was generated
FlexToken flexToken = ...; // The raw response body returned by Flex API deserialized into a FlexToken instance

if (!flexService.Verify(flexPublicKey, flexTokenResponseBody)) 
{
	// Reject token
}

FlexPublicKey flexPublicKey = ...; // The key with which the token was generated
IDictionary<string, string> flexTokenResponseFields = ...; // A map containing the signed response fields and the signature itself

if (!flexService.Verify(flexPublicKey, flexTokenResponseBody)) 
{
	// Reject token
}