Installation


Pre-Installation

The customer needs to complete the following tasks to fully install this product. The yellow highlighted text indicates values that need to be captured for the installation. The text states the Installation Section and Input Field Name where the value will be input. The blue highlighted text is to emphasize certain information.

  1. If you would like this product to support text (mobile) notifications for the cardholders, create a Twilio account and acquire a phone number for card-holder mobile notification.
    • To get started, go to Twilio’s website (https://www.twilio.com/) and click the ‘SignUp’ button found in the upper right corner.
    • Twilio information will map to the following installation input fields: (Notification Configuration : Twilio Account SID), (Notification Configuration : Twilio Account Token), (Notification Configuration : Twilio From Phone Number)
  2. If you do not already have them, obtain credit card processor credentials for one or more of the following:
    • Cayan
    • CyberSource
    • Chase Orbital
  3. This installation will create a StagedPay Portal app service and a StagedPay API app service.
    • Determine the name of the Portal app service. This must be an Azure globally unique name. An example might be yourCompanyNameStagedPayPortal. (Application Configuration : StagedPay Portal App Service Name)
    • Determine the name of the API app service. This must be an Azure globally unique name. An example might be yourCompanyNameStagedPayAPI. (Application Configuration : StagedPay API App Service Name)
    Remember, these must be a globally unique names.
  4. Determine your url for the Portal app service. Your url will either be https://{portal_appservicename}.azurewebsites.net (replacing {portal_appservicename} with the name you determined in the previous step) OR a custom url as specified in the CNAME settings (see below). 
    This url, minus the protocol identifier: ‘http:// or https://’, will be the input for the following installation fields: (Application Configuration : StagedPay Portal Url Domain) and (SSL Certificate Configuration : Certificate Root Host Name).
  5. Register a new application in the Microsoft developer console for Microsoft account logins:
    • View this document for reference but the instructions are listed here.
    • Navigate to the My Applications page in the Microsoft Account Developer Center
    • Click ‘Add an app’, type in an application name and click Create
    • Make a note of the Application ID as you will need it for the installation. (Authentication Configuration : Microsoft Application ID)
    • Under “Platforms”, click Add Platform and select ‘Web’.
    • Under ‘Redirect URIs’, supply the endpoint for your application. This will be the Portal URL determined in a previous step appended with ‘/signin-microsoft’.
    • Click Save
    • Under ‘Application Secrets’, click Generate New Password. Make a note of the value that appears as you will need it for the installation. (Authentication Configuration : Microsoft Password)
  6. Register a new application in the Google developer console for Google account logins:
  7. If you plan to have a custom url for the StagedPay Portal app service that will be installed, for example: ‘http://stagedpay.yourdomain.com’ instead of ‘http://appservicename.azurewebsites.net’, you will need to complete the following:
    • Add a CNAME record in the DNS Registrar that maps the custom domain to the Azure URL. This must be done before installing the product for the installation process to complete the proper SSL bindings to the app service.
      • Example if the custom url is ‘http://stagedpay.yourdomain.com’ and your app service name is ‘companyStagedPayPortal’, the CNAME record values will be:
        • ‘Type’: ‘CNAME’
        • ‘Host’: ‘stagedpay’
        • ‘Value’: ‘companyStagedPayPortal.azurewebsites.net’
          • The first segment of this value (in this case ‘companyStagedPayPortal’’) must be the name of the StagedPay Portal App Service you specify during the installation. Therefore, this first segment MUST be a globally unique app service name.
  8. The installation will create a Standard SSL Certificate if selected during the installation. This requires an Azure Key Vault to store the certificate. If you do not already have an Azure Key Vault, you need to create one before installing the product.
    • After creating the key vault or on your existing key vault, please ensure the following:
      • Open advanced access policies and enable access to Azure Resource Manager for template deployment.
      • Add a new access policy for principal Microsoft.Azure.CertificateRegistration
        • Secret permissions: Get, Set, Delete
      • Add a new access policy for principal Microsoft Azure App Service
        • Secret permissions: Get
    Retrieve the key vault id as it will be needed during the installation. In the Azure portal, open the Key Vault and click on the ‘Properties’ link on the left side. Copy the Resource ID value and paste it in this field. (SSL Certificate Configuration : Existing Key Vault Id)
  9. Register the Staged Pay API app service with Azure Active Directory (https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad#adding-an-application )
    • Determine your API app service url. This will be the API app service name determined in the previous step, concatenated with '.azurewebsites.net'. Example: 'http://companyNameStagedPayAPI.azurewebsites.net'. You will use this to configure your Azure Active Directory app registration.
    • Navigate to Active Directory, then select the App registrations, then click New application registration at the top to start a new app registration.
    • In the Create page, enter a Name for your app registration, select the 'Web App / API' application type, in the Sign-on URL box paste the API app service URL. Then click to Create.
    • In a few seconds, you should see the new app registration you just created.
    • Once the app registration has been added, click on the app registration name, click on Settings at the top, then click on Properties
    • In the App ID URI box, paste in the API app service URL. Also in the Home Page URL, paste in the API app service URL. Then click Save
    • Now click on the Reply URLs, edit the Reply URL, paste in the API app service URL, modify the protocol to make sure you have https:// protocol (not http://), then append the following to the end of the URL: /.auth/login/aad/callback (For example, https://companyNameStagedPayAPI.azurewebsites.net/.auth/login/aad/callback). Click Save.
    • At this point, copy the Application ID for the app. Keep it for later use. You will need for the API App Registration Application ID value during the installation process. (Application Configuration : StagedPay API App Registration Application ID)
  10. Create Key for StagedPay Web API
    • If not already there, in the Azure Portal, navigate to Azure AD, then select App registration and find and open the entry just created for the Staged Pay API service.
    • Open the app registration Settings page by clicking on Settings at the top, then click on Keys
    • In the Passwords section, enter a Description, select ‘Never expires’ and click Save at the top.
    • Copy the Value that is displayed. You will need this for the API App registration Application Secret value in the installation process. (Application Configuration : StagedPay API App Registration Application Secret)
  11. Add permission for the StagedPay Web API to access Microsoft Graph – Send email as any user
    • If not already there, in the Azure Portal, navigate to Azure AD, then select App registration and find and open the entry created for the Staged Pay API service.
    • Open the app registration Settings page by clicking on Settings at the top, then click on Required Permissions
    • Click Add at the top
    • Click Select an API
    • click on ‘Microsoft Graph’ and click the Select button
    • Click Select permissions
    • Scroll down and select ‘Send mail as any user’ and click the Select button
    • Click the Done button
  12. Register the Staged Pay Portal app service with Azure Active Directory (https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad#adding-an-application)
    • Recall the Portal app service url determined previously
    • Determine your Default Portal app service url. This will be the Staged Pay Portal app service name determined in a previous step, concatenated with '.azurewebsites.net'. Example: 'http://companyNameStagedPayPortal.azurewebsites.net'. You will use this to configure your Azure Active Directory app registration.
    • Navigate to Active Directory, then select the App registrations, then click New application registration at the top to start a new app registration.
    • In the Create page, enter a Name for your app registration, select the 'Web App / API' type, in the Sign-on URL box paste the Portal app service Url. Then click to Create.
    • In a few seconds, you should see the new app registration you just created.
    • Once the app registration has been added, click on the app registration name, click on Settings at the top, then click on Properties
    • In the App ID URI box, paste in the Portal app service Url. Also in the Home Page URL, paste in the Portal app service Url. Then click Save
    • Now click on the Reply URLs, edit the Reply URL, paste in the Default Portal app service url. Modify the protocol to make sure you have https:// protocol (not http://), then append the following to the end of the URL: /.auth/login/aad/callback (For example, https://companyNameStagedPayPortal.azurewebsites.net/.auth/login/aad/callback). Click Save.
    • Add another reply url, just like the first. Replace /.auth/login/aad/callback with /signin-oidc. ( For example, https://companyNameStagedPayPortal.azurewebsites.net/signin-oidc). Click Save.
    • At this point, copy the Application ID for the app. Keep it for later use. You will need for the Portal App registration Application ID value during the installation process. (Application Configuration : StagedPay Portal App Registration Application ID)
  13. Create Key for StagedPay Portal
    • If not already there, in the Azure Portal, navigate to Azure AD, then select App registration and find and open the entry just created for the Staged Pay Portal service.
    • Open the app registration Settings page by clicking on Settings at the top, then click on Keys
    • In the Passwords section, enter a Description, select ‘Never expires’ and click Save at the top.
    • Copy the Value that is displayed. You will need this for the Portal App registration Application Secret value in the installation process. (Application Configuration : StagedPay Portal App Registration Application Secret)
  14. Modify the StagedPay Portal application manifest to include the Administrator role
    • If not already there, in the Azure Portal, navigate to Azure AD, then select App registration and find and open the entry created for the Staged Pay Portal service.
    • Click on Manifest at the top
    • In the manifest, find "appRoles" property and set it to this, then click the Save button at the top:

      "appRoles": [ { "allowedMemberTypes": [ "User" ], "displayName": "StagedPay Portal Administrator", "id": "e1d1b79b-bf93-4698-96f7-b6460d86b39c", "isEnabled": true, "description": "Administrators can manage the StagedPay Portal.", "value": "StagedPayPortalAdmin" } ],

  15. Add a User Administrator
    • in the Azure Portal, navigate to Azure AD, then select Enterprise Applications.
    • Find the StagedPay Portal application in the list and open it.
    • Click on Users and Groups and then click the Add user button at the top.
    • Click on Users, click on the User who will be the administrator and click the Select button.
    • The Select Role option should already be set to ‘StagedPay Portal Administrator’ assuming you completed the update to the Portal application manifest in the previous step.
    • Click the Assign button.

Automated Installation Input Values

The installation process will take you through a series of steps to gather information needed to complete the installation.

Basics

Company Name:

  • The name of your company

 

Company TimeZone:

  • The time zone used for transaction processing

 

Application Configuration

App Service Plan Name:

  • The name for the App Service Hosting Plan that will be created.

 

App Service Plan Sku Name:

  • The pricing tier for the App Service Hosting Plan.
  • This application cannot be setup in the Free hosting tier.
  • It is recommended to select Basic or higher.

 

StagedPay API App Service Name:

  • A Web API App Service will be installed. This is the name you specified for the API app service in the pre-installation steps.
  • Example: yourCompanyNameStagedPayAPI
  • Because App Services must have a globally unique name, the installation process will append the ResourceGroup ID to the end of the name you specify to ensure uniqueness.

 

StagedPay API App Registration Application ID:

  • This is the Staged Pay API Azure AD Application Registration ID you created in the pre-installation steps.

 

StagedPay API App Registration Application Secret:

  • This is the Staged Pay API Azure AD Application Registration Secret you created in the pre-installation steps.

 

StagedPay Portal App Service Name:

  • A Portal App Service will be installed. This is the name you specified for the Portal app service in the pre-installation steps.
  • Set this to the SAME value you specified in the first segment of the DNS CNAME record Value property.
  • An App Service MUST have a globally unique name. Because you have most likely already set this in the CNAME record, it is up to you to be sure this is a globally unique app service name.

 

StagedPay Portal Url Domain:

  • The url resource name (domain) for your StagedPay Portal Application Service.
  • This is the Portal url you specified in the pre-installation steps, minus the protocol identifier: ‘http:// or https://’.
  • Example: 'stagedpay.yourcompanydomain.com' or 'companyNameStagedPayPortal.azurewebsites.net'.

 

StagedPay Portal App Registration Application ID:

  • This is the Staged Pay Portal Azure AD Application Registration ID you created in the pre-installation steps.

 

StagedPay Portal App Registration Application Secret:

  • This is the Staged Pay Portal Azure AD Application Registration Secret you created in the pre-installation steps.

 

Recurring Transactions Enabled:

  • Enables a background process to create recurring transactions according to a schedule set for the transaction.

 

Recurring Transactions Interval in Minutes:

  • The number of minutes between checks for the recurring transaction schedules. Value must be between 5 and 720. This field is only available if Recurring Transactions is set to Enabled.

 

Automatic Payments Enabled:

  • Allows a recurring transcation that is created with a credit card to be automatically completed. This field is only available if Recurring Transactions is set to Enabled.

 

Automatic Payments Interval in Minutes:

  • The number of minutes between checks for transactions that could be automatically paid. Value must be between 5 and 720. This field is only available if Recurring Transactions is set to Enabled and Automatic Payments is set to Enabled.

 

SSL Certificate Configuration

Create Standard SSL Certificate:

  • Select ‘Yes’ to have the installation create a Standard SSL Certificate for you and to assign it to the StagedPay Portal app service.
  • Select ‘No’ to create your certificate manually and assign it to the StagedPay Portal app service by following the instructions here: https://docs.microsoft.com/en-us/azure/app-service/web-sites-purchase-ssl-web-site
  • If you require a Wildcard SSL Certificate, please select ‘No’ and follow the steps to create and assign it manually.

 

SSL Certificate Name:

  • The SSL Certificate order name.

 

Certificate Rot Host Name:

  • In most cases this will be the same as the value entered in the ‘StagedPay Portal Url Domain’ property on the Application Configuration step.

 

Existing Key Vault Id:

  • This is the id for your existing key vault (created in the pre-installation steps, if necessary).
  • To retrieve this value, in the Azure portal, open the Key Vault and click on the ‘Properties’ link on the left side. Copy the Resource ID value and paste it in this field.

 

Sql Server Configuration

Sql Administrator Username:

  • The Username for your sql server administrator

 

Password:

  • The Password for your sql server administrator username

 

Confirm Password:

  • The Password for your sql server administrator username

 

Sql Server Name :

  • The name of your Sql Server. If you do not have a sql server, the installation will provision one.

 

Sql Server Database Name:

  • The name for the StagedPay Sql Server database.

 

Sql Server Collation:

  • A collation is a configuration setting that determines how the database engine should treat character data at the server, database, or column level. The value you input here is for the database. A default value has been provided.

 

Sql Server DB Edition:

  • Sets the Azure Sql Server database service tier.

 

Sql Server Database Pricing Tier:

  • This is the Sql Requested Service Ojbective Name - the Azure Sql Server database pricing tier.

 

Authentication Configuration

Microsoft Application ID:

  • The application Id from the pre-install step to register a new application in the Microsoft developer console.

 

Microsoft Password:

  • The password from the pre-install step to register a new application in the Microsoft developer console.

 

Google Client ID:

  • The Client ID from the pre-install step to register a new application in the Google developer console.

 

Google Client Secret:

  • The Client Secret from the pre-install step to register a new application in the Google developer console.

 

Notification Configuration

From Email Address:

  • Specify the email address any email notifications will come from.

 

Use Twilio:

  • Select ‘Yes’ to configure the application to be able to send text message notifications.
  • Select ‘No’ to not allow text message notifications.

 

Twilio Account SID:

  • Value from the pre-install step to setup a Twilio account.

 

Twilio Account Token:

  • Value from the pre-install step to setup a Twilio account.

 

Twilio From Phone Number:

  • Value from the pre-install step to setup a Twilio account.

 


Post-Installation

There are some additional items that cannot be automated and must be completed after the installation completes:

  1. If manually adding your SSL Certificate or using an existing certificate, please follow the instructions in this article: https://docs.microsoft.com/en-us/azure/app-service/web-sites-purchase-ssl-web-site.