AppFrontier

☰ Menu

Payment Request Documentation


Chargent Payment Request Documentation


Overview

Chargent Payment Request, one of the developer tools that is part of the Chargent Payment Processing for Salesforce application, allows you to generate requests for payment to send to your customers. These requests can be in the form of links contained in Salesforce email templates, you can also send them in your own email, over IM or really any media that has clickable links!

Your customers simply click on the link in a payment request email they receive to go to a hosted payment page, where their contact information and the amount is already populated. Hosted on your own Salesforce Force.com Site, the payment page features a brandable, secure credit card form, where your customers enter their payment information. Once payment is made, the transaction is recorded in Salesforce and the correct records are updated.

Requirements

Please Note: the Chargent Payment Request feature requires a Chargent Platform or Sites edition license for use outside of a Salesforce Sandbox.
 
For this reason we encourage development in a Salesforce Sandbox. Please contact us for additional information.

Setup

To use Chargent Payment Request, your Salesforce Administrator or Developer first needs to set up a Salesforce Force.com site, and then grant access to the correct profiles, objects, VisualForce pages, and Apex Classes.

Want the Chargent developer support team to set up Payment Request for you?
 
For a one-time setup fee we'll handle the basic configuration and setup of a Salesforce site payment page and email template with your logo and contact information.
 
The project will take less than 5 business days and costs just $899!

Steps to setup payment request are as follows:

  1. Install and Configure Chargent

    • Set up a Gateway and a test Chargent Order, Opportunity or Case record
    • Run a test by clicking on the Charge button to ensure that your Payment Gateway credentials are set up correctly before proceeding with Payment Request setup

  2. Obtain a License Key from Chargent

    • NOTE: This step is only necessary for Production / Development orgs. Sandbox installations do not require a license key.

    • Go to the Chargent Settings tab
    • Click on the Chargent Feature Activation sub-tab
    • Click the Request Key button
    • Check the box next to Payment Request and Send
    • A license key will be emailed to you by an AppFrontier team member
    • Enter the license key and click the Check and Save Key button

     

    Request a Payment Request License Key


  3. Set up the Visualforce pages

    • Go to the Documents tab
    • Find the Chargent Payment Request folder
    • Download the zip file of Chargent Payment Request Pages. (These open source pages are provided as a separate file so that you can modify them outside of the Chargent managed package).
    • Go to Setup > Develop > Visualforce Pages

     

    Payment Request Visualforce Pages


    • Create a page called "Success"
      • Cut and paste the code from the Success sample page provided
      • Your developer should refer to the comments in the code to understand what can be customized. There are a number of items that are commented out so they don't appear on the page, but should serve as placeholder examples (header and footer graphics, headlines, etc.)

    • Upload your logo
      • Go to Setup > Develop > Static Resources
      • Upload your logo to Static Resources
      • Change the sample logo {(!$Resource.ChargentBase__ChargentStyling, 'img/Chargent.png')} to {!$Resource.YourLogo}
      • Change AppFrontier address and contact information to your own company contact info
      • Customize other aspects of the design per your organization's requirements

    • Complete the steps above for the other Payment Request pages:
      • Fail
      • Cancel
      • PaymentRequest
      • NOTE: PaymentRequest needs to be created last, since it references the other 3 pages

  4. Configure your Force.com sites page.

    • Create a Domain if you do not have one already (eg. MyCompany.Force.com)
    • Click "New" to Create a New Site
    • Site Label: Choose a name, for example: Payment Request
    • Site Name: Choose a name, for example: PaymentRequest
    • Clickjack Protection Level: Use default or check with your IT department
    • Select PaymentRequest as Active Site Home Page
    • Active: Checked
    • Require Secure Connections (HTTPS): Checked
    • Save

     

    Create a Payment Request Site


    • Click Edit
    • Enable Site Visualforce Pages
    • Add access to the Fail, Success, Cancel and PaymentRequest pages as well as ChargentBase.TChargentApiHelper

     

    Enable Site Visualforce Pages


  5. Assign Chargent License to Guest User

    • Every Force.com site has an associated guest user
    • Go to Site > Public Access Settings > Assigned Users
    • Click on Site Guest User under the Full Name column
    • Scroll down to the "Managed Packages" related list, there you will find and click the "Assign Licenses" button (in center when you scroll down) and choose Chargent Orders, Cases or Opportunities (depending on which Transaction package you have installed.

     

    Payment Request Guest User


    Create a Payment Request Site


  6. Apply a Permission Set to the Site Guest User

    • Open the Site Guest User view page

      • Go to Setup > Develop > Sites

      • Select a Payment Request Site


      • Select an Active Site

      • Click the [Public Access Settings] button

      • Select Public Access Settings


      • Click the [View Users] button

      • Select the Guest User used in this site

    • Apply the Permission Set to Site Guest User

      • Click the [Edit Assignments] button in Permission Set Assignments related list

      • Edit Permission Set Assignments


      • Select two permission sets: Permission Set for Payment Request (Base) and Permission Set for Payment Request (SFA/Orders/Cases)

      • Select Permission Sets


      • Apply changes


    • Configure Payment Request Feature

      • Go to Setup > Develop > Sites

      • Copy the Site URL

      • Select Pay Request Site URL


      • Go to Advanced Settings in Chargent Settings

      • Insert the URL in the "Salesforce Sites Page (URL)" field


      • Select Pay Request Site URL


      • Apply changes

  7. Configure other Payment Request Settings

    • Go to the Chargent Settings tab
    • Click on the Advanced Settings sub-tab
    • Under the Payment Request section on the left, configure the fields as follows:

    • Automatically Create PR Record
      Checking this box will have Chargent create a new Payment Request record for each new Opportunity, Chargent Order, or Case record that is created. This is used when you want to use the Pay Link in certain automated emails or invoices. Leave unchecked as a default.

    • Show Debug
      If this option checked result message will include debug information like response from gateway. For testing only, should NEVER be enabled when customers are using your payment forms.

    • Payment Confirmation Text
      Displays a confirmation message to customer after successful payment. Leave default or customize the text as you wish.

    • Payment Error Text
      Displays a confirmation message to customer after failed payment. Leave default or customize the text as you wish.

    • Payment Request Confirmation Text
      Displays message to Salesforce user when a Payment Request is successfully sent. Leave default or customize the text as you wish.

    • Payment Link Expiration Hours (Number)
      Set the number of hours you would like an individual payment request link to be active. You can choose any number from 1 to 17520. The default is 17520 hours, which is 2 years.

    • Salesforce Sites Page (URL)
      • Go to your Setup > Develop > Sites
      • If you are in sandbox or development org, you will only see one option.
      • If you are in production, you will see two. Use the secure one only! The secure version will be https://yourdomain.secure.force.com
      • Right click and copy the URL, and paste into this field. Paste secure version of URL in SFDC Sites Page field

    • Error Page (URL)
      This URL is where the Payment Request user is sent if their card fails. You can leave this blank and it will go to the fail page you set up before. Or you can put an external URL and customers will go there. A third option is to insert the parameters into the pay request URL. This is an advanced feature, so see the customization section below for details.

    • Thank You Page (URL)
      This is the URL that the user is sent to when they get a successful charge. You can leave this blank and it will go to the fail page you set up before. Or you can put an external URL and customers will go there. A third option is to insert the parameters into the pay request URL. This is an advanced feature, so see the customization section below for details .


     

    Chargent Settings Tab with Payment Request options


  8. Update the Page Layout

    • Update the Opportunity, Case or Chargent Order Page Layout (recent installs of Chargent Orders will already be configured as this is a custom object)
    • Add Payment Requests Related List
    • Add Send Pay Request Button

     

    Add Payment Request button to Page Layout


  9. Create a Public Group and Sharing Rule

    (This will allow the guest user to see the parent records that will be updated by Payment Requests)

    • Go to Setup > Public Groups
      • Create new Public Group called Guest User
      • Add "Payments Site Guest User" and any internal Salesforce users who own Opportunities (or Cases or Chargent Orders if you are using those transaction packages) that might have payment requests to the Group

       

      Create a Payment Request Public Group


    • Go to Setup > Sharing Settings
      • Create New Sharing Rule
      • Read / Write Sharing Rule for the Opportunity, Case or Chargent Order that includes the Guest user for Sites and anyone that is sending Payment Request notifications.
      • Opportunity, Case or Chargent Order Access = Public Read/Write

     

    Create a Payment Request Sharing Rule


  10. Final Setup Steps

    • Go to the Gateways tab and check to make sure that you have selected the types of cards you wish to accept in the Available Card Types field (Visa, MasterCard, etc.)

    • Customize the Payment Request email template

      • Go to MySettings > Email > Email Templates > Chargent Templates
      • Edit the Payment Request template like any standard email template

      • You can also create a new template using your own letterhead or custom HTML or visualforce. To do this, edit the workflow action Payment Request email alert that is part of the Payment Request Email workflow rule.

    • Send yourself some test Payment Requests and run some test transactions, fails, cancels, etc.

     

    How to Send a Payment Request

    1. To send a Payment Request, click the Send Pay Request button on the Opportunity, Chargent Order or Case page

    2. In the modal window that pops up, you have two choices of where to send it:

      • You can choose a Billing Contact:, and the Payment Request will use the email address on the Billing Contact to send the email.

      • You can manually enter an email address in the Send To: field, and the Payment Request will use that email address to send the email.

      • NOTE: If you populate both the Billing Contact: and the Send To:, the email address in the Send To field will be used instead of the Billing Contact email address if they are different.

       

      Chargent Payment Request Popup Window

    3. You can see recent Payment Requests in the Payment Requests related list on the page layout. Click on any Payment Request name to pull up complete details and see the payment status.

    4.  

      Chargent Payment Request Related List

    5. You can also click the "New Payment Request" button to create a Payment Request. The "Send Payment Request Email" field is meant to be used upon create/insert. So when you first create the Payment Request record either with code or by hand if you set the field to TRUE Chargent will send the email.

    6. Advanced Payment Request Usage

      • Any time you create a Payment Request record, Chargent creates a pay link
      • That pay link can be extracted from Salesforce and put anywhere you want it to go, whether you create one at a time or thousands
      • There are a variety of ways that Payment Requests can be created: Apex methods, data loaders, api calls, users creating them one by one, a trigger off of a quote or other custom object, etc.

     

    Custom Development

    Customizing the design of your Payment Request page

    To customize the look and feel of your Payment Request page, you can either customize the sample pages provided as part of Chargent in Step 3 above, or create your own Visualforce pages.

    Chargent's SitePayment visualforce component can also be dropped into your visualforce pages any time you need to take a payment, such as ecommerce systems or customer communities.

    Chargent Payment Request Default Site
    Default Visualforce page SitePayment (prior to customization of surrounding PaymentRequest page).


    Creating your own Pages

    To create your own Visualforce page from scratch, you will need to include the SitePayment page as a component. This is because the SitePayment page is part of the Chargent managed package, so it can't be edited directly. To include it in your own Visualforce page, use the following code:

      <ChargentSFA:SitePaymentComponent />
    or
      <ChargentOrders:SitePaymentComponent />
    or
      <ChargentCases:SitePaymentComponent />
    

    Modifying the CSS inside of our Visualforce

    To make sure that your CSS styles will override the Chargent CSS, you just need to put your styles right after the component in your page that uses the Chargent Site Payment Component. Note that you may need to include the standard CSS stylesheets unless you are handling that on your own:

    Code sample:

    <apex:page showHeader="false" standardStylesheets="true">
       <!-- HEADER -->
       <ChargentSFA:SitePaymentComponent />
       <!-- FOOTER -->
     
       <!-- OVERRIDE CSS LOCATION -->
        <style type="text/css">
         .content {
           width: 34em;
           min-width: 372px;
           font-family: 'Source Sans Pro','Helvtica','Arial', 'san-serif';
           background-color: green;
           padding-top: 10px;
           padding-bottom: 300px;
           border-radius: 100px;
           top: 5%;
           left: 50%;
           border: 5px solid #666;
        }
       </style>
    </apex:page>
    

    The CSS styles used by default are found in style.css and in componentStyle.css.

    The following classes are the primary ones in our Site Payment Component:

    • .content
    • .message
    • .formHeader
    • .link
    • .info
    • .paidmsg

    A full list of classes are found in componentStyle.css

    Using an Intermediary Page with Payment Request

    This is an example of using a custom page prior to passing the user to the Chargent Payment Request Page. It has been simplified for demonstration purposes.

    Initial Page

    <apex:page controller="myController">
      <apex:form>
      <apex:commandButton value="Submit Page" action="{!myMethod}"/>
      </apex:form>
    </apex:page>
    

    Initial Controller

    public class renewal_Controller{
    
      private string req_param;
    
      public pageReference myMethod(){
        req_param = apexPages.currentPage().getParameters().get('req'); 
        Pagereference pr = Page.{YOURPAGENAME};
        pr.getParameters().put('req',req_param);
        return pr; 
      }
    }
    

    In the above example, in the Salesforce Force.com site settings, you configure your site's Active Site Home Page to be the Initial Page above. If the Payment Request configuration is properly completed when a Payment Request link is generated it should be similar to:

    https://mydomain.secure.force.com/initialpagename?req=xxxxxxxxx

    When the user clicks on the button on the initial page it will call the method in the controller. That method will then get the req parameter, create a new pagereference to the second page, append the req parameter to that reference and redirect the user to that page.

    On the second page, include the

    <ChargentSFA:SitePaymentComponent />
    

    on that page where you want it. The component will automatically get the req parameter from the url.

    Custom URL Results Pages

    With Payment Request you can define the pages (URLs) that your web visitors are sent to in certain situations. To control where users are sent when the Cancel button is pushed, set the Cancel attribute. To control where a user is sent upon a successful payment set the Success attribute. To control where the user goes if there was an error or decline set the error attribute.

    NOTE: You can either set these when you call the payment request component OR you can set these values in the Chargent Settings. The attributes sent in the URL as attributes will override the values in the Chargent Settings for the same attribute.

    The component has the below 3 attributes:

    • cancel
    • success
    • fail

    Here is a code snippet to help you set it up:

    <apex:page >
        <ChargentSFA:SitePaymentComponent showAddress="true" cancel="http://cancel-url" success="http://success-url" fail="http://fail-url"/>
    </apex:page>
    

    NOTE: You will need to replace the success-URL, fail-url and cancel-url with your actual URL. e.g., https://chargent.secure.force.com/payrequest