- Transaction Records
- Creating and Updating Transaction Records
- Additional Notes on Transactions
- Verifying a Card
- Capturing Authorization Holds
- Partial Authorization Capture
- Declined Charges
- Refunds & Voids
- Entering Cash and Paper Check Payments Manually
- Unresolved Transactions
- Unlinked Credits and Unreferenced Credits
- States, Provinces and Countries
- Address Verification System (AVS)
- AVS Response Options
- AVS Configuration
- Card Verification Number (Security Code)
- Card Number Formats
Chargent allows for several types of transactions. Here is how we define each transaction type within Salesforce. Each of these types of transactions are achieved through various processes using Chargent Anywhere.
- Authorize – Authorization Only, used for placing a hold on an amount or checking if a credit card is valid for future capture. Authorization can be initiated using either Payment Request or Payment Console.
- Charge – The [Charge] button is found in the Payment Console. It will perform an Authorization first and then immediately capture the amount. If you performed an Authorization previously, it will capture the amount authorized. For Payment Requests the Charge happens when the person clicks the [Pay] button.
- Refund – Refunds are initiated from the Transaction record. It will refund a transaction that has been previously settled (between 1-120 days typically), also called a Credit on some payment gateways. Please consult your payment gateway for the exact time frame in which a refund can be initiated.
- Void – Cancels a transaction that has not yet been settled (most commonly a Charge from that same day) or an Authorization that has not yet expired. You can also use the [Void] button to cancel a refund if a refund was accidentally processed and has not yet settled.
- 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.
Transaction Records #
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.
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 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.
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.
Additional Notes on Transactions #
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 with the exception of an invalid card number length.
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.
A credit card authorization holds a portion of the available balance on a card for you to capture in the future, without actually pulling the funds at the time of authorization. Authorizations for most credit cards expire after 7 days, however, this will vary depending on the gateway. Some gateways will be shorter, however some may be longer which could remain on a customers account up to 30 days. The authorization will continue to hold the amount from the credit cards available balance and could prevent the customer from making additional purchases until the authorization expires.
You should only authorize a credit card for more than the minimum $1, if you are intending to capture the funds within a few days. It’s recommended you capture funds within 3 days or void the authorization to process at a later date. This is because you are reducing the amount of credit available to your customer. In some cases your authorization could cause other transactions to be declined, or in the case of debit cards, could cause overdrafts for your customer, so use them carefully.
Visa, MasterCard, and American Express also have rules regarding acceptable authorization amounts for different types of transactions, so consult your merchant agreement for additional details.
A customer’s credit card will only be charged when an authorization is captured.
Verifying a Card #
The validity of a new credit card can be checked by performing an authorization of a $0 or $1 amount. Note that this does not verify that the card holds sufficient funds to accept a future charge or a larger amount, but has the benefit of not placing a hold on your customer’s funds and reducing their available credit.
- $0 authorization for Visa / MasterCard / Discover
- $1 authorization for American Express
For the $1 American Express authorizations, you can Void them by using the Void button on the Transaction record, or simply wait for the authorization to expire. The Transaction record will show a Type as ‘Register Token’
Capturing Authorization Holds #
To capture an outstanding Authorization in Salesforce, Click the [Payment Console] button. You will see a pop-up showing an existing Authorization. Click the Capture Button.
To release the funds back to your customer more quickly, such as in a situation where an order is canceled and you are not going to capture the funds, go to the Chargent Transaction record in Salesforce and click the [Void] button.
Note that Authorizations on debit cards typically expire in 1-8 business days, while Authorizations on credit cards can take up to 30 days to expire or “fall off”, depending on the issuing bank of the credit card.
In addition, not all banks allow you as the merchant to void authorizations, so in some cases you could void an authorization but the hold would remain on your customer’s account.
Partial Authorization Capture #
On occasion you may need to authorize an amount that is more than the final total. In this situation you will need to capture an amount less than the authorization.
One example of this is restaurants, which typically authorize the amount of the bill plus 20%. Once the total amount of any tip is known, they will capture only that amount of the authorization.
For ecommerce businesses, the best practice is to use 3rd party tools to automatically calculate shipping costs and taxes (if any), and then to authorize for the correct full amount. When the goods are later shipped, you then capture the prior authorization.
To capture an amount less than what was authorized in Salesforce using Chargent:
- Go to the Transaction record of the Authorization in Salesforce
- Edit the Amount of the Transaction to be the amount you wish to capture
- Click Save
- Click the Charge Authorized button
The first time you perform a partial capture of an authorization in Salesforce, we recommend verifying that the correct amount was captured by logging into your payment gateway reporting interface.
To capture an amount more than your prior authorization, please contact your payment processor to see if it is possible and
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:
- 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: 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.
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 App Launcher and select the Chargent App
- Click the 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|
Unresolved Transactions #
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
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
Authorizations are submitted in real-time when you click the Authorize or Charge button in Salesforce, but the capturing of funds does not happen just then. Typically charges are submitted in a batch once per day in what is known as Settlement.
Settlement batches can have any number of transactions greater than 0. There is no minimum for a batch, though there is typically a cut-off time daily when the batch is created. Once Settlement happens a transaction can no longer be voided, and the process of getting money into your bank account has started. When the daily batch settlement occurs varies widely amongst the payment gateways, and often it is configurable.
Settlement batches can sometimes be initiated manually, but most payment gateways automatically settle transactions at a particular time. The following are some examples for some of the more popular gateways. For times specific to your transactions, you should contact your gateway.
- Authorize.net: Settlement happens at the “Transaction Cut Off Time”, which can be configured in the Authorize.net interface
- Chase: The auto settle time is chosen during the Chase Orbital application process. To change it, contact the production helpdesk.
- Cybersource: Can vary, though typically Midnight Pacific time. Settlement batch time can be changed by contacting support.
Stripe: Midnight UTC (4pm PST / 5pm PDT)
Unlinked Credits and 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
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.
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 set up 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.
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 the 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.
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).
- Once you’ve updated the currencies click the [Save] button
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.
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.
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.
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:
Address Verification System (AVS) #
The Address Verification System (AVS) is a system used to prevent fraud and validate the ownership of a credit card, by checking the billing address of a credit card with the data on file at the credit card issuing company.
A wide variety of options are available in terms of how you use AVS, and how you would like transactions to be declined or approved based on matches of the AVS data.
The Address Verification System checks the numeric portions of the Billing Address. As an example, if you enter 1234 Main Street, Anytown, CA 94107 as the Billing address in Chargent the AVS will check 1234 (the street number) and 94107 (the zip code).
AVS is supported by Visa, Mastercard, and American Express through most card-issuing banks in the US, Canada, and the UK. Credit cards issued by banks in other countries may not support AVS and should return a response that it is not supported.
AVS Response Options #
The card networks do not decline transactions based on a mismatch with the street address number or zip code, they return an AVS response, and you can configure filters in your payment gateway to decline or approve the transaction.
If you are in a business which does not experience credit card fraud generally, you may choose to approve transactions despite mismatches in some or all of the AVS data. For example, some B2B transactions have a low rate of fraud but a higher than normal rate of AVS mismatches, as the person using the card could be unaware of the correct billing address on a company card.
Note: Regardless of the AVS Response flag, the credit card will have been authorized by the issuing bank. This means that your customer may have a temporary authorization hold on their card even if your payment gateway settings cause the transaction to be declined.
You may still be able to capture an authorization that received the AVS decline. You should review those orders carefully, and your bank may charge a higher fee on transactions that did not pass AVS checks. Many banks and processors use AVS as a way of avoiding non-qualified transaction surcharges. That can add about 1% to transactions, but may be worthwhile to your business if you have low fraud and a customer who you want to take a payment from without passing AVS checks.
AVS Configuration #
When configuring your payment gateway filters, there are a number of response codes that AVS returns, and you can choose which ones to reject (decline) and which ones to accept (approve).
Log into the web interface of your payment gateway to configure which codes you want to enforce as filters, rejecting transactions that come back with those AVS codes. Here is a sampling of common codes:
- R = AVS was unavailable at the time the transaction was processed. Retry transaction
- G = The credit card issuing bank is of non-U.S. origin and does not support AVS
- N = Neither the street address nor the 5-digit ZIP code matches the address and ZIP code on file for the card
- A = The street address matches, but the 5-digit ZIP code does not
- Z = The first 5 digits of the ZIP code matches, but the street address does not match
- W = The 9-digit ZIP code matches, but the street address does not match
- Y = The street address and the first 5 digits of the ZIP code match
Require AVS Salesforce Field
The Chargent field Require AVS on the Gateway record in Salesforce is used to generate an error if it is checked and the Billing Address and Billing Zip/Postal Code fields are blank.
It is a best practice to always populate the Billing Address, City, State and Billing Zip Code/Postcode as they are often required by the payment gateway. Some gateways such as Cybersource also require Country and Billing Email to be sent.
Card Verification Number (Security Code) #
The CVN (Card Verification Number), also referred to as CVV2 (Card Verification Value 2), CVC2 (Card Validation Code 2), CVC (Card Verification Code) or CID (Card Identification Number) is a 3 digit code that appears on the back of credit cards, beside the signature area. For American Express cards, it is a 4 digit code on the front of the card.
Card verification numbers, in conjunction with AVS verification, are used to reduce credit card fraud in ‘card-not-present’ transactions (ecommerce or phone, where the physical card is not being swiped). Card verification codes are required for processing cards in Salesforce in order to reduce the scope of your PCI compliance.
There are a number of response codes, but some common ones are:
- M = Matched.
- N = Not matched.
- P = not processed by processor for unspecified reason.
Note that CVV2 / CVC2 values are never stored in your Salesforce account for PCI Compliance reasons, so typically they should only be used the first time a card is authorized or charged. Chargent recommends tokenization if you are going to be processing recurring or subscription billing. This will allow you to send the first charge to get a token which can be used for future payments.
Card Number Formats #
first few digits tell you whether it is a Visa, Mastercard, American Express, or Discover Card. The first 6 digits identify the bank that issued the card, and the last digit is a check-digit, used to detect errors. The remaining digits (usually 9) are the cardholder’s account number.
|Card Type||Card Number Prefix/Range||Number Length||Card Validation Number Length|
|American Express||34 and 37||15 digits||4 digits|
|MasterCard||51-55||16 digits or 19 digits||3 digits|
|Visa||4||16 digits or 19 digits||3 digits|
|14 digits or 16 digits||3 digits|