This article describes the steps needed to implement a Payment Gateway plugin for SDK v2.0 that is using a redirection flow.
At the time of writing this document the SDK is migrating from v1.0 to v2.0. This means that some implementation is still needed using the v1.0 SDK. More specific you need to create a project that is used by the BSS's Setup in order for the user to configure the gateway (written using SDK v1.0) and a project to be used to process any transactions with the gateway, commonly known as the Processor (written using SDK v2.0).
Creating the Processor project (SDK v2.0)
- Create a new C# Class Library Project (.NET Framework). Use the naming convention for the namespace and project name "
- Create a new folder in vs solution to add the following DLLs. These libraries should be provided by interworks.cloud. (on-premises installations collect DLLs from bin folder of BSS)
- Iwcp.SDK.PaymentGateways.dll (SDK v2.0 for creating the processor)
- Interworks.SDK.PaymentGateways.dll (SDK v1.0 for supporting the setup of payment gateway on BSS)
- Create the Processor class that will be used by the SDK to complete transactions with the gateway. We recommend using a naming convention "<Gateway Name>Processor.cs".
- Add reference Iwcp.SDK.PaymentGateways in the processor project. In our example we have copied the libraries to a folder with libs' name.
- Enable the gateway for the SDK to discover it. You need to decide a display name and a gateway type for your gateway. The display name should be meaningful and reflect the commercial name of the gateway ie. My Foo Gateway. The gateway type should be all lower-case and hyphen separated ie. "my-foo-gateway".
On-premises installations. Run the following query in your working DB
- Otherwise, contact interworks.cloud to enable the plug-in
Extend your class from
Iwcp.SDK.PaymentGateways.DefaultProcessor. This will give your Processor some basic functionality such as logging support via
Trace. Decorate the class using a
PaymentGatewayattribute so that the Processor will be discovered by the SDK. The name used in the attribute must match the gateway type used in the previous steps.
- Implement the interface
Iwcp.SDK.PaymentGateways.Interfaces.IRedirection. This is the interface used by the Redirection flow. The interface serves the "on-session" transactions. The "on-session transaction" is a transaction with a user present, usually during a basket checkout procedure. Also the "on-session" transaction may or may not produce a token for future re-curring charges. A redirection flow always has two phases. The "before" (
PrepareTransaction) and "after" (
PrepareTransaction -The first phase is the communication with the gateway, like a "hand-shake", which is established right before the user's agent is redirected to the gateway's website. At this point the two parties exchange some inrfomation about the imminent transaction such as the amount, currency, buyer details etc. After a successful
PrepareTransactionthe user will be redirected to the designated URL by the
TransactionRedirectResponse. He will confirm his Credit Card details and commit the transaction. At this point the gateway's website will redirect the user back at the designated URL by the Processor by the
TransactionRedirectResponseor in some cases directly configured on the gateway's portal, passing a transaction token and/or the transaction result in the query params.
VerifyTransaction -When redirected-back the
VerifyTransactionwill be invoked by the SDK passing the query params in the
TransactionStatusRequest. Use the query params to communicate with the gateways, determine the result of the transaction and return a
TransactionStatusResponse. At this point if a token was generated for re-curring charges return it so it can be persisted for future use. If not return
ExecuteTransaction- If your gateway tokenizes Credit Cards for re-curring charges you need to implement the
ExecuteTransactionmethod. This method is part of the "off-session" transaction interface. An "off-session transaction" is considered a transaction that takes place without a user present, usually used for recurring charges from our Billing engine. When this method is invoked you will have access to the previously generated and persisted token so you can use it to complete the transaction. If your gateway doesn't tokenize credit cards you can leave the method body empty, it will not be invoked by the SDK.
ValidateSettings- For convience the SDK will call this method right before invoking any of the aforementioned methods. You can write here any validation logic and throw exceptions if your criteria are not met.
- Copy the generated DLL(in our example is Iwcp.PaymentGateways.FooGateway.dll) to bin folder in the Marketpalce V4.0.
If the payment gateway returns some error, you can throw a PaymentGatewayException so that the error to be logged and displayed on the UI.
- Create the gateway's "Processor" project
- Update the DB with the gateway's name and type
- Implement the appropriate interfaces of the Processor
- Copy the generated DLL to bin folder in the Marketpalce V4.0 and installation folder of billing service for on-premises installations or contact interworks.cloud.
Creating the BSS Setup project
- Create a new C# Class Library Project (.NET Framework). Use the naming convention for the namespace and project name "Iwcp.PaymentGateways.SetupOptions
Interworks.SDK.PaymentGatewaysas a reference.
- Create a new class that will be used by the BSS for setting payment gateway. We recommend using a naming convention "PaymentGatewaySetupOptions<GatewayName>".
- Implement the interface ISetupOptionsUI from
Implement OnInit method.
- Copy the generated DLL(in our example is Iwcp.PaymentGateways.SetupOptions.FooGateway.dll) to bin folder in the BSS for on-premises installations or contact interworks.cloud.
The source code of example is attached to the following file.
Enable the logger on payment gateways, adding a new rule on NLog.config file of application. The new rule is <logger name="Iwcp.SDK.PaymentGateways*" writeTo="DB" minLevel="Trace"/>.