AppFrontier

☰ Menu

Developer Documentation Chargent API


Chargent Developer Documentation


For web integrations, you can use the Chargent web services API. These web services are 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.

You can also call Chargent methods directly from inside Salesforce, without a user initiating them in the normal manner, such as from a customized Visualforce interface.

New June 2014: Payment Request
Chargent's new 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.

Please Note: the Chargent web services API requires a Chargent Platform edition license. Please contact us for details.

TChargentOperations Overview

There is a Web Service which you can find under Develop -> Apex Classes called "TChargentOperations". You can see a description on this page of the request and response. For example on the Apex page you will see:

 
webService static ChargentSFA.TChargentOperations.TChargentResult AuthorizeOpportunity_Click(Id OpportunityId)

webService static ChargentSFA.TChargentOperations.TChargentResult ChargeAuthorizedTransaction_Click(Id TransactionId)

webService static ChargentSFA.TChargentOperations.TChargentResult ChargeOpportunity_Click(Id OpportunityId)

The Global Class TChargentOperations (Class that creates the transaction) uses the with sharing keyword. The Global Class Webservice does not act on any records and does not use the with sharing keyword.

Chargent has a base package, and then you choose either Opportunities, Cases or Chargent Orders (custom object) for your Transaction object. The examples above are for the Opportunties Transaction object. If you are using Cases or Chargent Orders, simply change the syntax accordingly:

ChargentOrders.TChargentOperations.TChargentResult ChargeOrder_Click(Id CaseId)

or

ChargentCases.TChargentOperationsTChargentResult ChargeCase_Click(Id CaseId)

Using TChargentOperations

To integrate payment processing in your custom Visualforce pages you can utilize the methods in the Global Apex Class TChargentOperations.

This class provides apex the same functionality as clicking one ("Authorize","Charge","Void", or "Refund") buttons on the opportunity itself.

Required Parameters

In order to authorize or charge an Opportunity, all fields that would be required to be filled out when clicking the button must be completed when calling these methods.

Required fields:

  1. Charge Amount
  2. Payment Method
  3. Card Number (or Token)
  4. Card Expiration Month
  5. Card Expiration Year
  6. Billing Name, Billing Address, Billing Zipcode (depends somewhat on your AVS settings on the gateway side)

Other fields are optional, but are likely to be a part of most billing processes.

Optional fields:

  1. Invoice Number
  2. Billing Email (for receipts)
  3. Manual Charge (to optionally prevent balance due from recalculating charge amount)

Processing an Opportunity

Instantiate the result object so that you can parse the response from the server

ChargentSFA.TChargentOperations.TChargentResult ChargentResult;

The Result Object is defined in the apex class. You will most likely be parsing the Message and the Status to obtain the information needed for your page. Both of these are String objects.

Choose an Action

Authorize Opportunity

  1. Obtain the ID of the Opportunity that you wish to authorize
  2. Call the static method to process the authorization storing the result in the ChargentResult created above:
  3. ChargentResult = ChargentSFA.TChargentOperations.AuthorizeOpportunity_Click(OPPURTUNITYID);
  4. You can parse the message string by splitting it via \r\n
  5. List<String> tmp = result.Message.split('\r\n');
  6. The transaction ID can be obtained from the Message string and can be stored to later charge if required

Charge Authorized Transaction

  1. Obtain the ID of the transaction record related to the opportunity either by performing an SQL query for the record ID of the transaction ID obtained above or a simple query to return any authorized status transaction for the opportunity
  2. Call the static method to charge the authorized transaction and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.ChargeAuthorizedTransaction_Click(TRANSACTIONID **SF Record ID**);
  4. Parse the results

Charge Opportunity

  1. Obtain the SF ID of the Opportunity
  2. Call the static method to charge the Opportunity and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.ChargeOpportunity_Click(OPPORTUNITYID );
  4. Parse the results

Refund Opportunity

  1. Obtain the Opportunity ID
  2. Call the static method to Refund the opportunity and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.RefundOpportunity_Click(OPPORTUNITYID);
  4. Parse the results

Refund Transaction

  1. Find the SFID of the transaction you wish to refund
  2. Call the static method to refund the transaction and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.RefundTransaction_Click(TRANSACTIONID **SF Record ID**);
  4. Parse the results

Void Opportunity

  1. Obtain the Opportunity ID
  2. Call the static method to Void the opportunity and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.VoidOpportunity_Click(OPPORTUNITYID);
  4. Parse the results

Void Transaction

  1. Find the SFID of the transaction you wish to void
  2. Call the static method to void the transaction and obtain the results
  3. ChargentResult = ChargentSFA.TChargentOperations.VoidTransaction_Click(TRANSACTIONID **SF Record ID**);
  4. Parse the results


Considerations for Using Chargent Orders

For the "Chargent Orders" custom object you will need to make sure you include the following fields:

  1. "Subtotal" or "Charge Amount". Setting "Manual Charge" = true will prevent our workflow rule from changing Charge Amount to "Balance Due" which is Total minus Total Transactions. For a non-ecommerce model, we suggest hiding Subtotal, Tax, Shipping, Total and Balance Due fields, and using only the "Charge Amount". Also disable the packaged workflow rule called "Update Charge Amount" so it never gets overwritten.
  2. Depending on your gateway configuration, you will need full card data including security code, plus full billing address data (assuming your gateway requires CVV and AVS). Those fields should be obvious from the WSDL or object definition.
  3. If you wish to set a recurring payment schedule, you should look at the docs for those field settings.
  4. Once the record is saved you would essentially invoke the following method remotely using the record ID of the previously saved order:
  5. webService static ChargentOrders.TChargentOperations.TChargentResult ChargeOrder_Click(Id OrderId)
    

Sample Code

Parsing the Message String

List<String> tmp = result.Message.split('\r\n');
                
   if(tmp.size() == 3){
     transactionStatus = tmp[1].substring(tmp[1].indexOf('"') + 1,tmp[1].length() -1);
     transactionMsg = tmp[2].substring(tmp[2].indexOf('"') + 1,tmp[2].length() -1);
     transactionID = tmp[0].mid(tmp[0].indexOf('(')+1,tmp[0].indexOf(')') - tmp[0].indexOf('(')-1);
   }else{
     transactionStatus = 'UNKNOWN';
     transactionMsg = 'UNKNOWN Response';
   }
     isSuccess = transactionStatus != 'Error';
     record_status = transactionStatus;
     error_message = isSuccess == false ? transactionMsg : null;
                
   }

eCommerce Model

Here is the basic model we use for e-commerce. The apex will invoke Chargent by passing it the Opportunity ID (or Order ID if you choose that Transaction package). Here are some examples:

public TChargentOperations.TChargentResult ChargentResult {get; set;}

Boolean Apr = true; 
ChargentResult = TChargentOperations.ChargeOpportunity_Click(OpportunityId);
if (ChargentResult.Message.indexOf('Approved') < 0) {Apr = false;}

This example does not "Authorize" but performs a full charge with ChargeOpportunity_Click. If you only Authorize, then a user must click the Charge button to finish the payment process.

Here is the same example but using the Order instead of the Opportunity Transaction package:

public TChargentOperations.TChargentResult ChargentResult {get; set;}
Boolean Apr = true;
ChargentResult = TChargentOperations.ChargeOrder_Click(OrderId);
if (ChargentResult.Message.indexOf('Approved') < 0) {Apr = false;}

When the page is reloaded you can take different actions based on whether the Payment authorization has succeeded or failed.

 
<apex:outputText rendered="{!Err.PaymentFail == true}">
<p id="error">The payment method you have provided was declined. Please double check your security code, expiration and card number, or provide an alternative method of payment.

</apex:outputText>

There are apex webservices for all the standard methods. In addition to Charge and Authorize, there is Void and Refund. You can see the parameters required through the Apex class page.

Sample Page Downloads

Here is a sample Visualforce page (order2.page) and controller (customers.cls) that demonstrates Chargent's basic method for eCommerce from within Salesforce. The apex will invoke Chargent by passing it the Opportunity ID. In these examples we are using the custom "Order" object instead of "Opportunity".

order2.page

customers.cls

Both Files in a Zip


Scheduling TChargentBatchProcessing Batch Processing

Salesforce enforces several governor limits when executing a batch process. The most significant is the number of callouts allowed during an asynchronous transaction. Prior to Winter 15 (API 32) the limit was 10. As of Winter 15 (API 32) the limit is 100.

To incorporate the scheduling of TChargentBatchProcessing within your own code you can use the following snippet of code to do so. (Use 10 instead of 100 for API < 32)

 
global class ScheduledBatchLauncher implements Schedulable {

  global void execute(SchedulableContext sc) {
      ChargentOrders.TChargentBatchProcessing b = 
      newChargentOrders.TChargentBatchProcessing();
   Database.executeBatch(b,100);

   }
}

Custom Batches

If you are calling a Chargent method in a batch class you have written, setting the Scope of the batch to 1 will allow you to process all the orders in your batch in an automated fashion. Since you cannot do DML before a callout, setting the scope to 1 will reduce the number of callouts to 1 per transaction.

For example:

MyBatchClass b = New MyBatchClass();
database.executeBatch(b,1);

Testing & Error Handling

Testing Callouts

When testing the callouts that Chargent makes, you can't use the HttpCalloutMock class in Salesforce because it has to be done from within the Chargent managed package/namespace. To create sample responses and make sure that your code behaves appropriately, here is a workaround:

Wrap the actually call to Chargent Webservices in a

if(!test.isRunnungTest()){ 

     code that makes call out here

 }else{

   //create a transaction record manually or set what ever values need for your test to continue

}

Uncommitted Work Errors

Purpose

When building a custom visualforce page that will be using Chargent Webservice Methods to process a charge there is a potential that you may receive an error from Salesforce when executing the Chargent Webservice Method as follows:

       You have uncommitted work pending. Please commit or rollback before calling out

Background

One of the framework requirements when developing on the Salesforce platform is that you cannot perform any DML prior to making a callout to any external service in the same transaction. Chargent Webservices, when executed, makes a callout to the appropriate gateway to process the charge, thus you cannot perform any DML prior to executing a method from Chargent Webservices.

Solution

Within the lifecycle of a Visualforce page, each execution of a controller method from the Visualforce page itself is a separate transaction. The key is that individual execution of the method must come from the page and not from the controller.

The following is an example of a minimalistic page and controller. It is intended only to show the typical pattern that causes the issue.

Error Example:

Page
Uncommitted Work Error Example Visualforce page

Controller
Uncommitted Work Error Example Controller

When the command button is clicked it executes the update_and_charge() method. That method then updates the Opportunity record and then attempts to execute the charge() method. When the charge() method executes the ChargentWebservices Opportunity_Click method and attempts to make the callout to the gateway you will receive the error message.

The solution is to break up the calls using the oncomplete tag on the command button in conjunction with an apex:actionFunction to call the charge() method. This solution follows:

Working Example

Page
Working Example Visualforce page

Controller
Working Example Controller

Notice that on the page we added an apex:actionFunction to call the charge() method in the controller on completion of the update_and_charge() method. Also, we removed the call to the charge() method from the controller that was on line 11 in the error example.

In doing this, on click of the command button the update_and_charge() method is executed which updates the Opportunity and then the transaction finishes and returns control to the page. The page then calls the actionFunction via the oncomplete tag and then executes the charge() method in the controller in a separate transaction without producing any errors.