Skip to content

README_NetCore.md

Latest commit

 

History

History
257 lines (174 loc) · 11.2 KB

README_NetCore.md

File metadata and controls

257 lines (174 loc) · 11.2 KB

.NET Core Sample Code for the CyberSource SDK

This repository contains working code samples which demonstrate .NET Core integration with the CyberSource REST APIs through the CyberSource .NET Standard SDK.

Using the Sample Code

The samples are all completely independent and self-contained. You can analyze them to get an understanding of how a particular method works, or you can use the snippets as a starting point for your own project.

Requirements

The samples are organized into categories and common usage examples.

Caveats

  • Remember to add the installation path for the .NET Core/.NET Standard to the PATH environment variable.

Running the Samples

Windows OS

  • Clone this repository

    git clone https://github.com/CyberSource/cybersource-rest-samples-csharp.git

  • Open the solution cybersource-rest-samples-netcore.sln in Visual Studio 2019 and perform a clean build.

  • Run the console app and select a sample to execute.

    The console app can be executed from the Debug menu in Visual Studio 2019.

    Alternatively, the console app can also be executed from command prompt, run the following command.

    dotnet bin\Debug\netcoreapp3.1\SampleCodeNetCore.dll

Linux / Mac OS

  • Clone this repository.

    git clone https://github.com/CyberSource/cybersource-rest-samples-csharp.git

  • Change directory to cybersource-rest-samples-netcore folder.

    cd cybersource-rest-samples-netcore

  • Clean the bin folder to remove any previous build (if applicable).

    rm -r -f bin/*

  • From the root directory of the repository, run the following command:

    dotnet publish -c <configuration> -r <RID> --self-contained

  • In this command,

    • For <configuration>, accepted values are Debug and Release.

    • For <RID>, refer to .NET Core RID Catalog to find the proper Runtime Identifier (RID).

    • This determines the location of the output files ( bin/<configuration>/netcoreapp3.1/<RID>/publish ).

  • Move the output files from bin/<configuration>/netcoreapp3.1/<RID>/publish to bin/<configuration>/netcoreapp3.1.

    mv bin/<configuration>/netcoreapp3.1/<RID>/publish/* bin/<configuration>/netcoreapp3.1

  • Linux : Provide execute permissions for the DLL.

    chmod 777 bin/<configuration>/netcoreapp3.1/SampleCodeNetCore.dll

  • Execute the console app and select a sample to execute.

    • Linux

      ./bin/<configuration>/netcoreapp3.1/SampleCodeNetCore.dll

    • Mac OS

      dotnet bin/<configuration>/netcoreapp3.1/SampleCodeNetCore.dll

Setting Your API Credentials

To set your API credentials for an API request, configure the following information in Source\Configuration.cs file:

  • Http

    authenticationType  = http_Signature
merchantID          = your_merchant_id
merchantKeyId       = your_key_serial_number
merchantsecretKey   = your_key_shared_secret
useMetaKey          = false
enableClientCert    = false

  • Jwt

    authenticationType  = Jwt
merchantID          = your_merchant_id
keyAlias            = your_merchant_id
keyPassword         = your_merchant_id
keyFileName         = your_merchant_id
keysDirectory       = Resource
useMetaKey          = false
enableClientCert    = false

  • MetaKey Http

      authenticationType  = http_Signature
  merchantID          = your_child_merchant_id
  merchantKeyId       = your_metakey_serial_number
  merchantsecretKey   = your_metakey_shared_secret
  portfolioId         = your_portfolio_id
  useMetaKey          = true
  enableClientCert    = false

  • MetaKey JWT

      authenticationType  = Jwt
  merchantID          = your_child_merchant_id
  keyAlias            = your_child_merchant_id
  keyPassword         = your_portfolio_id
  keyFileName         = your_portfolio_id
  keysDirectory       = Resource
  useMetaKey          = true
  enableClientCert    = false
    • OAuth

    CyberSource OAuth uses mutual authentication. A Client Certificate is required to authenticate against the OAuth API.

    Refer to Supporting Mutual Authentication to get information on how to generate Client certificate.

    If the certificate (Public Key) and Private Key are in 2 different files, merge them into a single .p12 file using openssl.

    openssl pkcs12 -export -out certificate.p12 -inkey privateKey.key -in certificate.crt

    Set the run environment to OAuth enabled URLs. OAuth only works in these run environments.

    // For TESTING use
_configurationDictionary.Add("runEnvironment", "api-matest.cybersource.com")
// For PRODUCTION use
// _configurationDictionary.Add("runEnvironment", "api-ma.cybersource.com")

    To generate tokens, an Auth Code is required. The Auth Code can be generated by following the instructions given in Integrating OAuth.

    This generated Auth Code can then be used to create the Access Token and Refresh Token.

    In Source/Configuration.cs file, set the following properties.

    Note that authenticationType is set to MutualAuth only to generate the Access Token and the Refresh Token.

    authenticationType  = MutualAuth
enableClientCert    = true
clientCertDirectory = resources
clientCertFile      = your_client_cert in .p12 format
clientCertPassword  = password_for_client_cert
clientId            = your_client_id
clientSecret        = your_client_secret

    Once the tokens are obtained, the authenticationType can then be set to OAuth to use the generated Access Token to send requests to other APIs.

    authenticationType  = OAuth
enableClientCert    = true
clientCertDirectory = resources
clientCertFile      = your_client_cert - .p12 format
clientCertPassword  = password_for_client_cert
clientId            = your_client_id
clientSecret        = your_client_secret
accessToken         = generated_access_token
refreshToken        = generated_refresh_token

    The Access Token is valid for 15 mins, whereas the Refresh Token is valid for 1 year.

    Once the Access Token expires, use the Refresh Token to generate another Access Token.

    Refer to StandAloneOAuth.cs to understand how to consume OAuth.

    For further information, refer to the documentation at Cybersource OAuth 2.0.

Switching between the sandbox environment and the production environment

CyberSource maintains a complete sandbox environment for testing and development purposes. This sandbox environment is an exact duplicate of our production environment with the transaction authorization and settlement process simulated. By default, this SDK is configured to communicate with the sandbox environment. To switch to the production environment, set the appropriate environment constant in Source\Configuration.cs file. For example:

    // For TESTING use
    _configurationDictionary.Add("runEnvironment", "apitest.cybersource.com");
    // For PRODUCTION use
    // _configurationDictionary.Add("runEnvironment", "api.cybersource.com");

To use OAuth, switch to OAuth enabled URLs

    // For TESTING use
    _configurationDictionary.Add("runEnvironment", "api-matest.cybersource.com")
    // For PRODUCTION use
    // _configurationDictionary.Add("runEnvironment", "api-ma.cybersource.com")

The API Reference Guide provides examples of what information is needed for a particular request and how that information would be formatted. Using those examples, you can easily determine what methods would be necessary to include that information in a request using this SDK.

Logging

Generic badge

Since v0.0.1.7, a new logging framework has been introduced in the SDK. This new logging framework makes use of NLog, and standardizes the logging so that it can be integrated with the logging in the client application.

More information about this new logging framework can be found in this file : Logging_NetCore.md

Disclaimer

Cybersource may allow Customer to access, use, and/or test a Cybersource product or service that may still be in development or has not been market-tested (“Beta Product”) solely for the purpose of evaluating the functionality or marketability of the Beta Product (a “Beta Evaluation”). Notwithstanding any language to the contrary, the following terms shall apply with respect to Customer’s participation in any Beta Evaluation (and the Beta Product(s)) accessed thereunder): The Parties will enter into a separate form agreement detailing the scope of the Beta Evaluation, requirements, pricing, the length of the beta evaluation period (“Beta Product Form”). Beta Products are not, and may not become, Transaction Services and have not yet been publicly released and are offered for the sole purpose of internal testing and non-commercial evaluation. Customer’s use of the Beta Product shall be solely for the purpose of conducting the Beta Evaluation. Customer accepts all risks arising out of the access and use of the Beta Products. Cybersource may, in its sole discretion, at any time, terminate or discontinue the Beta Evaluation. Customer acknowledges and agrees that any Beta Product may still be in development and that Beta Product is provided “AS IS” and may not perform at the level of a commercially available service, may not operate as expected and may be modified prior to release. CYBERSOURCE SHALL NOT BE RESPONSIBLE OR LIABLE UNDER ANY CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE RELATING TO A BETA PRODUCT OR THE BETA EVALUATION (A) FOR LOSS OR INACCURACY OF DATA OR COST OF PROCUREMENT OF SUBSTITUTE GOODS, SERVICES OR TECHNOLOGY, (B) ANY CLAIM, LOSSES, DAMAGES, OR CAUSE OF ACTION ARISING IN CONNECTION WITH THE BETA PRODUCT; OR (C) FOR ANY INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES INCLUDING, BUT NOT LIMITED TO, LOSS OF REVENUES AND LOSS OF PROFITS.

License

This repository is distributed under a proprietary license.