Virtual Terminal

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 communities, and global quick actions.

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.


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.


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.


Process for setting Virtual Terminal in Lightning

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

  2. 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 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 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 terminal

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

Salesforce Classic

  • Navigate to the Blackthorn | Payments Admin App.

  • Select the Blackthorn | Payments Setup Wizard tab.

  • Click on the "Transaction Relationships" Step.

  • 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.

  • Click "Create."

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

Removing the Virtual Terminal button from your Page Layouts:

  • 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."

  • Edit the Page Layout.

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

  • Save.


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 660 px.

  • Save.


Salesforce1 Mobile

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

  • 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!
  • Click Next.

  • Add to your applicable profiles.

  • Save.

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

  • From the available list, select the Virtual Terminal.

  • 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:

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

  • Add new Utility Bar item.

  • Select the Visualforce component.

  • Select the “Virtual Terminal” component.

  • Update the properties.

  • 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
  • Custom fields

Navigate to Custom Metadata Types.

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

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

  • Click New.

  • 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.

  • Navigate to the Transaction object.

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

  • Scroll down to Field Sets.

  • Click edit next to Virtual Terminal.

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.

  • Save.

New Record Screen

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

  1. How to modify new record page for Account and Contact?
  2. How to modify/add new fields for other objects- Example: Lead

Account and Contact

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

  • Navigate to the Account or Contact Object.

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

  • Scroll down to and select "Field Sets."

  • Click edit next to "Virtual Terminal."

Contact 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:

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

  • Scroll down to Field Sets.

  • Click New.

  • 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."

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

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

Schedule a Payment using the Virtual Terminal

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

  • Change the Process Type to 'Auto Process'.

  • 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!

Updated 11 days ago


Virtual Terminal


The Blackthorn Terminal is replaced by the Virtual Terminal

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.