AppFrontier

Documentation Chargent Configuration

DOCUMENTATION
Chargent Payment Processing for Salesforce


 

Installation



Requirements

The following items are required to use Chargent Payment Processing:

  1. Salesforce Enterprise or Performance / Unlimited Edition
  2. Chargent Gateway Base package plus the Chargent Orders Transaction package
  3. A Payment Gateway account with one of our integration partners

To take advantage of Chargent's functionality, you will be populating billing and payment details on Chargent Orders custom object, which may be connected to any standard or custom object via a Lookup field.

Installation

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.


Installation Troubleshooting

Remote Sites List

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)

Zoom out to see all remote sites

Salesforce Edition Requirements

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.

Trial Salesforce Accounts

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.

Workflow Rule Limitations

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.

Setup



Manage Licenses

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.

  1. Click on Setup > View Installed Packages

  2. Beside Chargent Orders, click Manage Licenses.

    • If you do not see a Manage Licenses link, you may be looking at the Chargent Base package instead of the Chargent Orders package.

    • If you are installing into a Sandbox, licenses are not assignable to users and Chargent can be tested without assignment.

  3. Assign the licenses to the users you wish.


Gateway Setup

Using the Gateway Setup Wizard

Note: The Chargent Gateway Wizard is available in Chargent 5.50 and later versions.

After installing both Chargent Base and Chargent Transaction packages and assigning your users, you will want to set up the connection to your payment gateway. AppFrontier integrates with over 60 payment gateways.

In Salesforce you will need to make sure the the Remote Site Setting of the gateway you are going to use is Active. If it is already active then you can skip this step.

  1. Click the gear icon on the top right and choose Setup
  2. In the search window enter Remote Site and click on the Remote Site Settings option
  3. Find the payment gateway you are going to use and click Edit
  4. Check the box that says Active next to all remote sites for that gateway
  5. Click Save

Setup your Gateway using the Chargent Setup Wizard.

  1. Click on the AppLauncher on the top left side in Salesforce.

  2. App Launcher

  3. Select Chargent as the App
  4. Select the Chargent Settings Tab
  5. Choose Chargent Setup Wizard
  6. Follow the prompts to configure your gateway

Gateways

You will need the following information to configure the gateway:

  • What Gateway you will be using
  • Test Login / Live Login credentials - (If you are looking to do live tests from your Salesforce Sandbox you will need to also use the Endpoint Override URL)
  • Will you be using Tokenization (recommended)
  • What currency will you be using
  • What Payment Methods will you be accepting?

Gateway Emulation

Note: If your gateway is not listed it may be supported via the Authorize.net emulator. Please see our list of supported gateways on our Gateways page. If your gateway is supported using the Authorize.net emulator you will want to also make sure the endpoint override is added to the Remote Site settings.

  1. Click the gear icon and choose Setup in Salesforce
  2. In the search window enter Remote Site
  3. Click the New Remote Site button on the top
  4. Enter the following

    • Remote Site Name (this is generally your gateway name)
    • Remote Site URL (this is the Endpoint Override you would have used in setting up your gateway).


Manual Gateway Setup

Please note: Manual gateway setup applies to installed Chargent versions earlier than 5.50.

  1. Click on the AppLauncher In Salesforce

  2. App Launcher

  3. Search and click on for Gateways
  4. Click New
  5. you will need to map the Merchant ID, Merchant Security Key, Merchant Reference, and Transaction Security Key based on the information that is next to your gateway name below (ex: the Merchant ID field in Salesforce for Authorize.net would be the Authorize.net API Login ID).


Gateway

Merchant ID

Merchant Security Key

Merchant Reference

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
BluePay Account ID Secret Key N/A N/A
BlueSnap API Username API Password N/A N/A
Braintree Merchant ID Private Key Public Key N/A
Chase Paymentech N/A N/A N/A N/A
Cybersource Merchant ID Merchant Admin Password N/A Transaction Security Key
eProcessing Network Account Number RestrictKey N/A N/A
eWAY API Key Password N/A N/A
Ezidebit Digital Key Digital Key N/A N/A
Fat Zebra User ID Password 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
Merchant Warrior UUID API Key API Passphrase N/A
ModusLink User ID Password Entity ID N/A
Moneris Store ID API Key N/A N/A
NMI Username Password N/A N/A
PayPal Payflow Pro Merchant Login Password Partner N/A
Paysafe (formerly Optimal Netbanx) Account Number Store Pwd Store ID N/A
PayTrace Username Password N/A N/A
PayU Latam Merchant ID API Key API Login (& Account ID in Username field) N/A
Realex Payments Merchant ID Shared Secret and Refund Password, merged by a "@" symbol. Example: secret@refund N/A N/A
SecureCo MerchantAccountID Bearer Token N/A N/A
Stripe (test or live) Secret Key (test or live) Secret Key N/A N/A
USAePay Key PIN N/A N/A
Vantiv (Litle) Username Password Merchant ID N/A
  1. Setup the following Gateway fields

    • Check the Active box - To make the Gateway active
    • Use Tokenization - If you are planning on using tokens (see our tokenization documentation).
    • Available Card Types - Select the cards you will be accepting (this is based on your gateway settings and what card types they can process - Visa, MasterCard, American Express, etc..)
    • Available Payment Methods - Will you be accepting just Credit Cards or ACH (also known as electronic check, e-check, or direct debit)
    • Available Currencies - What currencies will you accept (this is based on your payment gateway and the currencies they accept payment in.
    • Credit Card / Bank Account Data Handling - This lets Chargent know when to clear the information in Salesforce. You have 4 options.

      • Never Clear
      • Clear After Successful Charge
      • Clear After All Transactions
      • Clear When Token is Present


When using Payment Requests or Payment Console the following should also be set.

  • Available PR Transaction Types

    • Charge Full Amount - Charges the credit card immediately
    • Authorize Full Amount - This option won’t charge the card but only holds the funds available until you charge the card.
    • Authorize Minimum Amount - This option won’t charge the card but only holds the minimum amount that your gateway will allow. You will need to charge the correct amount in order to capture the transaction.

  • Show Charge Button
  • Show Authorize Button

Gateways

Gateways Advance Tokenization


For more information on testing and test card numbers for each gateway, please refer to the linked Gateway guides in the table above, and see our Testing Chargent section below.

Gateways Authorize.net

Gateway Fields

  • Active: Enables a Gateway record to be used, in the same way that other parts of Salesforce have an Active checkbox. You may wish to have multiple gateway records, especially if you have a separate test account, and keep some deactivated.

  • Test Endpoint: Test Endpoint sends transactions to a separate test server or sandbox environment, which cannot be used for live transactions. We recommend keeping Test Endpoint checked until you are ready to capture live transactions.

    Note: If Chargent is installed in a Salesforce Sandbox, for security purposes all transactions are sent to the test endpoint, whether or not this field is checked.

  • Endpoint Override: This field enables you to enter a custom URL to send transactions to. It is primarily used for payment gateways that run Authorize.net emulation on their own server URLs. It is also required if you want to send live transactions from a Salesforce sandbox account. For security purposes, Chargent sends all transactions to the test account from Salesforce sandboxes, regardless of whether "Test Endpoint" is checked or not. Note that for Endpoint Override to work, the domain must be added under Salesforce's Remote Site Settings first.

  • Debug: Debug can be useful for troubleshooting and verifying the values being sent to the payment gateway, but should only be enabled temporarily. It displays the complete XML or HTTPS request that is being sent to the server and response strings in the popup window when you click the appropriate button on your screen (Charge, Authorize, etc.). Note: This feature should only be used by System Administrators or trusted users as it may contain decrypted payment data!

  • Require AVS: prevents the transaction from being submitted to the gateway without billing address fields being populated. Generally AVS settings are controlled through your payment gateway, but this will prevent Chargent from sending the transactions at all if the data is not present in Salesforce.

  • Require Card Security Code: The Card Security Code (CSC, or CVC) is required automatically in newer versions of Chargent. This setting is for older versions of Chargent where the CVC field in present. It creates a Validation Rule for this field to be filled out before saving the Chargent Order.

  • Use Tokenization: should be checked in gateways that support it if you wish to use stored tokens. If checkbox is unchecked, credit card numbers will be used for transactions.

  • Accounting Seed Integration: enables the integration with the Accounting Seed accounting and ERP software for Salesforce when checked.

  • Gateway Response: Stores the entire response from the gateway. The same data that debug mode shows in a popup, but the credentials and credit card data is masked.

  • Credit Card Handling: Allows you to choose if/how credit card data is stored in different scenarios. For PCI Compliance reasons, many customers do not wish to store credit card data. The options are as follows:

    • Never Clear: Chargent will not remove any card data automatically.
    • Clear After Successful Charge: Chargent will clear the credit card number, expiration dates and card security code only after a successful charge is run.
    • Clear After All Transactions: The credit card number, expiration date and card security code will be erased after any transaction (Charge, Void, Refund)
    • Clear When Token Present: Only when a token is present in the token field, will the credit card number, expiration date and card security code be cleared.

Multiple Gateways

  • Chargent supports multipleactive gateways. If only one gateway is active, it will be used for each payment transaction. With multiple gateways, you need to provide a lookup to the desired gateway record for each Chargent Order you are submitting transactions from.

  • Many customers use Chargent's multiple gateway functionality to keep payments for different business entities separate while using a single Salesforce account, or for supporting multiple geographies / currencies that might require multiple payment gateways.

Gateway-Specific Setup Guides

  1. Authorize.net and Salesforce Integration using Chargent.
  2. AvidiaPay / Linked2pay and Salesforce Integration using Chargent.
  3. BluePay and Salesforce Integration using Chargent.
  4. BlueSnap and Salesforce Integration using Chargent.
  5. Braintree and Salesforce Integration using Chargent.
  6. Chase Orbital and Salesforce Integration using Chargent.
  7. CyberSource and Salesforce Integration using Chargent.
  8. eWAY and Salesforce Integration using Chargent.
  9. Ezidebit and Salesforce Integration using Chargent.
  10. Fat Zebra and Salesforce Integration using Chargent.
  11. Forte and Salesforce Integration using Chargent.
  12. iATS Payments and Salesforce Integration using Chargent.
  13. Merchant e-Solutions and Salesforce Integration using Chargent.
  14. Merchant Warrior and Salesforce Integration using Chargent.
  15. ModusLink and Salesforce Integration using Chargent.
  16. Moneris eSELECTplus and Salesforce Integration using Chargent.
  17. Network Merchants NMI and Salesforce Integration using Chargent.
  18. PayPal Payflow and Salesforce Integration using Chargent.
  19. Paysafe (formerly Optimal Netbanx) Salesforce Integration using Chargent.
  20. PayTrace and Salesforce Integration using Chargent.
  21. Realex Payments Salesforce Integration using Chargent.
  22. Stripe and Salesforce Integration using Chargent.
  23. USAePay and Salesforce Integration using Chargent.
  24. Vantiv and Salesforce Integration using Chargent.



Chargent Settings Tab

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:

  1. Chargent Help
  2. Chargent Feature Activation
  3. Advanced Settings
  4. Troubleshooting Tools

Chargent Help

This page contains links to Chargent installation and documentation pages on the AppFrontier.com site.

Chargent Feature Activation

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.

Advanced Settings

Most of the settings on this tab relate to the Payment Request and Account Updater premium features of Chargent. However, the following fields will be of interest to all Chargent customers:

    • Chargent Admin Email Address - Enter the system administrator's email address. If there are unresolved errors with any transactions, this email address will receive a notification.

    • Fill Billing Address - Check this box to have Chargent's Billing Address fields in the Chargent Order automatically populated from the Billing Address fields in the related account.
       
      Note that this only works if all Billing Address fields are empty on the Chargent Order, and Billing Address fields are populated on the related Account.

 

Troubleshooting Tools

This tab contains several automated testing tools, which can help Chargent support or your administrator diagnose any Salesforce validation rule conflicts or other issues.

Chargent Advanced Settings


Connecting Chargent Orders to Opportunities or other Objects

Chargent Orders is separate from Opportunities, as sales processes and billing processes can often have conflicting requirements. To relate the two screens, simply create a lookup field which allows you to tie the Opportunity and Chargent Orders objects together, then add the Chargent Orders Related List to the Opportunity page layout. You can then easily create a Chargent Order and view related Chargent Orders from the Opportunity.

For more information on relating Chargent Orders to Opportunties, please see our Chargent Orders with Opportunities Guide

Chargent Anywhere

The same instructions from the Chargent Orders with Opportunities Guide can also be followed to relate Chargent Orders to other standard or custom objects in Salesforce.

To embed payment buttons directly on any object, we offer the Chargent Anywhere extension package. Chargent Anywhere works with the Chargent Orders object in order to allow you to process payments from any Salesforce Object while still allowing your Transactions to live on the Chargent Order in Salesforce. For more information on Chargent Anywhere please Contact Us.


Testing



Chargent Testing

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.

When migrating billing records from another system, always test with small batches (~10) before moving into full production.

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.


Developer / Sandbox Accounts

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. Some gateway test responses will be determined by the Charge Amount.

Payment Gateway Test Credit Card documentation:


Testing Phases

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.



Moving from Sandbox to Production


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:

  1. Go to Setup > Deploy > Outbound Change Sets
  2. Select the Components and Profiles that will be part of the Change Set
  3. Save
  4. Select the name of the Salesforce organization you want to send the Change Set to
  5. Click Upload
  6. In the target Salefsorce organization, go to Setup > Deploy > Inbound Change Sets
  7. Find the Change Set and click Deploy

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.


Using Chargent


Charges and Transactions

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 Refund. Here are the general definitions as used in Chargent:

  • Authorize - Authorization Only, generally for checking a card prior to a future charge or holding funds prior to merchandise shipment.

  • Charge - Either does an Authorization and Capture immediately, or Prior Authorization and Capture if an Authorization had been previously submitted. This button changes to Charge Authorized if you view an Authorization Transaction record in Chargent.

  • Refund - refunds a transaction that has been previously settled (between 1-120 days typically)

  • Void - cancels a transaction that has not yet been settled (Charge from same day typically) or expired (Prior Authorization)
  • Credit - can send funds not tied to a previously captured transaction. Only supported on some payment gateways.

Please refer to the administration guide for your particular payment gateway for additional information.


What fields are required?

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.

In general terms, however, the following fields should be populated:

  1. Billing First Name and Billing Last Name (these automatically populate Credit Card Name)
  2. Billing Address
  3. Billing Zipcode
  4. Payment Method (Credit Card or Check)
  5. Card Type (Visa, Mastercard, Amex or Discover)
  6. Card Number
  7. Card Expiration Month (2 digits - MM)
  8. Card Expiration Year (4 digits - YYYY)

Optional but commonly used:

  1. Billing Email (some gateways will send a receipt to your customer)
  2. Invoice Number (may reduce your fees, useful for reconciliation)
  3. Order Information (may appear on customer receipt as description)

For ACH / eCheck transactions:

  1. Bank Account Type (Checking, Savings or Business Checking)
  2. Bank Account Number
  3. Bank Routing Number
  4. Bank Account Name (person or company name on bank account)
  5. Bank Name (name of the financial institution)

 


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.

Card Details
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.



Calculating & Customizing Amounts

Total
In Chargent Orders, the Amount field has been renamed to Total, which is the sum of the Subtotal field plus the optional Tax and Shipping fields.

Charge Amount
Charge Amount is the field Chargent sends to the payment gateway, so this determines the actual amount of the payment. This amount must be greater than $0 for charges ($0 authorizations) and will be used for any subsequent Authorize or Charge functions.

Manual Charge
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 without the Charge Amount being recalculated each time, a freqeuent requirement for recurring billing.

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.



Chargent Order Amounts

The Chargent Orders Transaction package has the following fields that are involved in calculating a payment value:

Subtotal
Tax
Shipping

The 3 of these together sum to populate a formula field called

Total

from the Total, we calculate the

Balance Due

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:

Charge Amount

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.

Other Transaction Fields

Transaction Total and Transaction Count will display the sum total and number (respectively) of the Transactions related to this Chargent Order. Once the total of Approved charges equals the Total of the Chargent Order, 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.


Refunds and Voids

It is a good idea to always issue refunds or voids from the Transaction Record rather the Chargent Order Record. Doing it at the higher level Chargent Order 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.

Chargent Transaction List with Refund Screenshot

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.

Partial Refunds

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:

  1. Click on the Transaction record in question
  2. Press the Partial Refund button
  3. Enter the Amount to be refunded in the resulting dialog box
  4. It is possible to make multiple Partial Refunds against a single transaction, but the refunds cannot add up to more than the original Transaction amount.

Gateway-Specific Notes on Refunds

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 Chargent Order 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

Usage Examples

Charge a Credit Card manually from Salesforce, and then set a Recurring Payment schedule

1. Recurring Payment Setup

  1. Enter an Subtotal or Total in the Chargent Order record
  2. Set Manual Charge to "TRUE" and enter Charge Amount (this prevents the Charge Amount from recalculating based on Total minus Transaction Total)
  3. Set Payment Method to "Credit Card"
  4. Choose a Payment Frequency (anything from daily to Biennial)
  5. OPTIONALLY choose a Payment Stop (Date, Count, Balance Due or unending)
  6. OPTIONALLY choose a Charge Date to have the customer billed on the same date of the month
  7. Set Payment Status to "Recurring"
  8. Save the record

Chargent Recurring Fields Screenshot

2. Manual Charge Setup

  1. Set Card Type (Visa, Mastercard, Amex or Discover)
  2. Set Set Billing First Name and Billing Last Name (these automatically populate Credit Card Name)
  3. Set Card Number
  4. Set Expiration Month (2 digits)
  5. Set Expiration Year (4 digits)
  6. Set Billing Address and Zipcode
  7. OPTIONALLY Set Billing Email (some gateways will send a receipt to your customer)
  8. OPTIONALLY Set Order Information and Invoice Number fields
  9. Save the record

Chargent Credit Card Fields Screenshot

3. Process a Charge and Set the Schedule

  1. Press the Charge button
  2. A popup will tell you if the charge is approved or declined.
  3. Click ok.
  4. The page will refresh and a Transaction will appear on the related list
  5. Set the Payment Start Date ahead for when the next transaction should occur (one month, one year, etc.)
  6. OPTIONALLY choose a Charge Date to have the customer billed on the same date of the month
  7. Save the record


Single Scheduled Transaction

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.

  1. Set Payment Frequency to "Once"
  2. Set Payment Status to "Recurring"
  3. Set Payment Start Date to the date you want the single charge to run.
  4. Save the record


Chargent Credit Card Processing Response Screenshot

Run a Salesforce ACH transaction using Chargent

  1. Enter a Total OR set Manual Charge to "TRUE" and enter Charge Amount
  2. Set Payment Method to "Check"
  3. Set Bank Account Type
  4. Enter Bank Account Name (The name of the person who owns the account.)
  5. Enter the Bank Routing Number (ABA Routing)
  6. Enter the Bank Account Number
  7. Enter the name of the bank in the Bank Name field. (e.g., First Federal Bank)
  8. Save the record
  9. Press the Charge button

Refunds

  1. Click on the Transaction record in question
  2. Press the Refund button
  3. Same day exception: If refunding a transaction that has not yet settled, use Void instead

Partial Refunds

  1. Click on the Transaction record in question
  2. Press the Partial Refund button
  3. Enter the Amount to be refunded in the resulting dialog box
  4. It is possible to make multiple Partial Refunds against a single transaction, but the refunds cannot add up to more than the original Transaction amount.

Chargent Credit Card Processing Response Screenshot


Transaction Records

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 Chargent Orders as a Master-Detail relationship. The list of transactions can be found at the bottom of the page:

Chargent Transactions Related List Screenshot

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:

  • Transaction ID: An identifying name for the transaction, automatically generated by Salesforce.

  • Gateway Date: The date and time of the transaction.

  • Gateway ID: The identifying transaction number received back from the payment gateway (sometimes called a transaction ID or transaction number on the gateway side)

  • Type: The type of transaction submitted (Charge, Authorization, Refund, Void)

  • Response Status: The status of the transaction received from the payment gateway (Approved, Declined, Error)

  • Response Message: Additional transaction details received from the payment gateway ("This transaction has been approved." etc.)

Other fields which can be useful include:

  • Recurring: This checkbox is set by Chargent, and shows whether a particular transaction was created by the recurring batch or not.

  • Authorization: The authorization code returned by the payment gateway.

  • Response, Response Code, Reason Code: Additional information from your payment gateway. Some of these can be useful in understanding declines or errors, so check your payment gateway documentation for more information.

  • Gateway Response: The full text of the response from your payment gateway, sometimes useful in troubleshooting a transaction.

Chargent Transaction Record List Screenshot


Understanding Response Codes and Messages

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.


 

Check Response Codes from Chargent Transactions


Creating and Updating Transaction Records

  • To manually create transaction records for paper checks, cash, or other payment methods not automatically controlled by Chargent, please see cash and paper check instructions.

  • Chargent creates a new Transaction record for each Charge, Authorization, or Refund. The only time that we update an existing Transaction record is in the case of a Void. In this case, the Transaction Type of an existing Charge, Authorization or Refund is changed to VOID, since the Transaction was effectively canceled.

  • Chargent references existing transactions when running a recurring billing schedule, so be careful not to edit recurring transactions. In general, making any changes to existing transaction records is not recommended.

  • Historical transactions can be imported into Chargent, but it takes data migration expertise to do everything correctly. Please contact us for additional advice and/or a referral to a Chargent consulting partner who can assist you.

Additional Notes on Transactions

  • As of 5.20 Chargent does update transactions that were originally started in Chargent with the latest status from certain payment gateways. See our Authorize.net guide as an example of how this works.

  • Chargent will generally attempt to send any transaction to your payment gateway, unless it can determine ahead of time that the charge will be declined (for example, an invalid card number length or expiration date in the past).

  • If the Gateway ID field says Chargent Error, this means that Chargent prevented the transaction from being sent to your payment gateway. If there is another value in the Gateway ID field, it means that the data in the Transaction record was generated by your payment gateway and sent to Chargent.

  • Each payment gateway handles Duplicate Transactions differently. Some gateways will decline a second transaction where the billing information and amount match a previous transaction from that day. Other gateway may allow it but may flag it as a potential duplicate.


Declined Charges

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:

  1. Payment Status will automatically change from Recurring to Error.
  2. Once you have received updated billing information, change the Payment Status back to Recurring.
  3. If you have processed a charge manually outside of the recurring billing schedule by clicking the Charge button, be sure to set the Payment Start Date ahead to the next time the record should be billed, to avoid a recurring charge the next time the batch runs.


Entering Cash and Paper Check Payments

You can add a Transactions to Chargent manually by clicking the "New Transaction" button on the Transactions related list. By entering the fields described here, these manual transactions will count in the summary fields such as "Total Transactions" and related calculations such as "Balance Due". On the "New Transaction" page enter the following required values:

Field Name Value
Gateway Date Payment date and time
Gateway ID Enter "Check #" or "Cash"
Type Charge
Response Status Approved
Amount Amount of cash or check
Payment Method Cash or Check



Email Receipts and Notifications

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.

Key Chargent fields for Receipts

  • Billing Email -- the email address the payment gateway will send an email to
  • Order Information -- usually appears in the "Description" field of the gateway receipts. Will typically be limited to 255 or fewer characters.
  • Invoice Number -- sends an order or invoice number to the gateway. This appears on many email receipts, but is also required for obtaining the Qualified Rate (lowest transaction rate) on your transactions.
  • Charge Amount -- this is the amount field that Chargent sends to the payment gateway.

 

Preventing Gateway Receipts

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.


 

Sending Email Receipts from Salesforce

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:

  1. Go to Setup > Create > Workflow & Approvals > Workflow Rules
  2. Find the workflow rule called Customer Receipt
  3. Check that it is Active (if not, click the Activate button)
  4. Configure the From and optional CC Email addresses
  5. Go to Your Name > My Settings > Email > Email Templates
  6. Go to the Chargent Templates folder
  7. Click on the Customer Receipt template
  8. Edit the template to meet your needs (you can also clone or create a new template, and update the workflow rule to use your new template)

 

Receipt Considerations

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:

  • Transaction: Response Status = Approved
  • Transaction: Type = Charge

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:

  • Transaction: Payment Method = Credit Card

 

Custom Notification Emails

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.


 

Card Declined Notification

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.

  • Transaction: Response Status = Declined
  • Transaction: Recurring = True

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.


Chargent Declined Transaction Email Alert


 

Renewal Notification

For annual subscriptions, sending a renewal reminder 30 days before hand is a best practice (as well as being a legal requirement in some areas). 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 Annual Renewal Email Alert


 

Currency

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.


Default Currency

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 is not set (or wasn't passed via API call).

Chargent Default Currency Settings


Gateway Currency Settings

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 Currency picklist field (max 100 values).

Chargent Gateway Currency Settings


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.


Chargent Gateway Currency Settings


Currency Field

If Gateway Available Currencies field is not empty, the Currency field on the Chargent Order 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.


How Currencies Work

The Currency picklist on the Chargent Order object contains selected values from the Available Currencies picklist on the gateway that is currently populated in the Gateway on the Chargent Order. 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.


API Notes for Currencies

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.

  1. Australian Dollar
  2. Belgian Franc
  3. Canadian Dollar
  4. Swiss Franc
  5. German Mark
  6. Euro
  7. French Franc
  8. Luxembourg Franc
  9. New Zealand Dollar
  10. Pound Sterling
  11. Russian Ruble
  12. Singapore Dollar
  13. Thai Baht
  14. U.S. Dollar
  15. Plus 139 more. . .
  16. Plus any custom value you wish to pass to your gateway

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.



States, Provinces and Countries


States and Provinces

There are two fields in the Chargent Order object for states.

Billing State: A picklist field you can add values to or customize for your own Salesforce Org.

Billing State / Province: An optional text field where any value can be entered.

Note that any text value entered in Billing State / Province will override the Billing State picklist field and will be what is sent to your Payment Gateway.

When standardizing the picklist values or what is entered in the text field, it is important to run some tests with your Payment Gateway’s address verification settings (AVS). Some payment gateways may want the full name, or require a 2 digit abbreviation, or allow both.


Countries


The Billing Country field on the Chargent Order is a picklist that allows you to choose the country for the billing address. Chargent will attempt to match the value entered with the country abbreviation or ISO code which most Payment Gateways require.

New in Chargent 5.45 is the ability to map values to standardized country names / codes. Previously Chargent matched country names to codes, which could cause errors if country names or abbreviations were not standardized in a Salesforce org.


Country Mapping

Chargent has all country names from ISO 3166-1 standard in its internal mapping. Often users want to use non-standard names for countries, for example “USA” instead of the full name (United States of America) or 2 digit standard (US).

In that case, your Salesforce administrator can add these country names to a custom setting called ‘Country Mapping’. This will ensure that the expected, standardized country values are sent to your Payment Gateway for address validation.

This custom setting is pre-populated by many popular values by default (USA, America, Can, England, etc.)

To add mapping values for a country:

  1. Navigate to Develop -> Custom Settings and press “Manage” link next to Country Mapping.
  2. Press “New” button and enter Country name to the “Name” field and corresponding ISO codes to “Country Alpha-2 ISO code” and “Country Numeric ISO Code” fields.

See Country Codes here: https://en.wikipedia.org/wiki/ISO_3166-1

Chargent will check the custom settings for country mapping first, if no country is found in custom settings Chargent will check its internal mapper. If no value is found in the internal mapper, the original value in the Country field will be passed to the gateway without mapping.

Internal country map can be represented by the following table:

Country Name Alpha-2 Aplha-3 Numeric
united states of america US USA 840

The internal mapper searches by label, alpha-2, alpha-3 and Numeric values. So, if user entered ‘US’ or ‘USA’ or ‘840’ instead of ‘United States of America’ - the mapper will correctly find the necessary value and send it to the payment gateway.

To catch other non-standard values and correctly map them (if validation is not being enforced elsewhere in Salesforce), simply add them to the mapping values. For example:

Country Name Alpha-2 Alpha-3 Numeric
Merica US USA 840

Country Mapping

Recurring Billing



Recurring Billing Overview

Chargent provides a very flexible, customizable system for managing subscription billing, installment payments, and recurring charges. There are two basic parts to setting up recurring payments:


  1. Schedule the Recurring Batch in Salesforce (Scheduled Apex)

  2. Set the fields in your Chargent Order record to include it in the batch

  3. When included in the batch, whether or not a record is charged is determined by the following:

    • Payment Status
    • Payment Start Date
    • When the last transaction marked as recurring was

More details on all of these aspects of Chargent's recurring billing functionality are below.

Scheduling the Apex Batch

Chargent customers have the ability to create scheduled, recurring transactions using a Chargent Order record. 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.

Chargent Scheduled apex

The next page will allow you to configure the parameters of your scheduled process. Please pay attention to the following choices:

  • Enter a Job Name as shown in the image below ("Chargent Recurring")

  • Click the magnifying glass and select the "sheduledBatchProcessing" class to be run. Note: the class name contains a typo - there is no "c" in the word "scheduled". While that was not intentional, we can't change it!

  • You should choose the "Weekly" frequency and check each week day and weekend day. We recommend that the Batch job run 7 days/week.

  • You must choose a Start and End date. Note: Salesforce sets the end date quite close to the start date. Please set the end date to 2040, 2050 or beyond to avoid your recurring billing mysteriously stopping!

  • You may choose any Start Time that you would like. We like 3 am to give your team the whole business day to review transactions and make any required adjustments / voids, but your can also run during business hours so that users may be alerted immediately to issues or declined charges. Note: These Apex jobs run as resources are available, and may not execute exactly on the hour.

Chargent Recurring Batch Schedule


Recurring Fields

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 uses only the "Charge Amount" field. Unless you have the "Manual Charge" checkbox set and a related Charge Amount, the field will equal the "Total" on the Chargent Order. This means that it is possible to charge the customer the full amount multiple times unless you stop on "Balance Due" (explained below).

Payment Frequency

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.

  • --None-- (default) - will not be processed by Chargent Recurring, manual only
  • Once - a single transaction will occur on the Payment Start Date
  • Daily - one transaction per day that the schedule process is executed
  • Weekly - one transaction per calendar week on the same weekday
  • Biweekly - one transaction every two weeks on the same weekday
  • Monthly - one transaction per calendar month on the same day as the Payment Start Date
  • Bimonthly - one transaction every two months on the same day of the month
  • Quarterly - one transaction per every three months on the same day of the month
  • Semiannual - one transaction per every six months on the same day of the month
  • Annual - one transaction per every year on the same day
  • Biennial - one transaction per every two years on the same day

Chargent Payment Frequency Screenshot


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.

Payment Stop

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.

  • Date - Chargent will process the last transaction on or before the Payment End Date depending on frequency.

  • Count - Chargent will stop processing transactions when the number of approved recurring transactions equals the value in the Payment Count field. This is helpful to follow an agreed payment schedule based on number of payments instead of date. Note: this only tracks against the total number of "Approved" recurring transactions and does not include manual transactions by hitting the Charge button. If you would like to monitor this field, you can display or report on "Transaction Count Recurring".

  • Balance Due - Chargent will continue to process transactions until Balance Due is less or equal to zero. If the payment schedule (Amount times number of payments) exceeds the target "Amount" or at any point the "Charge Amount" exceeds the Balance Due, you may end up charging more than was intended, resulting in a negative Balance Due. It is suggested to only use Balance Due for evenly calculated amounts, such as "5 payments of $30" to avoid this scenario.

  • Unending - Chargent will process transactions with no stop event for as long as the Scheduled Apex is automaticaly executed.

Payment Status

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

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


Charge Date

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.

Next Transaction Date

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

Process builder and Validation Rules

Please be very cautious if you use the Process Builder, Validation Rules or Required fields on your Chargent Orders with recurring billing. Validation rules can prevent the Chargent Order 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.

Recurring Versus Manual Transactions

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.


What Determines Recurring Charges?

Records have a transaction processed if they meet the following criteria:

  1. Payment Status=Recurring
  2. Payment Start Date=Today or in the past
  3. The last Transaction record marked as Recurring occurred longer ago than the Payment Frequency

The status field is key in the recurring billing configuration. A Chargent 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).

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.

Installment Payments

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 Total of the Chargent 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 Chargent 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:

  1. Create a workflow rule that fires when the Payment Status is Recurring and the Stop is Balance Due
  2. Have it check the Charge Amount.
  3. If the Charge Amount is > Balance Due, set the Charge Amount to the Balance Due
  4. 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.


    Customizing Chargent




    Developer Tools

    Developer Documentation & API

    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.

    Payment Request

    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.

    Account Updater

    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.

    Payment Console

    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.


    Integrations

    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.

    Accounting Seed

    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.

    FinancialForce

    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 Billing Central, FFA, SCM, and ClickLink, please see our FinancialForce page.


    FormAssembly

    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.

    Salesforce Customer Communities

    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

    Other Considerations


    Security & PCI Compliance

    For best practices related to security and PCI Compliance inside Salesforce, please see our Security Implementation Guide.

    Data Migration

    It is possible to migrate from other payment systems to Chargent. Assuming you can export the data from the old system, if you have experience with data migration you should be able to load the data 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.

    We recommend extensive testing, and only migrating small batches (~10 records to start) to ensure Chargent is configured properly before expanding the migration scope.

    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:

    • Gateway Date=Date and Time of transaction
    • Response Status=Approved
    • Type=Charge
    • Amount=the amount
    • Recurring=True (if applicable)

    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.


    Custom Buttons

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

    1. Chargent Order (lookup from Transaction, both Name and ID)
    2. Transaction Type (Charge)
    3. Response Message (Approved)
    4. Payment Method "Check (Paper)"
    5. Response (Approved)
    6. Transaction ID (Check-Date)
    7. Gateway Date (Current datetime)
    8. Response Status (Approved)

    Label

    Add Check

    Object Name

    Transaction

    Name

    Add_Check

    Link Encoding

    Unicode (UTF-8)

    Namespace Prefix

    ChargentSFA

    Display Type

    List Button

    Behavior

    Display in existing window without sidebar or header

    Button or Link URL

    /a01/e?CF00N80000002wnrb={!Opportunity.Name}&CF00N80000002wnrb_lkid={!Opportunity.Id}&retURL=/{!Opportunity.Id}&saveURL=/{!Opportunity.Id}&00N80000002wnsm=Charge&00N80000002wnsj=Approved&00N80000002wnsf=Check+(Paper)&00N80000002wnsl=Approved&00N80000002wnse=Check-{!Today}&00N80000002wnsd={!NOW()}&00N80000002wnsk=Approved


     

    Track Field History


    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.


    Opportunity History Releated List


    Enabling History Tracking

    1. Go to the Fields Setup: Setup > Create > Objects > Chargent Order

    2. Click the Set History Tracking button in the center above the fields
      • Note that if you have not previously enabled history tracking, the button may say Enable History Tracking, and you will need to check a box to enable it on the following screen

    3. Select the fields you wish to track
    4. Save
    5. Repeat steps 2-4 for the Transaction object
      • Setup > Create > Objects > Transaction

    Set History Tracking Button


    Recommended Fields to Track

    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

    1. Amount (or Subtotal for Chargent Orders)
    2. Charge Amount
    3. Manual Charge
    4. Billing First
    5. Billing Last
    6. Billing Address
    7. Billing Email
    8. Card Name
    9. Card Number
    10. Card Expiration Month
    11. Card Expiration Year
    12. Charge Date
    13. Payment Frequency
    14. Payment Method
    15. Payment Status
    16. Payment Start Date
    17. Payment Stop

    Transaction

    1. Amount
    2. Recurring
    3. Type
    4. Response Status

    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.


    Opportunity Field History Tracking