The Zero Footprint Tokenization Component is an Aura Lightning Component that allows a developer to quickly implement tokenization of payment data in a configurable UI anywhere within your Salesforce ecosystem. The component will fire an event upon tokenization for you to obtain the necessary results and optionally can update the payee details with the entered data and create a corresponding chargent order and chargent transaction.
Zero Footprint Tokenization requires Chargent’s Enterprise Edition. For more information about our editions, visit our Pricing page.
Placement #
The component does not require an underlying SObject and can be placed within a lightning app and within your own lightning component. While it does not require an underlying SObject for placement, it does require an SObject that supports the configurable payee detail fields.
For example, the component can be placed within a component in your lightning application and use the SObject Contact to support the payee fields that you wish to display
Usage #
The component can simply be used within your markup for your lightning component. Some parameters need to be set, as well as some optional parameters. These are outlined below
Component #
<ChargentBase:zeroFootprint_Tokenization …./>
Parameters #
GatewayId (Required)
This is the Salesforce ID of the gateway record to use for the tokenization.
Note: The payment entry screen will respect the settings on this gateway record. If, for example, you have not selected Credit Card as a payment option, then it will not be displayed. Another example would be if you have not selected Visa as an accepted credit card type, then it would not allow the user to complete the tokenization with a Visa card number.
If the gateway has the “Require CVV in payment console” set to true, then the payment entry screen will also require the CVV to be entered.
buttonLabelPayeeSubmit (default: Next)
When in one column mode, this will be the label on the button to submit the entered payee details and continue to the next screen to collect the payment information.
buttonLabelTokenize (default: Submit)
This is the label of the button to tokenize the payment information. In one column mode, this will be the button on the second screen where the user enters the payment information. In two-column mode this will be the only button displayed.
twoColumnLayout (default: false)
This indicates the display mode.
When false, the component will present the payee details first, then the user clicks the payee submit button and is taken to the payment entry screen where they will enter their payment data and click the tokenize button. Useful for small modal windows and the narrow side of a lightning layout.
When true, the component will present the payee details and payment information side by side on one screen. Then the user enters the appropriate data and clicks the tokenize button. Useful for medium to large modal windows and the wide side of a lightning layout.
payeeRecordId (Id – not required)
If you are using a pre-existing record to pre-populate or associate the payee details, set this ID to the desired record ID. This field is not required. If not set and “updatePayeeRecord” is set to true, a new payee object will be created.
payeeObjectType (String – Required)
This is the Object type of the payeeRecordId (if set) or the object type where the specified payee fields will be pulled from. This is a required parameter and must be set in order to populate the fields on the payform.
How the component knows how to display each of the specified payee fields according to their type.
payeeRecordFieldList (String[] – Required)
This is a comma-separated list of field API names you wish to display from the payee object specified. These are the fields the user will be populating when they use the component.
An example if using the Contact Object Type: FirstName,LastName,MailingStreet,MailingCity,MailingState,MailingPostalCode
payeeToChargentOrderFields (Object – Required)
While no underlying SObject is required to place the component, it does rely on an abstract version of the Chargent Order. In order to properly associate the fields you wish to display with the appropriate data to send to the gateway this mapping will need to be provided.
The mapping is a javascript object with key-value pairs wrapped in {}. The key is the payee SObject Field API Name, and the value is the corresponding Chargent Order field API name
- Key: Payee SObject Field API name
- Value: Corresponding Chargent Order field API name
An example mapping using the contact fields specified above:
{‘FirstName’:’ChargentOrders__Billing_First_Name__c’,’LastName’:’ChargentOrders__Billing_L ast_Name__c’,’MailingStreet’:’ChargentOrders__Billing_Address__c’,’MailingCity’:’ChargentOrd ers__Billing_City__c’,’MailingState’:’ChargentOrders__Billing_State__c’,’MailingPostalCode’:’ChargentOrders__Billing_Zip_Postal__c’}
This is passed in as one long string. To see it a bit more clearly, we have prettified it a bit below.
Do not pass the information in the below format:
{
“FirstName”: “ChargentOrders__Billing_First_Name__c”, “LastName”: “ChargentOrders__Billing_Last_Name__c”, “MailingStreet”: “ChargentOrders__Billing_Address__c”, “MailingCity”: “ChargentOrders__Billing_City__c”, “MailingState”: “ChargentOrders__Billing_State__c”, “MailingPostalCode”: “ChargentOrders__Billing_Zip_Postal__c”
}
In the above examples, you can see it has been specified that the FirstName be associated with the ChargentOrders__Billing_First_Name__c field and so on. This is dynamic and will depend on your configuration for the payee fields and SObject type
orderStaticValueMap (Object – Not required)
This parameter is used to pass specific static information to the gateway during tokenization but do not wish to display that information to the user or obtain their input. The fields that can be passed are limited to:
- ChargentOrders__Payment_Method__c – ChargentOrders__OrderSource__c
- ChargentOrders__Order_Information__c – ChargentOrders__Description__c
- ChargentOrders__Currency__c
- ChargentOrders__Customer_IP__c
This is similar to the format of the payeeToChargentOrderFields parameter, except the key is the Chargent Order Field API Name and the value is the value to be sent.
Key: Corresponding Chargent Order field API name Value: value to be passed through to the gateway
An example using order information is: {‘ChargentOrders__Order_Information__c’:’An example Information’}
createChargentOrder (Default: false)
This parameter indicates if a Chargent Order and related chargent transaction record should be created due to the tokenization.
updatePayeeRecord (Default: false)
This parameter indicates if you wish to have the specified payee record updated, or in the case of no payeeRecordId parameter created. If this is not set to true, the entered information will be passed on to the gateway, but the underlying payee record will not be altered or created.
Tokenization Event #
When the tokenization is complete, an event named ChargentBase:tokenizationEvent is fired. Components including the Zero Footprint tokenization component can handle this event and perform actions based on the results of the tokenization event.
Event Parameters
| Parameter | Type | Description |
| success | Boolean | Tokenization successful |
| accountName | String | Credit card or bank account holder name |
| accountFirstName | String | Credit card or bank account holder first name |
| accountLastName | String | Credit card or bank account holder last name |
| accountStreet | String | Account holder billing street |
| accountCity | String | Account holder billing city |
| accountState | String | Account holder billing state |
| accountPostalCode | String | Account holder billing postal code |
| cardExpirationMonth | String | Credit card expiration month |
| cardExpirationMonth | String | Credit card expiration month |
| cardExpirationYear | String | Credit card expiration year |
| accountLast4 | String | Last four of the credit card or bank account number |
| bankRoutingNumber | String | Bank account routing number |
| paymentMethod | String | Credit Card or eCheck |
| paymentType | String | The card type or bank account type |
| gatewayStatus | String | The status returned by the gateway. If there was a platform error this will be set to “ERROR” |
| gatewayMessage | String | Either the gateway message or Exception message |
| gatewayReasonText | String | The returned reason text from the gateway |
| gatewayReasonCode | String | The returned reason code from the gateway |
| gatewayId | String | The id assigned to this transaction by the gateway |
| gatewayResponse | String | Full response from gateway |
| paymentToken | String | The returned payment token, if any |
| chargentTransactionId | String | The salesforce Id of the created transaction if createChargentOrder is set to true |
| payeeRecordId | String | The id of the payee record that was created or updates during this transaction. Wil be null if the updatePayeeRecord parameter is false |
Example #
An example implementation of the component placed on the opportunity object embedding the Zero Footprint tokenization component within it.
This example can be used to create a lightning component quickly and begin playing with the various options.
Design
| <design:component> <sfdc:objects> <sfdc:object>Opportunity</sfdc:object> </sfdc:objects> <design:attribute description=”Gateway Id” name=”gatewayId” label=”Gateway Id”/> <design:attribute description=”Create or Update Payee” name=”updatePayeeRecord” label=”Update Payee Record” default=”false”/> <design:attribute description=”Label for payee submit button” name=”buttonLabelPayeeSubmit” label=”Label for Payee Submit button” default=”Next”/> <design:attribute description=”Label for tokenization button” name=”buttonLabelTokenize” label=”Label for tokenization button” default=”Submit”/> <design:attribute name=”twoColumnLayout” default=”false” label= ”Two Column Layout” description=”show payee details and payment entry side by side in two columns”/> <design:attribute name=”contactLookupAPIName” l abel=”Billing Contact Lookup API Name” description=”The API name of the billing contact lookup on Opportunity”/> </design:component> |
Component
| <aura:handler name=”init” value=”{!this}” action=”{ !c.doInit}”/> <aura:attribute name=”gatewayId” type=”String” required=”true” access=”global”/> <aura:attribute name=”updatePayeeRecord” type=”Boolean” access=”global”/> <aura:attribute name=”buttonLabelPayeeSubmit” type=” String” default=”Next” access=”global”/> <aura:attribute name=”buttonLabelTokenize” type=”String” default=”Submit” access=”global”/> <aura:attribute name=”contactLookupAPIName” type=”String” access=”global” required=”true”/> <aura:attribute name=”twoColumnLayout” type=”Boolean” default=” false” access=”global”/> <aura:attribute name=”opportunityFields” type=”String[]” access=”private”/> <aura:attribute name=”opportunityRecordFields” type=”Object” description=”The fields object for reference in markup” access=”private”/> <aura:attribute name=”opportunityRecord” type=”Object” description=”The opportunity record” access=”private”/> <aura:attribute name=”opportunityRecordError” type=” String” access=”private” description=”Error messages associated with lightning data service for the opportunity record”/> <aura:handler name=”tokenEvent” event=”c:tokenizationEvent” action=”{!c.handleTokenization}”/ > <force:recordData aura:id=”opportunityRecord” layoutType=”FULL” recordId=”{!v.recordId}” targetRecord=”{!v.opportunityRecord}” targetFields=”{!v.opportunityRecordFields}” fields=”{!v.opportunityFields}” targetError=”{!v.opportunityRecordError}” mode=”VIEW”/> <lightning:card title=”Payment Tokenization”> <div class=”slds-p-around_medium”> <div aura:id=”tokenComponent”> <aura:if isTrue=”{!not(empty(v.opportunityRecordError))}”> <div class=”{!if(empty(v.opportunityRecordError),’slds-hide’,’recordError’)}”> severity=”error” closable=”true”> <ui:message title=”Error” {!v.opportunityRecordError} </ui:message> </div> <aura:set attribute=”else”> <ChargentBase:zeroFootprint_Tokenization twoColumnLayout=”{!v.twoColumnLayout}” buttonLabelTokenize=”{!v.buttonLabelTokenize}” buttonLabelPayeeSubmit=”{!v.buttonLabelPayeeSubmit}” payeeRecordFieldList=”FirstName,LastName, MailingStreet,MailingCity,MailingState,MailingPostalCode” updatePayeeRecord=”{!v.updatePayeeRecord}” payeeObjectType=”Contact” GatewayId=”{!v.gatewayId}” payeeRecordId=”{!v.opportunityRecordFields.ChargentBase__Billing_Contact__c }” payeeToChargentOrderFields=”{‘FirstName’:’ChargentOrders__Billing_First_Nam e__c’,’LastName’:’ChargentOrders__Billing_Last_Name__c’,’MailingStreet’:’Ch argentOrders__Billing_Address__c’,’MailingCity’:’ChargentOrders__Billing_Ci ty__c’,’MailingState’:’ChargentOrders__Billing_State__c’,’MailingPostalCode ‘:’ChargentOrders__Billing_Zip_Postal__c’}” orderStaticValueMap=”{‘ChargentOrders__Order_Information__c’:’An example Information’} /> </aura:set> </aura:if> </div> <div aura:id=”result-div” class=”slds-grid slds-size_1-of-1″ id=”result-div”></div> </div> </lightning:card> </aura:component> |
Controller
| ({ doInit: function(component,event,helper){ component.set(”v.opportunityFields”,component.get(”v.contactLookupAPIName”) ); }, handleTokenization: function(component,event,handler){ } }) var result = JSON.stringify(event.getParams(),null,2); $A.util.addClass(component.find(”tokenComponent”),’slds-hide’); component.find(”result-div”).getElement().innerText = result; |
Images of Results #
One column Layout
Payee Details
Payment Entry Screen
Credit Card
Bank Account
Results
Two Column Layout
