Getting Started
These are the pre-requisites to perform any Chargent Operation using the Chargent Custom Checkout:
Pre-requisites
- API Feature Parameter Activated
- Assign permissions to users
- Get the Order record Id related to the payment
- Validated input data
- Implement scaComponent LWC
API Feature Parameter Activated
Contact your administrator to request the API Feature parameter activation.
Assign permissions to users
Salesforce internal and communities external users must be equiped with special permissions in order to perform any operation with the Custom Checkout Form. The following permissions are for a user with community license and are not included in the library, therefore in every implementation it is mandatory to create and assign them to users that will make payments.
Community User
To provision Community Users (users with the Customer Community license), follow these steps:
1. Clone the Chargent User (Orders) permission set, then remove its assigned apps. // This may change after fixing the community guest user sharing rule issue. Permission Set for Payment Request (Chargent Orders) could be assigned instead
2. Clone the Permission Set for Payment Request (Base) permission set and go to "Object Settigs > Gateways" to add to the View All permission.
3. Assing the permission sets created in step #1 and #2 to the Community users.
Community Guest User
Community Guest Users (users with the Guest License) must be assigned the following Permission Sets, which are included in the Chargent Package:
- Permission Set for Payment Request (Base)
- Permission Set for Payment Request (Chargent Orders)
- Additionaly, give access to ChargentBase.ScaCyberSource Visualforce Page
- Additionaly, create a sharing rule to give read access to all active gateways
// *This may not be necessary after fixing the community guest user sharing rule issue.
Note: For Create Payment Method functionality additional permissions need to be assigned. Follow these instructions in the Custom Checkout Operations.
Get the Order record Id related to the payment
All Chargent Operations avalaibles in CCC need the Chargent Order Id to be executed. Thus the Order Id needs to be set as a variable in the LWC implemented in the Custom Checkout Form page.
import { LightningElement } from 'lwc';
import customCheckout from "@salesforce/resourceUrl/ChargentCustomCheckout";
export default class CustomCheckoutExample extends LightningElement {
recordId = "orderId";
...
}
Validated input data
import { LightningElement } from 'lwc';
import customCheckout from "@salesforce/resourceUrl/ChargentCustomCheckout";
export default class CustomCheckoutExample extends LightningElement {
recordId = "OrderId";
handleCustomCheckoutOperation() {
// Retrieve and validate input values
var payload = chargentFields.buildPayForm(this.recordId, 'Credit Card');
if (payload.status === 200) {
// Perform payment Operation
} else {
// Missing and invalid fields error handling
}
}
}
All input data must be validated by calling the buildPayForm(orderId, selectedPaymentMethod) CCC library method. This method receives the Chargent Order Id and the payment method used by the client ('Credit Card' or 'Bank Account'), and it returns a responseObject with ‘200’ status if all inputs were filled out correctly (mainly the mandatory fields); and with ‘400’ status if the mandatory fields were not defined in the Chargent Configuration Object or if any input that was defined was not filled out by the user. This responseObject will be part of the input that the scaComponent will receive to perform all payment operations.
responseObject with 400 status
| Name | Description |
|---|---|
| status | 400 |
| message | "error" |
| recordId | Record Order Id |
| formValues | N/A |
| missingcardformFields | List of PayformFields inputs that were defined as required in the Configuration Object but not filled out by the user |
| missingBillingFields | List of BillingFields inputs that were defined as required in the Configuration Object but not filled out by the user |
| invalidFields | List of inputs fields with incorrect data (for now only past card expiration dates) |
{
"status": 400,
"message": "error",
"recordId": "orderId",
"formValues": null,
"missingcardformFields": [
"cardNumber",
"cardCVC"
],
"missingBillingFields": [
"state",
"country"
],
"invalidFields": [
"cardExp"
]
}
{
"status": 400,
"message": "error",
"recordId": "orderId",
"formValues": null,
"missingcardformFields": [
"nameOnAccount",
"accountNumber",
"routingNumber",
"bankName",
"bankAccountType"
],
"missingBillingFields": [
"addressLine",
"city"
],
"invalidFields": []
}
responseObject with 200 Status
| Name | Description |
|---|---|
| status | 200 |
| message | "success" |
| recordId | Order record Id |
| formValues | Key/value list formed with all values retrieved from the inputs |
{
"status": 200,
"message": "success",
"recordId": "orderId",
"formValues": {
"firstName": "John",
"lastName": "Doe",
"nameOnCard": "John Doe",
"cardNumber": "4111111111111111",
"cardType": "Visa",
"expYear": 2024,
"expMonth": 12,
"securityCode": "123",
"billingAddressLine": "Main Street",
"paymentMethod": "Credit Card",
"amount": "33.00",
"billingAddressLine2": "Second Street",
"billingState": "Florida",
"billingCity": "Miami",
"billingZip": "12345",
"billingCountry": "United States of America",
"billingEmail": "[email protected]",
"billingPhone": "9955559965"
}
}
{
"status": 200,
"message": "success",
"recordId": "orderId",
"formValues": {
"bankAccountName": "John Doe",
"firstName": "John",
"lastName": "Doe",
"bankAccountNumber": "999999999",
"bankRoutingNumber": "123456789",
"bankName": "Test Bank",
"bankAccountType": "Checking",
"paymentMethod": "Bank Account",
"billingAddressLine": "Main Street",
"amount": "33.00",
"billingAddressLine2": "Second Street",
"billingState": "Florida",
"billingCity": "Miami",
"billingZip": "12345",
"billingCountry": "United States of America",
"billingEmail": "[email protected]",
"billingPhone": "9955559965"
}
}
Notice that buildPayForm() method only performs data validations and does not guarantee that the data provided by the user will produce a successful charge. Also, the structure of the responseObject may change on future releases.
Implement scaComponent LWC
The scaComponent component must be included in your LWC implementation, as it is through it that all Chargent Operations will be performed. This component also enables the Strong Customer Authentication functionality. As scaComponent is a Lightning Web Component that comes in the ChargentBase package, Lightning Web Security needs to be able to use it in your custom LWC implementation. Lightning Web Security can be activated in Setup > Security > Session Settins:
Then the scaComponent can be implemented just by adding this code snippet to your custom LWC implementation:
<template>
<chargentbase-sca-component
order-id={recordId}
onresponse={handleScaComponentResponse}>
</chargentbase-sca-component>
<!-- More of customCheckoutExample code -->
</template>
To avoid errors, it is necessary to pass a valid Chargent Order ID to the scaComponent and to implement a method to handle its communication (it communicates through events). In this code example, the handleScaComponentResponse method handles that communication.