Storefront Emulator

When you are developing a plug-in for the interworks.cloud platform you will soon find the need to test your implementation. You can make this happen easily by using the Storefront Emulator. The Emulator is a lightweight mocked Storefront that enables you to load your code and debug it just like it was loaded in the Storefront but with the perks that come with a mocked environment, such as ease of deployment, short load times (no DB is needed, no activation, etc) and more.

Step-by-step guide

Download  the Emulator

The Emulator is simply a web app solution with some example projects included. Download the solution, extract it and open it with Visual Studio:

Projects structure

The Solution already contains some example projects. Depending on the type of the plugin and its needs, the projects you need to build vary.

Configuring the Emulator

Out-of-the-box the Emulator comes with some basic data to get you started. These data are persisted in the file named “Storage.json”. If you delete this file it will be recreated with these basic data. You can edit the storage file to configure the emulator to your needs.

Please note that this file acts as a local DB, so it is normal for the Emulator to update it constantly while you use it, ie when making a payment a record for the payment is appended. Keep this in mind if you keep this file under version control.

When editing the file you should restart the application in order for the Emulator to load the changes; otherwise, it will throw an exception if it detects changes from the User.

{
  "application": {
    "path": "https://localhost:44331/"
  },
  "paymentGateways": [
    {
      "id": "1",
      "name": "Foo Redirect",
      "type": "foo-redirect",
      "settings": {
        "LiveMode": 0,
        "IsActive": 1,
        "fooUsername": "JohnDoe",
        "fooPassword": "Password"
      }
    }
  ],
  "paymentMethods": [
    {
      "id": "8726A22B-878B-4100-8CB0-51327FA74363",
      "name": "Foo Redirect",
      "gatewayId": "1"
    },
    {
      "id": "DD2CD1FC-772C-46EE-9F7A-6D8D583DAD8F",
      "name": "DPO Redirect",
      "gatewayId": "2"
    },
    {
      "id": "11C188F2-3694-40C9-B140-4F4CC84BF0A6",
      "name": "Paypal",
      "gatewayId": "3"
    }
  ],
  "organization": {
    "name": "Emulator Organization"
  },
  "account": {
    "id": 1,
    "name": "Emulator Account",
    "companyName": "Emulator Company",
    "email": "[email protected]",
    "phone": "1234567890",
    "profileId": "",
    "paymentMethodId": "8726A22B-878B-4100-8CB0-51327FA74363",
    "currencyId": "1CF82613-4DEC-4AA4-B4C7-BB172CF2699C",
    "contact": {
      "id": 100,
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    },
    "billing": {
      "address": {
        "address": "Metropolitan Ave 71",
        "address2": "",
        "city": " New York City",
        "state": "New York State",
        "country": "USA",
        "countryCode": "NY",
        "zipCode": "11379"
      }
    }
  },
  "currentUser": {
    "id": 1,
    "language": "en-US"
  },
  "storefront": {
    "paymentMethodId": "8726A22B-878B-4100-8CB0-51327FA74363"
  },
  "currencies": [
    {
      "id": "1CF82613-4DEC-4AA4-B4C7-BB172CF2699C",
      "name": "US Dollar",
      "sign": "$",
      "code": "840",
      "mnemonic": "USD",
      "decimals": 2,
      "decimalSeparator": ".",
      "groupSeparator": ",",
      "positivePattern": "$ n",
      "negativePattern": "-$ n"
    },
    {
      "id": "25CF77B5-5B6C-4F83-B7F6-CC18B241E45C",
      "name": "Euro",
      "sign": "€",
      "code": "978",
      "mnemonic": "EUR",
      "decimals": 2,
      "decimalSeparator": ",",
      "groupSeparator": ".",
      "positivePattern": "$ n",
      "negativePattern": "-$ n"
    }
  ],
  "strings": {
    "lblGPPaymentAccepted": "\"Your payment of <span class=\"gpAmountThatPaid\"></span> has been accepted!\"",
    "lblGPReceiveConfirmation": "You will receive a confirmation email for your payment.",
    "lblClose": "Close",
    "lblCancel": "Cancel",
    "lblPay": "Pay",
    "lblSelectHowToPayInAddCreditLimit": "You can pay either using an existing Credit card from your selected Payment Gateway or by using a new Credit card",
    "lblNewCreditCard": "New Credit Card",
    "lblNewBankAccount": "New Bank Account",
    "lblSaveAndPay": "Save and Pay"
  },
  "paymentProfiles": [],
  "payments": []
}

The Storage tries to mimic the real DB structure to emulate a live environment as close as possible. So you need to make your self familiar with some concepts of the Platform.

• Application – Setting the correct path is mandatory. Otherwise, you will end-up with 404 errors or redirecting the User to incorrect URLs.
• Account – This would be the user’s account used throughout the Emulator. You can set here which Currency the account uses to make any payments and which Payment Method of the ones setup. You may setup multiple Payment Methods and easily change the selected one by just editing the Account’s config.
• Payment Gateways – The “adapter” between our Platform and third-party systems to communicate with and charge a Credit Card. Here you should add your own with any settings needed for the API to function properly.
• Payment Methods – A Payment Method is how the Account will pay for goods. In a real environment, a Payment Method can be Cash, Bank Deposit or some Payment Gateway. For the Emulator only the Payment Gateway option is available since the others are not really useful for any development cases. You should add a new Payment Method associating it with the Payment Gateway you wish to develop for and give it a descriptive name. Otherwise, you can keep an existing Payment Method and just change its associated Payment Gateway.
• Organization – The “umbrella” under all Accounts live.
• Current User – The id and selected language of the current user.
• Currency – A Currency should be configured according to ISO4217 standards because it is used by the Payment Gateways and should adhere to the correct codes and mnemonics of a real currency. You can add as many as you want but only the one set in the Account will be used in the transactions.
• Storefront – For reasons that are beyond the scope of this article you should set the Storefront paymentMethodId to point to the Payment Method you wish to test. 
• Strings – A collection of text/strings that are used for internationalization (i18n). If you are going to make use of our Platform i18n you should place here any strings you need.
• Payment Profiles – A Payment Profile is an abstract idea of a saved Credit Card or Bank Account or whatever that is saved and used for recurring charges. As you play with the Emulator, any saved profiles will appear under this node. You can delete the list if it’s getting large.
• Payments – A Payment is considered a transaction that is initiated for a specific amount and currency in order to charge a Credit Card or Bank Account or any other mean. Any initiated payments and their status will appear under this node. You can use this list to debug your implementation. You can delete the list if it’s getting large.

Always prefix your keys with a word related to your plugin; i.e. instead of “lblHelloWorld” use something like “myplugin_HelloWorld”. This will help avoid collisions with other plugins

Testing your code

Hit “Run – F5” in Visual Studio →  ( Chrome will open… ) -> Select the module you are developing a plugin for.