The following items are required to use Chargent Payment Processing:
To take advantage of Chargent's functionality, you must be utilizing the standard Salesforce CRM Opportunity or Cases object depending on the package you install. We also offer the custom Chargent Orders object for applications where Opportunities or Cases are not a perfect fit. Chargent Orders may be connected to any standard or custom object via a Lookup field. It is not required that your Opportunity or Case records point to a separate Account or Contact record. Descriptions of the custom fields and objects attached to these objects can be found below.
You can install Chargent for the first time, or upgrade a current Chargent installation, through the links on our Installation page.
If you are encounter any problems during the installation (such as the screenshot below where you get stuck approving the long list of remote sites) please see our installation troubleshooting section or contact us.
The Chargent installer will automatically add all necessary Remote Site Settings for you. You will be asked during installation of Chargent to "Allow" access to these external sites.
NOTE: The list of sites is long, so sometimes web browsers may not show the "ok" button to get past this screen. If this happens to you, simply zoom out in your browser (Ctrl + - or Command + - on Macintosh)
|Remote Site Name||Remote Site URL|
|Authorize.net AIM Test||https://test.authorize.net|
|AvidiaPay / linked2pay||http://www.linked2pay.com|
|AvidiaPay / linked2pay Test||http://test.linked2pay.com|
|Authorize.net CIM Test||https://apitest.authorize.net|
|Barclaycard ePDQ Test||https://mdepayments.epdq.co.uk|
|Chase Orbital Test||https://orbitalvar1.paymentech.net|
|Litle Transact Test||https://transact-postlive.litle.com|
|Merchant e-Solutions Test||https://cert.merchante-solutions.com|
|Moneris CA Test||https://esqa.moneris.com|
|Moneris US Test||https://esplusqa.moneris.com|
|Network Merchants NMI||https://secure.networkmerchants.com|
|Optimal Payments NetBanx||https://webservices.optimalpayments.com|
|Optimal Payments NetBanx Test||https://webservices.test.optimalpayments.com|
|PayPal PayflowPro Test||https://pilot-payflowpro.paypal.com|
|PayU Latam Test||http://stg.api.payulatam.com/|
If you need to use an endpoint different than the sites automatically installed with Chargent, you can use the Endpoint Override field in the Chargent Gateway record. You will then need to add the endpoint URL as a Remote Site Setting in Salesforce for it to work.
The list of Remote Sites (payment services Chargent integrates with) is very long, so sometimes web browsers may not show the check box and "ok" button you need to click to get past this screen. If this happens to you, simply zoom out in your browser (Ctrl + - or Command + - on Macintosh)
Please note that due to its need for Workflow rules and Scheduled Apex, Chargent currently only works with the Enterprise, Performance, Unlimited, and Developer editions of Salesforce.
If you are on a 30 day trial of Salesforce, the API may be disabled by default. Chargent needs the API to communicate with external payment gateways. Please contact your Account Excecutive and they should be able to enable the API during your trial.
Chargent includes 4 workflow rules to automatically update totals and other field values after transactions occur. As there is a limit of 50 active rules per Salesforce org, if you exceed that limit you may need to deactivate some rules in order to install Chargent. You may also contact Salesforce to request they raise your maximum worflow rules to 300.
Other issues installing Chargent?
Please give us a call at +1-415-275-1115 during business hours Pacific time, or Contact Us. We are here to assist you.
The first thing you should do after installation is assign your Chargent licenses to your users. Our standard installation is 10 users but you may have licensed more. Users who do not have Chargent licenses assigned will not have access to Chargent objects, fields, tabs or related data.
After installing both packages and assigning your users, the first configuration required is your payment gateway. Switch to the Chargent application in the upper-right and navigate to the Gateway tab. This object defines the parameters of your gateway account. You can have more than one gateway configured in Chargent, but if more than one gateway is active, you will need to define the "Gateway" field in the Opportunity, Case, or Order object. (If only one Gateway is active, that Gateway is automatically used).
Click New and select your gateway provider from the list of Record Types. Next enter the required fields for your gateway paying special attention to the Help Text (click on the ? icon) which describes the field names specific to your gateway. Gateway Name is a descriptive field and is not used as part of the integration.
Merchant Security Key
Transaction Security Key
|AstroPay||Web Pay Status Merchant Id||Secret Key||Web Pay Status Merchant Password||N/A|
|Authorize.net||API Login ID||Transaction Key||N/A||N/A|
|AvidiaPay / linked2pay||Login Name||Web Services Key||N/A||Virtual Terminal name|
|Barclaycard ePDQ||ePDQ PSPID||Password||UserID (of API user)||N/A|
|Braintree||Merchant ID||Private Key||Public Key||N/A|
|Chase Orbital||Cert Required||Cert Required||Cert Required||Cert Required|
|Cybersource||Merchant ID||Merchant Admin Password||N/A||Transaction Security Key|
|eProcessing Network||Account Number||RestrictKey||N/A||N/A|
|Forte||Account ID||Location ID||API Key||Secure transaction Key|
|iATS Payments||User ID (Agent Code)||Password||N/A||N/A|
|Merchant e-Solutions||Profile ID||Profile Key||N/A||N/A|
|ModusLink||User ID||Password||Entity ID||N/A|
|Moneris||Store ID||API Key||N/A||N/A|
|Optimal Payments Netbanx||Account Number||Store Pwd||Store ID||N/A|
|PayPal Payflow Pro||Merchant Login||Password||Partner||N/A|
|PayU Latam||Merchant ID||API Key||API Login
(& Account ID in Username field)
|Realex Payments||Merchant ID||Shared Secret and Refund Password, merged by a "@" symbol. Example: secret@refund||N/A||N/A|
|Stripe||(test or live) Secret Key||(test or live) Secret Key||N/A||N/A|
|Vantiv (Litle)||Username||Password||Merchant ID||N/A|
For more information on testing and test card numbers for each gateway, please see our Testing Chargent section below.
The next step is to add the client and payment fields and buttons to your Opportunity, Chargent Order or Case page layout, and enable the Transactions related list.
Page Layouts you can use are provided with the Chargent package, but if you have customized your Opportunities or Cases page layouts, you will need to add the Chargent fields manually. AppFrontier® suggests a layout similar to the one below, with separate sections for Payment, Credit Card and Electronic Check fields. Be sure to also enable Authorize, Charge, Void and Refund buttons under Custom Buttons at the top.
Note: the layout will look different for Cases and Chargent Orders installation but the field names are the same
To enable Authnet "eCheck" or Payflow "ACH" simply add a new section under "Credit Card" titled Electronic Check and add the following fields: Bank Account Name, Bank Account Type, Bank Account Number, Bank Routing Number (ABA) and Bank Name.
Important: In order to ensure that all picklist options are available for Payment Method, Card Type, Payment Status, Bank Account Type, and similar drop-down picklist fields, you must enable all available options for each Opportunity Record Type. If you do not utilize record types you can skip this step. Go to Setup -> Customize -> Opportunities (or Cases) -> Record Types and locate the fields above for each record type you wish to enable with Chargent capabilities. The Edit link will be found under Picklists Available for Editing. If some of your fields are grayed out, this is the problem.
It is important to realize that the Salesforce View Encrypted Data permission is not activated by default and must be added to custom profiles. The encrypted fields are used to ensure that only appropriate users can access payment data such as card numbers, security codes or gateway account information.
Only cloned custom profiles can have the encrypted data permission enabled.
This includes system administrator profiles. Single user-license customers will not be able to enable the permission. AppFrontier® suggests cloning your Standard User profile, or whichever profile(s) will need access to encrypted data.
Pay careful attention to the Custom Object Permissions outlined below in addition to the location of the View Encrypted Data field.
The Chargent Settings tab contains links to help documentation, access to Chargent Custom Settings, and more. There are 4 sub-tabs available in the Chargent Settings tab:
This page contains links to Chargent installation and documentation pages on the AppFrontier.com site.
On this page, you can request access to premium features of Chargent, as well as enter any license keys provided to you by the AppFrontier team.
This tab contains several automated testing tools, which can help Chargent support or your administrator diagnose any Salesforce validation rule conflicts or other issues.
AppFrontier recommends that you ALWAYS test your configuration or any configuration changes in the Salesforce sandbox before deploying to production. Charging cards and bank accounts is serious business, and the utmost in quality assurance measures should be taken at all times.
AppFrontier is not liable for mis-configurations of the Chargent product. If you are not comfortable with this, please ask us for a referral to a consulting partner that has experience with Chargent.
For more information on testing, please see our Testing Salesforce Financial and Billing Systems page.
For submitting test transactions, most payment gateways provide separate test accounts. You can create both test and live gateway records for testing purposes, just uncheck the "active" checkbox on your test gateway when it is not in use.
If you would like to try Chargent quickly and easily, you can sign up for an Authorize.net test account. It takes only a few minutes. The confirmation page will give you the API Login (Merchant ID) and Transaction Key (Security Key) that you need to configure your gateway. Be sure to check Test Endpoint. Stripe also has a developer account signup that just requires an email address, and provides separate API Keys for production and test environments.
When running test transactions, please use the test credit card numbers and parameters provided by your payment gateway. A list of expected responses will be included in the respective documentation.
Payment Gateway Test Credit Card documentation:
After you have completed basic testing with a developer account, we recommend testing a few real live transactions prior to going live with Chargent.
This is because not all features can be fully tested with test transactions, even if you are following along with your payment gateway's recommended tests and expected responses. For example, address verification (AVS) settings cannot be fully tested on most payment gateways, so transactions that were approved in test could be declined when live. It is best to work any issues out before going live.
To run some live test transactions using your own credit card, it is recommended that they are for very low amounts. You can then go to the Transaction record created and click the "Void" button to void the transaction. Note that live transactions do incur per transaction fees (around 30 cents depending on your payment gateway pricing).
For more information on testing phases, parallel systems, and contingency plans, please see our Testing Chargent page.
AppFrontier recommends testing all Salesforce and Chargent configurations in a Salesforce sandbox, prior to moving into production. This is recommended for upgrades or changes in configuration once you are already live with Chargent as well.
You can migrate configuration changes from your sandbox to production using Salesforce Change Sets. Change Sets are a convenient way to move configuration changes from one Salesforce org to another, and only include changes you make under the Setup menu in Salesforce. No record data is included.
To Use Change Sets:
Please note that you will still need to install Chargent into production from our links provided. Change sets are simply a way of moving any custom work you have done from sandbox to production.
For more information on using Change Sets to move configuration updates from your Salesforce Sandbox to your Production Org, please see the Salesforce documentation on Change Sets.
Chargent utilizes standard terminology for online credit card and electronic check processing. As a user of an online payment gateway you may already be familar with Authorize, Charge, Void and Credit. Here are the general definitions as used in Chargent:
Please refer to the administration guide for your particular payment gateway for additional information.
The minimum fields required to process a credit card transaction using Chargent will vary slightly depending on your payment gateway provider and settings. For this reason, we have not made any fields required on the Chargent Order, Opportunity, or Case.
In general terms, however, the following fields should be populated:
Optional but commonly used:
For ACH / eCheck transactions:
Read-Only Informational Fields:
Card Expiration Year Indicator
This field shows the credit card expiration year in an unencrypted format.
Card Expiration Month Indicator
This field shows the credit card expiration month in an unencrypted format.
Card Last 4
This field shows the last 4 digits of a credit card number. It is useful for tokenization configurations where the credit card number is deleted after a successful charge, or other applications where you want a simple way to know which card was used.
A VisualForce page that you can add to the page layout to give you a summary of the card information - Type, Last 4, and Expiration Date. It appears green if the card is > 2 months from expiration, yellow if card is within 2 months of expiration, and red if the card is expired.
The field Amount is commonly used on Opportunities, and provided in our package for Cases as a custom field. In our custom object package Chargent Orders, the Amount field has been renamed to Total, since Chargent Orders features a Subtotal with optional Tax and Shipping fields.
Charge Amount is the field Chargent sends to determine the actual amount of the payment or transaction. This amount must be greater than $0 for charges ($0 authorizations) and will be used for any subsequent Authorize or Charge functions.
If Manual Charge is checked and a Charge Amount is specified, Chargent will only authorize or charge the amount listed. This allows you to perform multiple transactions against a single Chargent Order, Opportunity or Case without the Charge Amount being recalculated each time.
If Manual Charge is NOT checked, we use a workflow rule to copy Balance Due to Charge Amount as we only ever charge the amount specified in the Charge Amount field. Make sure the Update Charge Amount workflow rule exists and is Activated, or replace this with your own workflow rule should you wish to calculate charges a different way. You can also bypass the Amount field entirely, hide it from the page, and simply use Charge Amount on its own for recurring or one-time charges. You can also use Workflow to default Manual Charge to TRUE (checked).
The Chargent Opportunities Transaction package has the following fields that are involved in calculating a payment value:
from the standard Opportunity Amount field, we calculate the
which is the Amount, minus the Transaction Total (the total of all previous Charge and Refund transactions with status=Approved). This then automatically populates the field that we send to the Payment Gateways for a transaction:
The Charge Amount is automatically updated to equal the Balance Due, unless
Manual Charge=True (checked)
In which case the Charge Amount field will not be updated automatically by our code.
Generally we recommend using the Amount field, but if you want to ensure that Chargent only charges a particular number from elsewhere in Salesforce or an external system integration, then set Manual Charge=TRUE and insert the amount to be charged into the Charge Amount field.
One common situation where you want to use Manual Charge=True is an unending recurring billing schedule. If you are running recurring payments with no end date, or total amount or number of payments desired, you may wish to use Manual Charge so the recurring Charge Amount never gets adjusted.
For example, to run a $20 payment each month, set Manual Charge=TRUE and Charge Amount=$20. That way, whether your Amount represents the annual contract value (ACV) of $240, is set to the monthly subscription of $20, or is set to another number, your customer will still be charged $20 every month.
You can use Workflow Field Updates and Triggers to populate any Amount you like based on any calculations you like from any object you want. Then simply insert the resulting value into the Amount field.
If you are using Products on the Opportunities, your Amount is automatically calculated from the product totals and any pricing customizations there. In this case, the best practice would be to add additional calculations needed (such as shipping or tax) as additional product line items.
If you are using an ecommerce system to do one-time payments for online purchases, where ecommerce is handling carts, shipping and sales tax, you should complete calculations in the ecommerce system, then write the final total to be charged to the Amount field and finally use the Chargent API to charge the payment.
If you need to add in additional items such as Tax or Shipping to the Amount prior to collecting a payment, there are a number of options.
The Chargent Orders Transaction package has the following fields that are involved in calculating a payment value:
The 3 of these together sum to populate a formula field called
from the Total, we calculate the
which is the Total, minus the Transaction Total (the total of all previous Charge and Refund transactions with status=Approved). This then automatically populates the field that we send to the Payment Gateways for a transaction:
The Charge Amount is automatically updated to equal the Balance Due, unless
Manual Charge=True (checked)
In which case the Charge Amount field will not update. So if you wanted to use fields somewhere besides the Chargent Orders object, or are doing calculations in another system, you can populate the Charge Amount and set Manual Charge=True.
You can use Workflow Field Updates and Triggers to insert any Subtotal, Tax and Shipping you like based on any calculations you like from any object you want.
The tax field on Chargent Orders should be treated as a Total Tax field. Meaning if you are in Canada and you have GST & HST, do the math first then insert that value into our Tax field.
If you are using an ecommerce system to do one-time payments for online purchases, where ecommerce is handling carts, shipping and sales tax, you should complete calculations in the ecommerce system, then write the final total to be charged to the Subtotal field and finally use the Chargent API to charge the payment.
Transaction Total and Transaction Count will display the sum total and number (respectively) of the Transactions related to this Opportunity. Once the total of Approved charges equals the Amount of the Opportunity, the order is considered to be paid.
The field Payment Received should automatically be updated to reflect this status after transactions are finalized, and has no impact on transaction behavior. Values for Payment Received include None, Partial and Full. Balance Due automatically calculates the difference between Amount and Transaction Total and is a useful field to display below or near Amount. Remember if "Manual Charge" is not checked, the Charge Amount will automatically reset to Balance Due.
Other fields that you may wish to send include the Order Information field, which shows up as the Description in most gateways and email receipts to your customers, and Invoice Number. Not all gateways use the Invoice Number, but you may get more favorable rates if it is populated, and many companies use it for reconciliation.
It is a good idea to always issue refunds or voids from the Transaction Record rather the Opportunity Record. Doing it at the higher level Opportunity, Order or Case Record will attempt to void all transactions which have not yet settled or refund the last transaction.
Voids will cancel a charge before it has been settled. For example, if you charge a card incorrectly you can void it, and it will not be processed when your daily batch settlement happens. Refunds create a new, separate transaction record in Salesforce, while Voids simply change the original transaction from Charge or Authorize to Void.
Many customers like to schedule their recurring billing (Chargent's scheduled Apex) to run early in the morning, and the daily settlement (when the Gateway finalizes the batch of processed transactions) at the end of the business day, to allow for plenty of time to review any transactions if necessary.
If you Refund an earlier transaction within the allowable window (typically 30-120 days depending on your payment gateway), it will refund the entire amount of the Transaction. With most payment gateways it is possible to do partial refunds using Chargent's Partial Refund button, but in some cases even if Chargent sends a different amount for a refund, the gateway references the original transaction amount only. For this reason, we recommend confirming during your testing period that the proper amounts were refunded.
Assuming your payment gateway supports partial refunds, here are the steps you would follow:
Authorize.net: you can ask Authorize.net to enable what is called Unlinked Credits to issue refunds beyond the 120 day window, or refund transactions made in another system, etc. With this setup you would Clone the original Opportunity, Chargent Order or Case with payment information, enter a positive Charge Amount you wish to credit back and click the Refund button with no existing Transactions. Without this feature enabled, Chargent will either end up refunding the entire amount of the original Transaction (or multiple transactions) and/or you will get an error due to a missing reference transaction.
Realex Payments: Realex has two refund modes - Rebate is the primary and you can override in Custom Settings to be Refund. In Refund, Realex Payments will allow you to send whatever amount of money you like. With either you have to append a refund/rebate password in the gateway record setup, to be entered in the Merchant Security key field with "@" character separator - secretkey@refundpassword
1. Recurring Payment Setup
2. Manual Charge Setup
3. Process a Charge and Set the Schedule
To run a single scheduled charge in the recurring batch, first complete the Billing and credit card data as shown in the Manual Charge Setup above.
Every time Chargent calls out to your payment gateway to send a credit card or ACH transaction, it creates a transaction record in Salesforce containing the data it receives in response.
Transactions is a custom object in Salesforce, related to either the Chargent Orders, Opportunity, or Case record (depending on which Chargent Transaction package you have installed). The list of transactions can be found at the bottom of the page:
Almost all the data in a Chargent Transaction record has been received from your payment gateway in response to the callout Chargent made. Key fields include:
Other fields which can be useful include:
The Response Code, Reason Code and other fields in the Chargent transaction have been returned to Salesforce by your payment gateway. If a transaction is declined or there is an error, you can often obtain more information by entering these codes into a search engine, or consulting the documentation provided by your particular payment gateway provider.
If a credit card is declined, a transaction record will be written with Response Status = Declined. There may be Response Codes in the transaction record with additional information provided by the payment gateway (please see Transaction Records for more information and links to response code lookup tools).
You can then attempt the charge again on a later date, contact the customer for updated billing details, or send a payment request to the customer.
Recurring Billing Declines
If a card is declined as part of the scheduled Apex batch that runs recurring billing transactions:
|Gateway Date||Payment date and time|
|Gateway ID||Enter "Check #" or "Cash"|
|Amount||Amount of cash or check|
|Payment Method||Cash or Check|
Most payment gateways will send an email receipt automatically to your customer, as soon as a charge (authorization and capture) goes through. The email address that Chargent sends to the Payment Gateway is the Billing Email field.
You can often control whether a receipt is sent or not by logging into your payment gateway web interface and altering the settings there.
If you don't want your customer to receive the email, or you wish to send them your own email receipt from Salesforce with your branding / formatting, one option is removing the email address from the Billing Email field on the Chargent Order, Opportunity or Case.
Chargent stores all billing and transaction data 100% natively inside Salesforce, so it is relatively straightforward to create your own notification emails based on this data, using the workflow rules and email template functionality provided by Salesforce.
Chargent includes a workflow rule called Customer Receipt, which is also the name of the Email template you can edit.
To enable Chargent customer receipts from Salesforce:
If you are sending receipts from Salesforce, you should disable Email receipts from your Payment Gateway. Most Payment Gateway interfaces have a setting to turn receipts off.
If your payment gateway does not have a receipt setting, you should contact their support. You can also simply leave the Chargent Billing Email field blank, so it will not be sent to the payment gateway.
The Chargent Customer Receipt workflow rule uses the following criteria:
If you are manually entering paper check or cash transactions in Chargent, and donít wish to send receipts for those transactions, you can modify the worfklow rule to add an additional criterion:
To create an custom notification using your own workflow rules, see the examples below.
For more information on workflow rules, please see the Salesforce workflow documentation. We recommend testing all new workflow rules in the sandbox with sample data, to avoid any unexpected behavior.
In Chargent version 2.75, a sample email template for receipts was included as a starting point for you to customize if you wish to send your own receipts.
When a credit card is declined for a recurring subscription transaction, here is a handy way to send an email alert automatically to your customer.
Note that due to a limitation of Salesforce email capabilities, if you have more than 1 custom object called Transaction, you may not be able to select the Chargent transaction record.
For annual subscriptions, sending a renewal reminder 30 days before hand is a best practice (as well as being a legal requirement in some jurisdictions). You can use the Next Transaction Date, which is automatically calculated by Chargent based on the various recurring field values, to drive this email alert 30 days prior.
Chargent can support transactions in more than 150+ different currencies.
Please note that what currencies you can accept, and whether the payments are settled in the currency they are sent as or are converted to a different currency, is determined by your payment gateway and payment processor. So if you wish to accept multiple currencies, you should start with a conversation with your payment processor and gateway. If you are looking for a new payment provider to support a particular currency, please contact us for assistance.
Chargent also supports multiple active payment gateways, so some customers choose to use different payment gateways for different currency transactions. Workflow rules can automate selection of the proper currency based on other criteria, and gateways can be selected through the lookup field or automated via trigger.
First set the Default currency on the Chargent Settings tab, Advanced Settings sub-tab. The default currency will be used in transactions when the Currency field on a Chargent Order, Opportunity or Case is not set (or wasn't passed via API call).
If your payment gateway supports multi-currency, there will be an Available Currencies multi-select picklist on the Gateway page. Choose the currencies here that you wish to be available on the Chargent Order, Opportunity, or Case Currency picklist field (max 100 values).
Please note that you may have to manually add the Available Currencies field to the gateway page layout, depending on if it was available when you first installed Chargent. In addition, go to Setup > Create > Objects > Gateway and select the record type of your gateway to define which picklist values are available for selection on the Gateway page.
If Gateway Available Currencies field is not empty, the Currency field on the Chargent Order, Opportunity or Case will have a picklist of the values from the gateway. --None-- is selected by default.
Please note that you may have to manually add the Currency Visualforce page (inline) to the gateway page layout, and remove the old Currency field if you installed Chargent before version 3.80.
The Currency picklist on the Chargent Order, Opportunity, or Case object contains selected values from the Available Currencies picklist on the gateway that is currently populated in the Gateway on the Chargent Order, Opportunity, or Case. Chargent will pass this currency value to the payment gateway when initiating a transaction.
If --None-- value is selected, Chargent will submit the value from the Default Currency field on the Chargent Settings tab. If a Default currency wasn't configured, it will use USD as a default value.
Chargent uses ISO 4217 standard in internal mapping for currency values. E.g. if you pass United States dollar currency via API, we'll send USD or 840 value on the gateway side (depending on the particular gateway).
In case no currency was passed via API, we'll use the Default currency from the Chargent Settings.
If you pass a currency which is not contained in Chargent's internal mappings, it will be passed directly to the gateway without changes. E.g. if you pass "MyMadeUpCurrency" currency via API, we'll send "MyMadeUpCurrency" value to the gateway, as it is not described in ISO 4217. You can use this feature to directly submit ISO values also: if you pass "GBP" currency via API, we'll send "GBP" value to the gateway.
Chargent contains mappings for over 150 currencies in its Available Currencies field. Here are some of the more popular currencies.
Please note that not all these currencies are accepted by all payment gateways, and we may be able to enable additional currency support based upon your requirements.
If you are using Advanced Currency Management, the Salesforce feature which keeps track of exchange rates between currencies over specific date ranges, you will need to use the Chargent Orders transaction package. This is because Advanced Currency Management disables roll-up summary currency fields on the Opportunity, which Chargent needs to calculate balances. Running transactions from the Chargent Order object should work fine in this case, and the Amount can be pulled via a trigger or manually from the Opportunity.
Chargent provides a very flexible, lightweight system for managing subscription billing, installment payments, and recurring charges. There are two basic parts to setting up recurring payments:
More details on all of these aspects of Chargent's recurring billing functionality are below.
Chargent customers have the ability to create scheduled, recurring transactions against Opportunities (SFA), Cases or our custom object "Chargent Orders" (each available separately). The first step is to enable the "Scheduled" process which will run automatically each day to process recurring transactions. Go to Setup -> Develop -> Apex Classes and click the "Schedule Apex" button as shown below.
The next page will allow you to configure the parameters of your scheduled process. Please pay attention to the following choices:
Now that all the fields and scheduled processes are in place, let's discuss how it all works! The first critical thing to understand is that Chargent Recurring uses only the "Charge Amount" field. Unless you have the "Manual Charge" checkbox set and a related Charge Amount, the field will equal the Opportunity or Case "Amount" or "Total" on Chargent Orders. This means that it is possible to charge the customer the full amount multiple times unless you stop on "Balance Due" (explained below).
This field is critical to the recurring process. Although an option exists for "Once" Chargent will assume that any value other than those listed here will not be processed automatically. The notes on processing time assume that the scheduled process is running 7 days per week, 365 days pr year.
Note: There is a difference between a "Manual" (buttons) and "Recurring" (apex batch) transaction. As such, if you set a payment frequency of monthly and initiate a manual charge prior to the next scheduled transaction, the customer will likely be charged again when the schedule is run.
To prevent this issue, we recommend moving the Payment Start Date into the future to begin a new cycle the following period. You can also edit the Transaction record and check the "Recurring" checkbox to count the manual charge toward the payment cycle.
For more information see What Determines Recurring Charges? below.
This field is dependent on Payment Frequency, which is why we address it second. This critical field determines the length of time the process will run. Think of the field name as "when should this process stop running?". Chargent offers you four options to manage the payment schedule of a recurring transaction. If this field is left blank, the payment schedule will run indefinitely.
Chargent requires a value of "Recurring" to include a record in its batch. If Chargent discovers a problem with the transaction such as a declined form of payment, the payment status will change to "Error" and no further transactions will be processed until the status is changed back to "Recurring". You may use the "Stopped" status to temporarily pause recurring transactions. When Chargent reaches a stop event, such as Balance Due, End Date or Count, it will change the status to "Complete".
Manual Charge should always be checked for recurring payments, since it keeps the Charge Amount field the same. If unchecked, the Charge Amount will be recalculated based on the balance due (which could go to $0 after the first payment).
This optional field can be set to a value (1-31) and recurring charges from here out will be done on that day of the month. Regardless of how long it took to get it paid last time. If a card is declined, then finally approved a week later, the customer will still be charged on the same date next month, rather than 30 days from the previous successful recurring transaction.
This field is not used in Daily, weekly, or Biweekly recurring transactions, but will work for any time periods Monthly or above. If this field is set to 31, Chargent will automatically charge on the 30th for months with 30 days, or on the 28th/29th of February.
Chargent runs its logic and indicates when the next recurring transaction is going to occur in this field. Useful for reporting, and double checking your configuration.
Please note that the Next Transaction Date field cannot be modified, as it is set automatically by Chargent when a record is saved. For this reason, we recommend setting it to Read Only at the Page Layout level (not the field level security level). See the Chargent-provided page layouts for the suggested setting.
Please be very cautious if you use Validation Rules or Required fields on your Opportunities, Cases or Chargent Orders with Chargent recurring process. Validation rules can prevent the Opportunity, Order or Case record from saving properly after a transaction occurs, and because Recurring transactions run in a batch you would only see the errors in the Apex Jobs monitoring page in Salesforce.
Certain validation rule problems can result in duplicate transactions, so please be sure to test any validation rules in Sandbox prior to deployment. Contact us for additional assistance.
Chargent treats manual and recurring transactions separately. Many customers wish to charge the first transaction manually, to see if it goes through, before setting a recurring billing schedule.
The key thing to remember when running a manual transaction is that after you do a manual transaction, you need to set the Payment Start Date ahead a month or year, etc. to the day when you would like the customer to next be billed automatically, or use the new Charge Date field to indicate the day of the month when they should be billed. Because Chargent does not see manual charges as part of the recurring schedule, if you do not set the Payment Start Date ahead or the Charge Date is not populated, the following day it will once again attempt a transaction as part of its recurring schedule.
The Payment Start Date is the most effective way of preventing charges before a certain date, as Chargent does not evaluate records for possible charging until the Payment Start Date is today or in the past. So if my Charge Date is 15 and Payment Start Date is set for June 16th, the next transaction attempted will be July 15.
Records have a transaction processed if they meet the following criteria:
The status field is key in the recurring billing configuration. An Opportunity or Order will only be considered for processing if the Payment Status = "Recurring". Anything else and it gets ignored.
When Chargent runs its scheduled batch (daily (recommended) or however you have the Scheduled Apex set), the first pass is to find all Payment Status="Recurring" records where Payment Start Date is either the current day or in the past.
The second pass is to look at the Charge Date field, and see if the Last Approved Transaction (that is checked as Recurring) is within the current month. If not, for Payment Frequency=Monthly records Chargent will charge on the Charge Date within the month that it is supposed to be charged.
Finally, if no Charge Date is set, Chargent evaluates the "last recurring transaction" and ensure that it has been X days since (where x = 29/30/31 in the case of monthly, 364/365 in the case of annual, etc.). Chargent only looks at the date of the last recurring transaction that was successful (Response=approved, Recurring=true, not voided).
Opportunities or Chargent Orders that meet the two criteria will then be processed, and a transaction with the Recurring field = true will be created (assuming the charge is successfully approved).
Please refer to the Usage Examples in our documentation for complete step-by-step instructions for combining manual and recurring transactions.
The Charge Amount field is the amount to be charged or authorized by the next transaction. If there are multiple charges, it will automatically reflect the Amount of the Opportunity or Order, minus the total of past successful charges (also shown in the Balance Due field). Check the Manual Charge field when you want to charge an amount different than the amount due on the Opportunity or Order. This will prevent the Charge Amount from automatically being calculated and updated.
One thing to be aware of when using this manual override, however, is that your Charge Amount will not be prorated. So if the Amount is $100, and you set the Charge Amount is $30, Chargent will charge 4 x $30. The system does not automatically prorate the last amount to equal the remaining balance (if less than the Charge Amount).
To automatically set the Charge Amount to the final balance that is smaller than previous installments:
When the next to last transaction gets run, the totals update and the charge amount would be updated at that time preparing it for the final charge.
Chargent has a Webservices API that is available as an extension to the standard SOAP API that Salesforce offers, so they can be called in the same way that you interact with other parts of the Salesforce API. Please see our Developer documentation for details.
Chargent's Payment Request feature allows you to generate requests for payment to send to your customers, and customize your own Force.com site with an integrated, hosted credit card form.
Chargent's Account Updater feature allows you to send automated notifications of expiring credit cards to your customers, and have customers update their payment information in Salesforce through a secure online form.
With Chargent's Payment Console feature you can submit payments directly from a Salesforce popup window to your payment gateway, without saving or storing account numbers in Salesforce. Payment Console supports credit card / ACH transactions and tokenization.
Because Chargent is a flexible payment payments framework that is 100% Salesforce native, it is easy to customize it to work with other Salesforce business processes and systems that you have also integrated into Salesforce.
Chargent offers prebuilt integration functionality with several partners.
Chargent has a built-in integration with Accounting Seed, where successful charge and refund transactions in Chargent automatically create corresponding Cash Receipt and Cash Disbursement records in Accounting Seed. Please see the documentation PDF or view the video for complete details.
Chargent connectors for FinancialForce Accounting and Supply Chain Management add easy-to-use payment features directly in FinancialForce. Please contact us for complete details.
For information on using Chargent with FinancialForce FFA, SCM, and ClickLink, please see our FinancialForce page.
Chargent also integrates with Ascent ERP. Please contact us for complete details.
With FormAssembly's new Chargent integration, you can now integrate your credit card payment forms with Salesforce. Create donation forms, event reservations, order forms, appointment bookings, and much more. Please visit FormAssembly's Chargent Connector page for more information.
Chargent can be used with Salesforce Customer Communities and Partner Communities, as well as the legacy Customer Portal and Partner Portal products. Empower your customers and partners to make payments, update billing information, view invoices and more. Please see our guide to Enabling Payments in Salesforce Customer Communities and Partner Portals
For best practices related to security and PCI Compliance inside Salesforce, please see our Security Implementation Guide.
It is possible to migrate from other payment systems to Chargent. Assuming you can export the data from the old system, it is a fairly straightforward data loading process into Salesforce.
For manual charge usage of Chargent, the migration is quite straightforward and requires only Amount and payment information be transferred to Salesforce.
Recurring billing situations require a bit more care so that there is no interruption in billing or duplicate charges. The most important field is Payment Start Date, to prevent premature recurring charges from happening prior to your cutover date. Make sure the Payment Start Date is always in the future, on or after the cutover date beween systems.
Chargent uses past Transactions and their Gateway Date to calculate the next date, but in data migration you should not turn off the old system after proplerly testing before cutoff date. As soon as you get a successful transaction that is part of Chargent's recurring schedule, you should be good to go from then forward.
We recommend loading data into "Transactions" and making sure you set these fields:
If you are using tokenization, you should be able to run a report at your gateway, and import this data into the Token field.
AppFrontier® has a number of partners who are experts in data migration and payment systems who we can refer you to for assistance if needed.
Many Chargent customers have added custom Transaction buttons for Cash and Checks which don't hit the gateway. Because the IDs for custom fields change in each Salesforce instance, we have not packaged these as part of Chargent.
If you would like to create custom buttons for other payment types (Add Cash, Add Check), here is an example of how to do it.
Click the native "New Transaction" button on Opportunities or Chargent Orders and modify the link IDs as appropriate. This is essentially a custom button on Transactions which we place on the related list as "Add Cash" or "Add Check". Currently our normal buttons do not take into Account "paper" checks vs electronic. All the field IDs in the link (e.g. "00N80000002wnsm") should be replaced with your unique field IDs. These map to (in order):
Display in existing window without sidebar or header
Button or Link URL
Salesforce's Track Field History feature provides a useful audit trail for reviewing or troubleshooting past changes. Changes to tracked fields are displayed in the History related list. You can track up to 20 fields per standard or custom object, and the data is retained for 18 months.
AppFrontier recommends that you enable history tracking on key fields for auditing purposes, and to be able to review when and how fields were updated should there be questions in the future.
The 20 fields you will want to track will depend on your organization and how you are using Chargent. If you are doing ACH instead of Credit Card transactions, for example, you will want to select the bank fields, and if you are not doing recurring transactions you may not wish to select those fields. You may also wish to track other standard or custom fields on an object that may be unrelated to Chargent, which will reduce the number of Chargent fields you can track.
Here are our starting recommendations for Chargent fields to track:
Chargent Order / Opportunity / Case
Note that most fields on the Transaction record should not be edited, and users may not have permissions to change fields depending on how you have configured Chargent.