Search

Page tree
Skip to end of metadata
Go to start of metadata


PaymentGatewayBase class  has several methods and fields which are required to implement.

  • DisplayName: This is a user friendly name that will be used for labels from the interworks.cloud platform.
  • Category  : It is an enumeration type GatewayCategoryEnum and the available options are here.
  • Settings: This is a dictionary type (IDictionary<string, GatewaySetting>). It includes all the settings that the provider requires and they will be available in BSS Setup.
  • SettingsInstructions: The instructions that the user will see at Payment Gateway Setup page of interworks.cloud platform.A html descriptions that will be show in BSS Setup (right column).
  • GetTransaction: This method returns a <TransactionResponseDetails> object that includes information about the transaction.
  • GetTransactionByResponseData: This method returns a <TransactionResponseDetails> object that includes the information of the transaction based on the response data that comes from the Redirection URL response (Only for redirection methods).

    GetTransactionByResponseData comments..
               /* take a look here.
                   return new TransactionResponseDetails()
                    {
                        Result = new TransactionResult
                        {
                            IsSuccess = //boolean
                            ErrorCode = //if there is a code error,
                            ErrorMessage = //if there is an error message
                        },
                        TransactionPaymentId = //BSS id that is being used from both systems
                        TransactionId = //gateway’s transaction id
                        CreditCardMaskedNumber = //the masked number of the card
                        ExpirationMonth = //if it is available
                        ExpirationYear = //if it is available
                        CreditCardToken = //the token that will be saved in BSS
                    };        
  • PrepareTransaction: This method "prepares" the transaction and it must return a transaction token or a redirection URL based on the category.
  • ExecuteTransaction: This method executes the transaction. There is a request object that holds all the required info. It completes the payment and returns the result.
  • GetPublishableClientSideKey: This method is only for embedded client side forms. It returns the publishable key to communicate with the provider's bridge.

Payment Gateway Categories


As is mentioned above, interworks.cloud platform supports several payment gateway categories. Read the guidelines for every case:

1.TokenizationRedirection

This category only supports the following flow:

  • redirection to the external provider's page 
  • fill in the credit card details
  • redirect back to interworks.cloud platform to complete the transaction and keep the credit card's token.
    Required methods to implement 
  • GetTransactionByResponseData
  • GetTransaction
  • PrepareTransaction
  • ExecuteTransaction

IMPORTANT

1. It is required to return the RedirectionUrl in  PrepareTransactionResponse object of the PrepareTransaction method. Otherwise the redirection will not work! This Url is the gateway's external page

2. If the response data is being sent back to interworks.cloud platfrom in the URL as query string values for example:
<app_url>/PaymentHandlers/PaymentHandler.aspx /?type=<your_plugin_name>
you have to implement the GetTransactionByResponseData method that has as input these query string data values.The return url should contain also all the values you need that the method GetTransactionByResponseData


3. Callback Response URL (RedirectionURL)
When the payment is completed the gateway itself has to redirect to the static response handler page which is always:

<app_url>/PaymentHandlers/PaymentHandler.aspx?type=<your_plugin_name>
The gateway has to return the query string values that contain all results and then GetTransactionByResponseData of plugin will analyze the result.IMPORTANT - type=<your_plugin_name> must be exactly with this name pattern.

2.EmbeddedClientSideFormWithExternalUiElements

This category supports client-side form hosted at interworks.cloud platform and there is a js client side bridge between the provider to initialize the form.

Required methods to implement:

  • PrepareTransaction
  • ExecuteTransaction
  • GetPublishableClientSideKey

IMPORTANT

You have to provide The UI processor (for example SampleUiProcessor.js) that communicates with the provider's bridge to perform transactions. Read this part for more details and a ready template. This is a PCI Compliant payment gateway category as the form resides on the client's browser. Only the token is being kept for future transactions.Interworks.cloud platform saves only tokenization data to database.

Code Reference 



GatewayCategoryEnum
    public enum GatewayCategoryEnum
    {
        Unknown = 0,
        IFrameForm,
        SimpleRedirection,
        TokenizationRedirection,
        EmbeddedClientSideFormWithExternalUiElements,
        EmbeddedClientSideFormWithPredefinedUiElements
    }

 GatewayCategoryEnum documentation

IFrameForm : This category includes payment gateways that serves an iframe for the customer's credit card info. Interwork.cloud platform opens this iframe.

SimpleRedirection: This category includes payment gateways that redirects to the gateway's provider page to fill the the customer's credit card info. Interwork.cloud platform show a button to redirect to the provider's page

TokenizationRedirection: This category includes payment gateways that redirects to the gateway's provider page to fill the the customer's credit card info. After that this category supports a token that represents a credit card. Interwork.cloud platform show a button to redirect to the provider's page and then keeps the token to platform's database for future transactions.

EmbeddedClientSideFormWithExternalUiElements: This category includes payment gateways that supports a client-side form (html and javascript) that is served by interworks.cloud platform. The html comes directly from the provider's js bridge and interworks.cloud platform only creates html containers (div elements).

EmbeddedClientSideFormWithPredefinedUiElements: This category includes payment gateways that supports a client-side form (html and javascript) that is served by interworks.cloud platform. The html part is created from interworks.cloud platform and the whole credit card form is a custom user control.

Gateway Setting class definition
    public partial class GatewaySetting
    {
        public string Label { get; set; }         
        public string Id { get; set; }       
        public string Value { get; set; }      
        public GatewaySettingType Type { get; set; }      
    }
 GatewaySetting documentation

Label: The user-friendly label name of the settings. For example, "Api Username".

Id: The id that will be saved at interworks.cloud platform. For example, "api_username".

Value: The value of the settings.Leave it blank as it will be filled by interorks.cloud platform setup page.

Type: The type of the settings.Text or boolean to represent a text input or a checkbox ui elements at settings page. 

Gateway Setting Type enum:
    public enum GatewaySettingType
    {
        Text = 0,
        Boolean
    }


TransactionResponseDetails
	public class TransactionResponseDetails 
    {
        public TransactionResponseDetails()
        {
            Result = new TransactionResult();
        }

        public TransactionResult Result;
        public Guid TransactionPaymentId { get; set; }             
        public string TransactionId;          
        public decimal Amount { get; set; }  
        public string CreditCardToken { get; set; }
        public string CurrencyCode { get; set; }         
        public string CreditCardMaskedNumber;               
        public string ExpirationMonth;        
        public string ExpirationYear;   
        public string ExtraInfo; 
    }
 TransactionResponseDetails documentation

Result: A transaction result object.

TransactionPaymentId: This is the PaymentId from the interworks.cloud platform.It is the communicator between interworks.cloud platform and the provider's service.

Amount: The amount of the transaction. It is decimal type and conversions may be needed in plugin's implementation.

CreditCardToken: Represents the credit card token.

ExtraInfo: For some extra string info to pass

TransactionResult
    public class TransactionResult
    {   
        public TransactionResult()
        {
            IsSuccess = false;
            ErrorCode = string.Empty;
            ErrorMessage = string.Empty;            
        }

        public bool IsSuccess;
        public string ErrorMessage;
        public string ErrorCode;
    }


PrepareTransactionResponse
    public class PrepareTransactionResponse : TransactionResponseDetails
    {
        public string RedirectionUrl;  
    }
 PrepareTransactionResponse documentation

RedirectionUrl: The url that interworks.cloud platform will use to redirect.The provider's credit card's info page.


ExecuteTransactionResponse
    public class ExecuteTransactionResponse : TransactionResponseDetails {}


TransactionRequestDetails
    public class  
    {
        public TransactionRequestDetails()
        {
            Result = new TransactionResult();
        }

        public TransactionResult Result;
        public Guid TransactionPaymentId { get; set; }             
        public string TransactionId; 
        public decimal Amount { get; set; }  
        public string CreditCardToken { get; set; }
        public string CurrencyCode { get; set; }         
        public string CreditCardMaskedNumber;               
        public string ExpirationMonth;        
        public string ExpirationYear;   
        public string ExtraInfo; 
        public string CustomerName { get; set; }
        public string CustomerEmail { get; set; }
    }
 TransactionRequestDetails documentation

CustomerNameSome providers requires the customer's name.

CustomerEmailSome providers requires the customer's email


PrepareTransactionRequest
    public class PrepareTransactionRequest : TransactionRequestDetails
    {
        public string transactionToken;
    }


ExecuteTransactionRequest
    public class ExecuteTransactionRequest : TransactionRequestDetails
    {
        public string ExtraCode;
    }

GatewayCategoryEnum.EmbeddedClientSideFormWithExternalUiElements Code Example
var PaymentGatewayProcessor = {};

var SampleUiProcessor = function () {
    var _that = this;
    
    this.PublishableClientSideKey = "";
    this.GatewayObject = null;
    this.CreditCardObject = null;
    this.OnInitForm = function () { };
    this.StartLoader = function () { };
    this.StopLoader = function () { };
    this.OnSaveSuccess = function (saveResult) { };
    this.OnSaveFailed = function (messsage) { };
    this.CreditCardTokenData = {
        token: "",
        maskedNumber: "",
        expirationYear: "",
        expirationMonth: ""
    };
}

StripeUiProcessor.prototype.ApiBridgeUrl = "https://<the_bridge_js_url>";
StripeUiProcessor.prototype.AmountValue = "";
StripeUiProcessor.prototype.CurrencyValue = "";
StripeUiProcessor.prototype.ErrorDivSelector = "";

//If it is for EmbeddedClientSideFormWithExternalUiElements.Otherwise no implementation is needed
StripeUiProcessor.prototype.EmbeddedHtmlContainer = "<script src='\'>/*may needed to load bridge by this way*/script>\
    <div class='form-row'> \
    <label for='card-element'>\
    </label>\
    <div id='card-element'>\
    </div>\
    <div id='card-errors'></div>\
  </div>";

StripeUiProcessor.prototype.InitForm = function () {
    this.CleanFormData();
    this.CleanFormErrors();
    this.OnInitForm();
    this.StopLoader();
};

StripeUiProcessor.prototype.LoadClientSideBridge = function () {
    _this = this;
    $.getScript(this.ApiBridgeUrl, function (data, textStatus, jqxhr) {
    }).done(function () {
        _this.GatewayObject = /*mount and initialization of the gateway instance object*/;
    })
};

StripeUiProcessor.prototype.SetAmountAndCurrency = function (amount, currency) {
    this.AmountValue = amount;
    this.CurrencyValue = currency;
}

StripeUiProcessor.prototype.CleanFormData = function () { };

StripeUiProcessor.prototype.IsValidForm = function () {
    this.CleanFormErrors();    
    return true;
};

StripeUiProcessor.prototype.CleanFormErrors = function () {
    $(this.ErrorDivSelector).hide();
    $(this.ErrorDivSelector).html('');
}

StripeUiProcessor.prototype.ShowError = function (errorMessage) {
    this.CleanFormErrors();
    $(this.ErrorDivSelector).html(errorMessage);
    $(this.ErrorDivSelector).show();
}

StripeUiProcessor.prototype.CreateCreditCardToken = function () {
    var _this = this;

    this.CleanFormErrors();
    this.StartLoader();

    //integrate with the gateway to create a token..
	//for example...if the gateway has a create token function
    _this.GatewayObject.createToken(_this.CreditCardObject).then(CreateTokenResponseHandler);
}

//This is the Create token response handler after the CreateCreditCardToken was completed...
function CreateTokenResponseHandler(result) {
    _this.CleanFormErrors();
    if (result.error) {
        _this.ShowError(result.error.message);
        _this.StopLoader();
    }
    else {
		//You have to fill in the CreditCardTokenData .For example something like this (check your result's correspondent definition)
        _this.CreditCardTokenData.token = result.token.id;        
        _this.CreditCardTokenData.maskedNumber = result.token.card.last4;        
        _this.CreditCardTokenData.expirationMonth = result.token.card.exp_month;
        _this.CreditCardTokenData.expirationYear = result.token.card.exp_year;

        // Send the token to your server
        //through this client-side form
		//This method lives in interworks.cloud platform
        CreditCardTokenHandler(_this.CreditCardTokenData);
    }
}

//Important
$(document).ready(function () {
    PaymentGatewayProcessor = new StripeUiProcessor();
})

Table of Contents


Download SDK with Sample Project


Download payment gateway integration framework SDK's  ready sample project (that already references to the SDK) to get started (Project's Framework is .NET Framework 4.5.2):

Interworks.Plugin.PaymentGateways.Sample.zip

Download SDK only


Download payment gateway integration framework SDK's assemblies:

Interworks.SDK.PaymentGateways.zip


Table of Contents


  • No labels