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 familiar with Authorize, Charge, Void and Refund. Here are the general definitions as used in Chargent:
Authorize: This creates an authorization only. Authorizations are a temporary transaction recommended to either void or process the charge within a few days. It’s used for, but not limited to the following situations.
- Making sure a credit card is valid or has the funds before processing a future charge.
- Holding funds prior to shipping merchandise.
- Holding funds until a final amount is calculated.
Charge: When the Charge button is pressed, you will see a popup asking for the CVC (Card Verification Code). Once the CVC is entered and the Charge button pressed. one of the following instances will occur.
- An Authorization is done to obtain a token and then Capture the transaction.
- If an Authorization has been previously submitted it will capture the authorization and charge the credit card. This will change the Transaction Status field from Authorization to Charge.
Void: Voiding will cancel a transaction that has not yet been settled (Charge or Refund from same day typically) or expired (Prior Authorization). You should always perform Voids from the Transaction record.
Refund: The Refund and Partial Refund button will refund a transaction that has been previously settled (between 1-120 days typically). You should always perform Refunds from the Transaction record.
Credit - The Credit button can send funds not tied to a previously captured transaction. Only supported on some payment gateways.
Please refer to the gateway guide for your particular payment gateway for additional information.
Authorizations and how they work
Every time Chargent calls out to your payment gateway to send credit card or ACH transactions, 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 under the Related tab on the Chargent Order.
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.
- Authorization: The authorization code returned by the payment gateway.
- Response, Response Code, Reason Code: These responses can be useful in understanding declines or errors, so check your payment gateway website for more information.
- Gateway Response: The full text of the response from your payment gateway, sometimes useful in troubleshooting a transaction.
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 payment gateway provider.
Here are some helpful links to understanding the decline reasons or support options for your specific gateway. Not all gateways have the response codes / reason codes listed on their website and may advise you to contact the issuing bank for the specific decline reason.
- eProcessing Network
- IATS Payments
- Merchant e-Solutions
- Merchant Warrior
- PayPal Payflow Pro
Creating and Updating Transcation Records
Chargent references existing transactions when running a recurring billing schedule, so be careful not to edit recurring transactions. In general, making changes to any existing transaction records is not recommended.
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 canceled.
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, for some gateways, will update transactions that were originally started in Chargent with the latest status from certain payment gateways. Transaction Sync is available for the following Gateways.
- 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 within a certain time period. Other gateway may allow it but may flag it as a potential duplicate.
Chargent supports tokenization on most of our payment gateway integrations. Tokens are stored in the “Token” field on the Chargent Order, and can be used for future transactions, referencing the payment data stored securely on your payment gateway’s servers.
For an overview of tokenization, please watch this short video:
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:
- Payment Status will automatically change from Recurring to Error.
- Once you have received updated billing information, change the Payment Status back to Recurring.
- 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.
Refunds & Voids
Refunds and Voids should always be initiated from the Transaction Record.
- In Lighting you need to have My Domain enabled within your Salesforce settings to see Lightning Actions. These buttons will need to be added to your Transaction Page Layout. You will find them under “Mobile & Lightning Actions” within the Page Layout when adding them.
Refunds: Refunds can be done once a transaction has settled in your gateways batch (typically nightly). Refunds mean that the credit card statement will show a charge and then a refund as a separate record.
Refunds can be made against settled transactions for up to 120 days typically. Refunds are shown as a separate Transaction record in Salesforce with the Type equal to Refund and a negative amount to balance the total fields.
Voids: Voids will cancel a charge before it has been settled. For example, if you charge a credit card incorrectly, you can void it that same day, and it will not be processed when your daily batch settlement happens.
Voids will change the original transaction Type from Charge, Authorize, or Refund to Void in Salesforce, and does not create a separate transaction record. You can also void Refunds if you refunded a transaction by mistake.
Partial Refunds: With most payment gateways it is possible to do partial refunds using Chargent's Partial Refund button.
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.
It is possible to make multiple Partial Refunds against a single transaction as long as the total of the refunds do not add up to more than the original Transaction amount.
Unlinked Credits & Unreferenced Credits
Unlinked Credits (credit cards): Some payment gateways allow you to enable what is called Unlinked Credits to issue refunds beyond the 120 day window, refund transactions made in another system, or even send payments. Unlinked Credits are available for the following gateways. Unlinked Credits may have a different name depending on your gateway provider.
- Merchant e-Solutions
- Network Merchants (NMI)
Unreferenced Credits (ACH / Direct Debit): Some gateways allow you to do Unreferenced Credits. This is the option to send payments to a person’s checking account using the Routing Number and Bank Account Number when the transaction is not a refund of a previous charge. Unreferenced Credits are available from the following gateways. Unreferenced Credits may have a different name depending on your gateway provider.
- Network Merchants (NMI)
- Fat Zebra
Entering Cash and Paper Check Payments Manually
Chargent Anywhere makes it easy to add Cash and Paper Check Transactions simply by pushing a button and entering in the amount. On occasion however you may need to add a manual transaction for cash, paper check, or other payment methods that are not in Chargent.
You can add a Transactions record to Chargent manually by doing the following.
- Click the AppLauncher and select the Chargent App
- Click on Transactions tab
- Click the [New] button
- Enter the fields listed below and click [Save]
|Gateway Date||Payment Date & Time|
|Gateway ID||Enter either the Check Number or Cash|
|Amount||Amount of Cash or Check|
|Payment Method||Cash or Check|
Level II and Level III
- What are Unresolved Transactions?
- How to access the Unresolved Transaction object
- How the Unresolved Transactions are handled
- Cleaning up Unresolved Transactions
- Other Troubleshooting Tools
What are Unresolved Transactions?
An Unresolved Transaction is when a Transaction record can’t be created or saved due to a Salesforce configuration error. Errors can happen due to Process Builder, Validation Rules, Triggers, custom Apex code or other conflicts. Since Transactions have a master-detail relationship to the Chargent Order, if the Chargent Order cannot be updated or saved, the Transaction cannot be either.
When an error occurs, an Email Notification is sent to the email address listed under the Chargent Admin Email Address you have listed in your Chargent Settings.
Chargent’s Unresolved Transactions feature will save a copy of the transaction for the Chargent Order, that can be reparented using its interface. Once the error has been fixed you will then be able to quickly attach the Transaction to the Chargent Order.
How to access the Unresolved Transactions object
- Click on the AppLauncher in Salesforce
- Search for Unresolved Transactions and select it
You will see all the transactions that could not be written.
If the error is corrected then you can easily check the box to the left of the unresolved transaction and click the Create Transactions button. If you have multiple unresolved transactions then you can select multiple transactions and create all the records at the same time.
If the error is still present you will see the error message when you try to resolve the transaction. You can also click on the “View” link to see the original error.
How the Unresolved Transactions are handled
When attempting to process a transaction, if the transaction can’t be saved for some reason it will be marked as an Unresolved Transaction. It also creates an Email Notification which gets marked as Unresolved via the checkbox field
NOTE: If an unresolved transaction exists, additional transactions will not be processed on that Chargent Order until the transaction is attached to it.
Cleaning up Unresolved Transactions
If the error was with saving the Chargent Order (Validation Rule, Flow, or Process) and a transaction is present, review the gateway and payments made against the Order. If the Chargent Order should be picked up in the next batch then edit the Email Notification to uncheck the “Unresolved transaction”. You cannot use the Unresolved Transaction tab to process these as the error was not in a transaction. You should be able to process this again.
If the error was saving the Transaction record, use the Unresolved Transactions tab to process them. You should have the Email Notification that explains why the Transaction Record couldn’t be saved. Once you fix the error, and the record is able to be attached to the existing Chargent Order, you can process the Unresolved Transaction as listed above.
Other Troubleshooting Tools:
You can test the insertion of a Transaction record and the Master record from the Chargent Settings tab.
- Click on the App Launcher in the top left side of Salesforce
- Click on Chargent App
- Click on Chargent Settings
- Click on Troubleshooting Tools
- Press the button to insert a transaction
The testing of the insertion is based on your setup in your Salesforce Org and will tell you if there are any Flows, Processes, or Validation Rules preventing it from saving a record.
Chargent can support transactions in more than 150+ different currencies.
Please note your payment gateway and processor will determine:
- What currencies you can accept
- The currency your transactions are sent in (or converted to a different currency)
- The currency your payments are settled in
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.
The default currency is what gets sent to your Payment Gateway based on two different settings. The field you select from the Payment Console or Payment Request when processing a payment using Chargent Anywhere. The other default setting is in your Chargent Settings under your Advanced Settings tab.
When you set up your payment gateway you will be prompted in the wizard to choose the currencies you will accept. These currencies are stored in the Gateway record and will be available with the Chargent Payment Console and Chargent Payment Requests (v 5.85 or newer).
Note: If you are using multiple currencies, and on an older version of Chargent we recommend updating your current package to the most current version from our installation page.
For the Payment Console, the main default currency will be the one you designate when processing a payment. You can select the currency from the picklist. These will be the same currencies you setup in your Gateway record. This field is defaulted to ‘United States dollar’ but the default can also be changed based on the default currency setup in your Chargent Settings Advanced Settings.
Note: If you don’t see a currency listed, you should check the Gateway setup to make sure it’s listed as an Available Currency. If the currency isn’t listed, you want to update the currency accepted.
For Payment Requests, you will need to indicate the currency prior to sending the request. There will be a drop down to indicate the currency field. Like Payment Console, this field can also be changed to auto-populate with a different currency based on your Chargent Settings Advanced Settings.
The Chargent Settings Advanced Settings provides you with a Default Currency field. This is the field that automatically populates the default Currency field on your Payment Request and Payment Console currency. This also acts as a default when no currency is selected.
The currency sent to the gateway will be reflected on the Chargent Order under a Visualforce field called Currency. The Visualforce field will need to be added to the Chargent Order Page Layout in order to be visible.
Versions Prior to 5.85 with Chargent Orders
If you are on a version prior to 5.85, the default currency when using the Payment Console or sending a Payment Request will be in the Chargent Settings Advanced Settings tab. If you need to choose a different currency when processing a payment, you can always process a charge directly from a Chargent Order.
Chargent Orders have a Visualforce field for currency that can be added to the Page Layout. When you add the Visualforce field it works with the currencies selected during the Chargent Setup Wizard and will allow you to select the correct currency from the picklist.
When adding the Visualforce field to the Page Layout you want to make sure you update the size so that the height is 25.
To set the default currency in your Chargent Settings
- Click the App Launcher in Salesforce and select Chargent app
- Click Chargent Settings tab.
- Select the Advanced Settings sub-tab.
- Under Gateway Settings you can select from the dropdown menu your default currency
Gateway Currency Settings
To update the default currency in the gateway settings:
- Click the App Launcher.
- Search the Quick Find and select Gateways.
- Select the gateway you want to edit and click the [Edit] button.
- Once you’ve updated the currencies click the [Save] button
If you don’t see the section for Available Currencies you may need to add that to the Gateway Page Layout.
Currency picklist field (max 100 values).
Chargent strives to provide as many currencies as possible but in the event you find your currency is not listed, you can add it to the list. Currencies are part of your Gateway record under a Picklist called Available Currencies.
To add currencies to the picklist you want to do the following:
- Click the gear icon on the top right and choose Setup
- Navigate to Objects & Fields, and select Object Manager
- Locate the Gateways object and choose Fields and Relationships
- Click on Available Currencies
- Scroll down to the list of values and you can click New to add a currency.
Don’t forget to update your Payment Gateway record in Salesforce to accept this currency.
When you add your currency you also want to make sure that the country is also listed in the Country Mapping tool.
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).
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.
- Australian Dollar
- Belgian Franc
- Canadian Dollar
- Swiss Franc
- German Mark
- French Franc
- Luxembourg Franc
- New Zealand Dollar
- Pound Sterling
- Russian Ruble
- Singapore Dollar
- Thai Baht
- U.S. Dollar
- Plus 139 more. . .
- 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.
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.
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
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.
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.
You can use the Country Mapping tool to add the Country Code to the list.
- Click the gear icon and choose Setup
- Under Custom Code select Custom Settings
- Next to Country Mapping click on Manage
- Click New and name it.
- add your ISO country codes and save.
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:
|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: