--- name: chargent-salesforce description: Build a production-grade Chargent to Salesforce integration covering architecture, the step-by-step build with Apex code, field mapping, API and governor limits, security, monitoring, and the pitfalls to design out. Use when connecting, building, or debugging a Chargent and Salesforce integration. --- # Chargent to Salesforce integration > Cloudsheer's delivery playbook for Chargent on Salesforce, distilled from 1 client projects and 35 delivery tasks. Apply it as the reference approach when building this integration. ## Overview A full Chargent managed-package rollout for collecting card payments inside Salesforce. We have shipped it across 2 client projects and 35 build tasks. The value is what happens after the charge: matching payments to records, handling refunds, and keeping finance reconciled without manual work. We deploy the managed package the right way: sandbox first, licenses and permission sets assigned, templates and layouts configured, and automation wrapped around it so it fits your process. Every Chargent build is delivered by a senior Salesforce architect on a fixed price, tested end to end in a sandbox, deployed to your org, and backed by 30 days of hypercare. You own the result: documented, source-controlled, and free of black-box middleware lock-in. ## Integration facts **Connects via:** - Managed package suite (AppExchange): Chargent Base/Gateway + Chargent Orders + optional Chargent Anywhere - Native Apex HTTPS callouts to 30+ pre-built payment gateways - Chargent Anywhere runs payment processing on any standard or custom object **Package:** Chargent Payment Processing (AppFrontier) **Authentication:** Per-gateway credentials (e.g. API Login ID + Transaction Key) stored on the Chargent Gateway record; outbound HTTPS callouts to the selected gateway **API type:** REST **Key endpoints:** - `ChargentOrders__ChargentOrder__c (order/payment record)` - `ChargentOrders__Transaction__c (transaction log)` - `ChargentOrders__Gateway__c (gateway config)` - `ChargentOrders__Payment_Request__c (text-to-pay / payment link)` **Official docs:** https://developers.appfrontier.com/ ## Prerequisites - A Salesforce edition with API access (Enterprise, Unlimited, or Developer) - The managed package, installed in a sandbox first - A dedicated sandbox to build and test in - Chargent test-mode credentials to validate before going live - A Chargent account on a plan with API access - System Administrator access on both systems - A dedicated integration user with a minimum-access permission set - Agreement on the objects, fields, and sync direction for the Chargent data ## Architecture Data flows left to right through four lanes: 1. **Sources:** Chargent checkout, Chargent events, Managed package, OAuth 2. **Integration layer:** Webhook / API handler, Payment flows, Reconciliation jobs 3. **Salesforce:** Payment, Related records, Reports 4. **Outcomes:** Payments reconciled, Records created, No manual entry ## How it works at runtime 1. **Customer pays** `[In Chargent]`: A customer or donor pays through Chargent using checkout, a payment link, or a saved card. - Note: `Handled entirely vendor-side, so raw card data never touches Salesforce and PCI scope stays low.` 2. **Event is emitted** `[In transit]`: Chargent emits an event such as checkout.session.completed or charge.succeeded. - Note: `POSTed over Managed package, OAuth to a public Apex REST endpoint exposed on a Salesforce Site.` 3. **Verified and queued** `[In Salesforce]`: The endpoint verifies the signature, returns HTTP 200 immediately, and hands the work off. - Note: `HMAC signature checked; heavy processing runs in a Queueable so the webhook never hits its timeout.` 4. **Record is written** `[In Salesforce]`: The event is upserted to an Events object, then mapped onto the Payment and Account. - Note: `Idempotent upsert on the event id; a record-triggered flow maps fields and reconciles.` 5. **Reconciled and reported** `[In Salesforce]`: The payment is matched to the right record; refunds and disputes flow back automatically. - Note: `Amounts reconciled against invoices, with exceptions raised on a dashboard.` ## Step-by-step build ### Step 1: Plan the integration and prerequisites We line up licenses and access before installing anything. - A Salesforce edition compatible with the package, and a sandbox to install into first - A Chargent account and admin rights on both systems - The records, templates, and outcomes agreed up front ### Step 2: Install the managed package We install Chargent the safe way. - Install from AppExchange into a sandbox first, choosing Install for All Users - Approve the third-party access it requests, and note the API or remote endpoints it uses > **Pro tip: sandbox first** Install the managed package in a sandbox first and choose Install for All Users, so you can configure and test safely before anything touches production. ### Step 3: Assign licenses and permission sets We give the right users the right access. - Assign the package licenses and its permission sets to the integration user and the end users who need it ### Step 4: Authenticate to Chargent We connect the package to your Chargent account securely. - Authenticate Chargent via OAuth and configure the org-wide and per-user settings - Confirm any Named Credential or Remote Site the package relies on is configured ### Step 5: Configure objects, templates, and layouts We set Chargent up around how you actually work. - Configure the Chargent-specific pieces such as templates, gateways, or components - Add the Lightning components and actions to the right page layouts - Map Salesforce fields into Chargent so documents and records are accurate every time ### Step 6: Build automation around the package We make Chargent fire from the right place and write results back. - Record-triggered flows or Quick Actions invoke the package's invocable methods - Status and results are written back onto the Salesforce record automatically Reference implementation (`snippets/GenerateDocument.cls`): ```apex public class GenerateDocument { @InvocableMethod(label='Generate document via package') public static void run(List recordIds) { // a record-triggered flow calls this; it hands off to the managed package for (Id recId : recordIds) { pkg.DocumentService.createFromTemplate(recId, 'Order Form'); } } } ``` ### Step 7: Test in a sandbox We validate the full flow before go-live. - Run real scenarios end to end and confirm the records, documents, and callbacks ### Step 8: Deploy and monitor We ship it and support it. - Deploy configuration via change sets and assign permission sets in production - Monitor callbacks and errors, with 30 days of support ## Data model | Object | Purpose | Key fields | | --- | --- | --- | | `Payment` | The primary Salesforce record Chargent data maps onto. | `External_Id__c, Name, Status` | | `Account` | Matched or created for the customer or company behind the record. | `Name, External_Id__c` | | `Error_Log__c (custom)` | Captures every request, response, and failure so anything can be replayed. | `Payload__c, Status__c, Related_Id__c` | Salesforce objects typically in play: `ChargentOrders__ChargentOrder__c`, `ChargentOrders__Transaction__c`, `ChargentOrders__Gateway__c`, `Opportunity / Order / Case (via Chargent Anywhere)` ## Field mapping (example) | Chargent | Salesforce | Notes | | --- | --- | --- | | Chargent charge id | `Payment.External_Id__c` | Unique external id, upsert key | | Chargent amount | `Payment.Amount` | | | Chargent currency | `Payment.CurrencyIsoCode` | | | Chargent customer | `Account` | Matched or created | | Chargent status | `Payment.Status` | Picklist value mapping | | Created / updated at | `LastModifiedDate` | Enables delta sync and audit | | Owner or rep | `Payment.OwnerId` | Assignment rules or a default owner | Tailor the full mapping to the org. Always upsert on an external-id field so retries are idempotent. ## API and rate limits ### Chargent-specific - Salesforce Apex callout limits (100 callouts/transaction, 120s, 6MB heap) - Gateway-specific transaction and rate limits - Scheduled and recurring charges bound by Apex batch and scheduled-job limits ### Salesforce platform - The managed package uses its own API budget. We confirm the limits on your plan before go-live. - Chargent rate limits apply to bulk operations. We chunk batches to stay within them. ## Security checklist - Secrets stored in Named Credentials and permission sets, never in code or metadata - A least-privilege integration user, with field-level security and sharing scoped tight - All traffic over TLS, with signature verification on inbound events - Card data never touches Salesforce, keeping your PCI scope minimal - Shield Platform Encryption available for sensitive fields - A full audit trail: every request and response logged for traceability - Every automation runs as a dedicated integration user, so actions are attributable and revocable - Sandbox-first delivery and change-set deployment keep production changes reviewed and controlled ## Monitoring and reliability - Every request and response is logged to a custom Error Log object, tagged with the related record id. - Failed calls retry with exponential backoff; anything still failing lands in a dead-letter queue for review. - Idempotency keys guarantee a retried or duplicate event never double-posts a record. - A dashboard surfaces failures, latency, and volume so problems are caught before users notice. - Optional email or Slack alerts fire on repeated failures or a stalled sync. ## Testing and deployment - Apex unit tests with HttpCalloutMock cover the success path, failure handling, and a 200-record bulk case, at 75 percent or higher coverage. - The full flow is validated in a sandbox against real sample data and the edge cases that matter. - A parallel run reconciles the integration against your live system before cutover. - Everything deploys through change sets or an SFDX and CI pipeline, under version control. - Permission sets, sharing, and Named Credentials are configured in production, then we run 30 days of monitored hypercare. ## Pitfalls to design out - **Config lost between orgs:** Deploy configuration via change sets and document the setup. - **Users cannot see the feature:** Assign the package license and permission set to the right users. - **Vendor limits hit unexpectedly:** Confirm the API and volume limits on your plan before go-live. - **No visibility when it breaks:** We log every call and surface failures on a dashboard with alerts, so an issue never goes unnoticed. - **Reporting drifts from reality:** External-id keys and a delta timestamp keep Salesforce and the source reconciled, so reports stay trustworthy. ### Chargent-specific gotchas - Chargent Anywhere is required to process payments on objects other than Chargent Orders - Tokenize at the gateway (not in Salesforce) to reduce PCI scope - Each gateway needs its own Gateway record and credentials; some gateways are SOAP rather than REST ## FAQ **How do you authenticate Chargent with Salesforce?** We connect Chargent using the managed package with OAuth and store every secret in Salesforce Named Credentials with a permission set, so nothing is hard-coded or shipped in metadata. **Does the Chargent integration handle bulk volume?** Yes. All Apex is bulkified, volume moves to Queueable or Batch Apex, and we respect the Salesforce governor limits (SOQL, DML, and callout caps per transaction). **How do you prevent duplicate records?** We upsert on a unique external-id field, so a retried or duplicate payload is idempotent and never creates a second Payment. **How is the integration tested and deployed?** Apex tests with HttpCalloutMock cover the success, failure, and a 200-record bulk case (75 percent plus coverage). We deploy via change sets or an SFDX and CI pipeline. **What happens if Chargent or Salesforce is briefly down?** Failed calls retry with backoff and land in an Error Log object with alerting, so nothing is lost and any event can be replayed. **Do we still need custom code?** Usually only a thin layer: record-triggered flows or a small invocable Apex method to fire the package and write results back. The heavy lifting is the managed package. --- Maintained by [Cloudsheer](https://www.cloudsheer.com). Full illustrated guide: [Chargent technical guide](https://www.cloudsheer.com/integrations/chargent/technical-guide). Want it built for you at a fixed price? [Book a free 30-minute call](https://cal.com/cloudsheer-consulting/30min?overlayCalendar=true).