Virtual Terminal - deprecated

The Blackthorn Terminal is replaced by the Virtual Terminal

Feature Overview

This feature allows you to create payment methods and, create, capture and auto-process the transactions on a scheduled date. It uses the latest method of Stripe.js and Accept.js for collecting the card details in order to maintain the simplest form of PCI Compliance. It provides you with the flexibility to modify the fields on the terminal using the fieldsets. You can also pre-populate the fields on the terminal using our custom metadata mapping.

Scope

The Virtual Terminal is supported in Classic, Lightning, Lightning Utility Bar, Salesforce Mobile, Salesforce Communities, Global Quick Actions, and Custom Components.

Use Cases

  • The model supports Leads/Contacts or any object of your choosing (Standard or Custom) to be your transaction parent.

  • You can add/remove/sort fields in the terminal using Field Sets.

  • Ability to prepopulate fields values with mapping records. Click here for more information.

  • Create and process charge transactions, create payment methods, and create related object records.

  • Schedule a payment.

  • Adding a Spreedly Payment Method and processing a charge Transaction for that Payment Gateway provider.


Setup

Instructions to set this up in:

  1. Salesforce Classic
  2. Salesforce Lightning
  3. Salesforce Mobile
  4. Lightning Utility Bar
  5. Customer Community
  6. Quick Action
  7. Custom component

Configuration

  1. Create mapping records to prepopulate values from your Parent object to the Virtual terminal.
  2. Add, remove, and modify fields on the transaction screen.
  3. Add, remove, and modify fields on the new record screen for Accounts, Contacts, and other Related To Objects.

📘

Note:

The Payment Method is defined by the Related To and Payment Gateway fields.
For example, if you have multiple payment gateways, the Payment Method will only show cards related to that gateway and the Related To record.


Process for setting Virtual Terminal in Lightning

  1. Firstly, you'll need to configure the virtual terminal in lightning record page.

Lightning Experience

  • Navigate to any Object's single record.

  • Select the widget icon in the upper right-hand corner.

  • From the drop-down, click "Edit Page."

  • On the left-hand side, select the "Visualforce" component.

  • Define the Virtual Terminal visualforce page.

  • Set the height to 660px.

  • Save.

  1. Next, you can pre-populate the terminal fields. Example screenshot below shows the amount is been populated on the transaction screen. How can I do this?
Pre-populating amount field - Virtual TerminalPre-populating amount field - Virtual Terminal

Pre-populating amount field - Virtual Terminal

  1. If you wish to customize the above transaction screen to contain your custom field, you can modify the fieldset from here.
Custom payment field - Virtual TerminalCustom payment field - Virtual Terminal

Custom payment field - Virtual Terminal

  1. Clicking "Add New" under the Related To tab allows you to open a screen to create an account/contact/lead (pre-populate this Related To field in step 2). See how this can be done here.
New account record screen - Virtual terminalNew account record screen - Virtual terminal

New account record screen - Virtual terminal

  1. You're all set to capture payments through the Virtual terminal now! :dancers:

Salesforce Classic

  1. Navigate to the Blackthorn | Payments Admin App.

  2. Select the Blackthorn | Payments Setup Wizard tab.

  3. Click on the "Transaction Relationships" Step.

  4. Select object(s).

Transaction (Business Process) relationships: When a business charges a customer for a product or service in Salesforce, there is an object that represents what's being sold, typically an Opportunity, Quote, or similar. In this step, if you select Opportunity, a lookup relationship between Transaction and Opportunity will be created.

  1. Click "Create."

  2. Navigate to the Object's Page Layout and add the Virtual Terminal button.

Removing the Virtual Terminal button from your Page Layouts:

  1. Navigate to the Object's Page Layout.

Standard Objects: Setup | In the Quick Find / Search type in the “Object Name” | Select “Page Layouts."

Custom Objects: Setup | In the Quick Find / Search type in “Objects” | Select “Objects” under Create | Select the Object | Scroll down to “Page Layouts."

  1. Edit the Page Layout.

  2. Under custom buttons, click and drag the Virtual Terminal button off the layout.

  3. Save.


Salesforce Mobile App

  1. Navigate to Setup | In the Quick Find / Search type in and select “Tabs” | Scroll down to “Visualforce Tabs” | Click "New."

  2. Enter in:

Visualforce Page: Virtual Terminal [bt_stripe_BlackthornTerminal]
Tab Label: Up to you! (then click Tab to auto-fill the Tab Name)
Tab Style: Up to you!
  1. Click Next.

  2. Add to your applicable profiles.

  3. Save.

  4. Navigate to Setup | In the Quick Find / Search type in and select “Salesforce Navigation."

  5. From the available list, select the Virtual Terminal.

  6. Save.

Log into Salesforce1, navigate to the mobile menu, scroll to the bottom of Apps, and you should see the Virtual Terminal.


Lightning Experience Utility Bar

📘

Note:

Virtual terminal (VT) cannot be added to the Lightning experience Utility Bar of the packaged (Installed) applications, like Blackthorn | Payments or Blackthorn | Payments (Admin). You can create a custom lightning app with your desired objects and add the VT by following below steps.

Create the Virtual Terminal Utility Bar item on other Apps:

  1. Navigate to: Setup | In the Quick Find / Search type in “App Manager” | select edit next to the Lightning Application | tab over to "Utility Bar."

  2. Add new Utility Bar item.

  3. Select the Visualforce component.

  4. Select the “Virtual Terminal” component.

  5. Update the properties.

  1. Save.

Customer Community

Community Builder Component
The Virtual Terminal is located in the Visualforce component in the Community Builder:

If the user is not able to see the Virtual terminal in the community or is throwing an error, please refer our troubleshooting guide here.


Quick Action

  1. Navigate to the setup, quick find, global actions.

  2. Create a new "Visualforce" type action. The page you want is bt_stripe__BlackthornTerminal called Virtual Terminal.

  3. Add this to the global publisher layout (quick find, publisher).

  4. Add to the Opportunity Mobile/Lightning Actions.


Custom component

If you have created a visualforce page or custom component that needs to reference the Virtual Terminal, please use the below structure:

<bt_stripe:VirtualTerminal recordId="{ORDER_OBJECT.Id}" sObjectName="Order"/>

Replacing order with your parent Object.


How to prepopulate terminal fields?

Map fields from the Transaction's Parent Object to the Terminal's Transaction screen using a Custom Metadata Type called, "Virtual Terminal Mapping."

Please make sure the fields mapped have the same field type and property. For example, if you created a custom field to prepopulate currency, make sure it matches the same format as the currency field on Transaction.

Fields that can be prepopulated:

  • Related To
  • Payment Method
  • Description
  • Amount
  • Currency
  • Email
  • Holder's Name
    Note: This is for Credit Card Payment Methods only at this time.
  • Custom fields

Navigate to Custom Metadata Types.

Lightning/Classic: Navigate to Setup | In the Quick Find / Search, type in and select " Custom Metadata Types."

  1. Click "Manage Records" next to Virtual Terminal Mapping.

  2. Click New.

  3. Enter:

Virtual Terminal Mapping Name: This is the API name for the record. The API name can only contain underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. For example, "opp_amount."

Label: This is the label for the particular prepopulating record.
For example, use "Opp->Trans Amount" for the label if you are prepopulating the amount field.

Screen: Single Transaction.
Use the Related To screen for prepopulating the "Related To" field on the Terminal's Transaction screen. See example here.

Source Object: Select the Parent Object.
For example, the Opportunity Object.

Source Field: Select the field you want the value to come from.
For example, if you want to prepopulate the Terminal's Transaction amount with the Opportunity's amount, then select the amount field from the list.

Target Object: select Transaction [bt_stripe].

Target Field: Select the field you want the value to populate in.
For example, you would select the Amount field.

  • Save.

Please view our Use Cases for additional prepopulating examples.


How can we add/remove terminal fields?

Adding, removing, and modifying fields on the Virtual Terminal is done through Field Sets. A Field Set is a grouping of fields that can be displayed on Lightning Components. Where a user can add, remove, or rearrange fields from the Field Set, without altering the Lightning Component.

🚧

Formula and auto-number fields cannot be added to the fieldset.

Transaction Screen

A few managed fields and all custom fields can be added and modified on the Virtual Terminal's Transaction screen.

  1. Navigate to the Transaction object.

Classic: Navigate to Setup | In the Quick Find / Search type in and select " Objects" | Click the Transaction Object.

  1. Scroll down to Field Sets.

  2. Click edit next to Virtual Terminal.

Example of available custom and managed fields.Example of available custom and managed fields.

Example of available custom and managed fields.

Fields "In the Field Set" box are the fields currently on the Virtual Terminal's Transaction screen. Remove, add, and modify the fields within that box to fit your use case.

  1. Save.

New Record Screen

New record screen allows you to create new records from the "Related To" field on the Virtual Terminal.

Account and Contact

The Account and Contact "New Record" screens have predefined fields available and a FieldSet record is automatically created.

  1. Navigate to the Account or Contact Object.

Classic: Navigate to Setup | In the Quick Find / Search type in " Accounts" or "Contacts."

  1. Scroll down to and select "Field Sets."

  2. Click edit next to "Virtual Terminal."

Contact Field SetContact Field Set

Contact Field Set

Account Field SetAccount Field Set

Account Field Set

Fields "In the Field Set" box are the fields currently on the Virtual Terminal's new Account or Contact record screen. Remove, add, and modify the fields within that box to fit your use case.

Other objects

Related To objects besides Account and Contact, show a blank "New Record" screen. In order to create new records, you will need to manually create a Field Set.

For example, the new Lead screen looks like this before adding a FieldSet:

  1. Navigate to the "Related To" object. For example, the Lead Object.

  2. Scroll down to Field Sets.

  3. Click New.

  4. Enter in:

Field Set Label: Virtual Terminal.

Field Set Name: VirtualTerminal.
_If the Field Set Name value is different than above, the fields will not display on the Virtual Terminal screen.

Where is this used? Description of this Field Set. For example, "Virtual Terminal for the new Lead record screen."

  1. Drag the fields you want to use for creating a new Lead record "In the Field Set" box.
  1. Save.

The screen now has fields and can create new Lead records!

Custom Settings

We've included the ability to modify how you use the Virtual Terminal in Custom Settings. The following settings will give your organization more flexibility when it comes to adding payment details to a record and charging Transactions.

Settings:

  • Disable Amount in Communities - This setting will prevent users from populating the Amount field in Virtual Terminal on a community page. This will work only for users logged in as a Community User or and unauthenticated user.

  • Disable New Charge - This setting will remove the "New Single Charge" option from the Action menu.

  • Disable New Payment Method - This setting will remove the "New Payment Method" option from the Action menu.

  • Default New Payment Method - This setting will set the "New Payment Method" option as the default option on the Action menu.

  • Disable Related To - This setting will make the Related To field read-only.

  • Hide Parent - This setting will remove the Parent Object field from the Virtual Terminal.

  • Hide Process Type - This setting sets the Process Type selection to "Capture Now" and removes the picklist from the Virtual Terminal.

  • Hide Related To - This setting removes the field Related To from the Virtual Terminal.

  • Payment Method Success Message - When a value is added to this setting it is used as the text in the success message box that appears when a Payment Method is created in the Virtual Terminal.

  • Transaction Success Message - When a value is added to this setting it is used as the text in the success message box that appears when a Transaction is captured in the Virtual Terminal.

Steps to Enable:

  1. Navigate to "Setup".

  2. Type "Custom Settings" in the Quick Find menu and click "Custom Settings".

  3. Click "Blackthorn Payments - Virtual Terminal".

  4. Click the Manage button.

  5. Click the Edit button.

  6. Use the checkboxes to enable one or multiple settings.

  7. Click Save.


Custom Labels

Custom Labels are custom text values, up to 1,000 characters, that can be accessed from Apex Classes or Visualforce Pages. Our Payments package has included multiple Custom Labels for the Virtual Terminal. They include:

  • Action
  • Related To
  • Parent Object
  • Payment Method
  • Amount
  • Process Type
  • Currency

In order to update the labels you see in Virtual Terminal follow these steps:

  1. Navigate to "Setup".

  2. Type "Custom Labels" in the Quick Find menu and click "Custom Labels".

  3. Find the Custom Labels with "VT" in the Name.

  4. Click Edit to the left of the Virtual Terminal Label you would like to modify.

  5. Add your Custom Label text to the Value field.

  6. Click Save.


ACH Payment Method for Stripe in Virtual Terminal

Using the new Payment Method screen on the Virtual Terminal, users can select to create an ACH or Card payment method. See the image below.

Once you enter the ACH details and click save, you will see the below screen which shows the Payment Method is successfully created in Salesforce.

Upon entering the micro-deposits, this payment method will be verified and ready to use! To learn more about micro-deposit verification, click here.


Schedule a Payment using the Virtual Terminal

  1. Define the Account, Payment Method, Description, Amount and Currency Type.

  2. Change the Process Type to 'Auto Process'.

  3. Define the Capture Date and then click the process button.


Migrating from Lightning Component to Visualforce Component

  • Salesforce Classic: No changes need to be made. The Virtual Terminal button will still work as expected.

  • Salesforce Lightning: Update all pages where the current Virtual Terminal lightning component is.

  1. Edit the page
  2. Remove the Virtual Terminal
  3. Add in the Visualforce component
  • Salesforce Mobile: Delete the Lightning Component tab and create a new Visualforce tab. To do so, please find the detailed instructions here.

  • Lightning Experience Utility Bar: Remove the Lightning Component from the app utility bar and insert the Visualforce component. Then define the Visualforce component below:

  • Community: Replace the custom Lightning component with the Visualforce component as shown below:

Next Steps


Troubleshooting/FAQ

If you have received an error with the Virtual Terminal or have a question, please view our Troubleshooting and Frequently Asked Questions. If you still have Virtual Terminal questions, please contact Blackthorn Support. We're happy to help!


Did this page help you?