---
name: authvia-salesforce
description: Build a production-grade AuthVia 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 AuthVia and Salesforce integration.
---

# AuthVia to Salesforce integration

> Cloudsheer's delivery playbook for AuthVia on Salesforce, distilled from 1 client projects and 7 delivery tasks. Apply it as the reference approach when building this integration.

## Overview

Invoice-based payments supporting five or more gateways. We have shipped it across 1 client project and 7 build tasks.

The value is that the action happens automatically from the record your team already works in, with the result tracked back in Salesforce.

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 AuthVia 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 (AppExchange): a native composite app with Apex callouts to the Authvia platform
- Requires both a Base Package and an Extension Package
- TXT2PAY, email invoicing, hosted payment page and virtual terminal driven from Salesforce records and Experience Cloud

**Package:** Authvia for Salesforce (Base + Extension Package)

**Authentication:** Authvia platform API credentials used by the composite-app callouts over HTTPS; underlying gateway credentials are configured inside Authvia, not in Salesforce

**API type:** REST

**Key endpoints:**
- `Send payment request (TXT2PAY)`
- `Email invoice / payment-link email`
- `Hosted payment page`
- `Virtual terminal charge`
- `Recurring / automated payment`

**Official docs:** https://www.authvia.com/platform/salesforce-payment-solutions/

## 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
- A AuthVia 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 AuthVia data

## Architecture

Data flows left to right through four lanes:

1. **Sources:** Salesforce record, Flow / Apex trigger
2. **Integration layer:** Payload build, AuthVia API call, Status write-back
3. **Salesforce:** Order, Related records, Reports
4. **Outcomes:** Action done automatically, Status on the record, No app-switching

## How it works at runtime

1. **Trigger in Salesforce** `[In Salesforce]`: A record change or a button starts the AuthVia action.
   - Note: `A record-triggered flow or a Quick Action fires the process.`
2. **Payload is built** `[In Salesforce]`: A flow or Apex assembles the request and maps the Salesforce fields.
   - Note: `Serialized with JSON.serialize; the callout is queued to run asynchronously.`
3. **Call AuthVia** `[In transit]`: The request is sent to AuthVia.
   - Note: `HTTPS callout via callout:NamedCredential over Managed package, Flows, with no secrets in code.`
4. **Result written back** `[In Salesforce]`: AuthVia performs the action and the status is written back.
   - Note: `Response parsed; status and external ids stored on the record for audit.`

## 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 AuthVia account and admin rights on both systems
- The records, templates, and outcomes agreed up front

### Step 2: Install the managed package

We install AuthVia 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 AuthVia

We connect the package to your AuthVia account securely.

- Authenticate AuthVia 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 AuthVia up around how you actually work.

- Configure the AuthVia-specific pieces such as templates, gateways, or components
- Add the Lightning components and actions to the right page layouts
- Map Salesforce fields into AuthVia so documents and records are accurate every time

### Step 6: Build automation around the package

We make AuthVia 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<Id> 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 |
| --- | --- | --- |
| `Order` | The primary Salesforce record AuthVia 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: `Authvia objects (Payment Request / Transaction / Invoice)`, `Account`, `Contact`, `Opportunity`, `Case`

## Field mapping (example)

| AuthVia | Salesforce | Notes |
| --- | --- | --- |
| Salesforce Order | `AuthVia record` | Direction: Salesforce to AuthVia |
| Record id | `AuthVia external reference` | Stored back on the record |
| Key fields | `AuthVia fields` | Mapped per template |
| Status | `AuthVia status` | Written back on completion |
| Created / updated at | `LastModifiedDate` | Enables delta sync and audit |
| Owner or rep | `Order.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

### AuthVia-specific

- Licensing: minimum 10 users plus an Authvia subscription
- Gateway-agnostic: throughput is bound by the connected gateway
- Salesforce Apex callout limits on request and status calls

### Salesforce platform

- The managed package uses its own API budget. We confirm the limits on your plan before go-live.
- AuthVia 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
- 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.

### AuthVia-specific gotchas

- BOTH the Base and Extension packages are required; installing only one breaks the app
- Multi-gateway configuration lives in the Authvia platform, not in Salesforce
- Card data is captured on Authvia hosted pages, so the PAN never touches Salesforce

## FAQ

**How do you authenticate AuthVia with Salesforce?**

We connect AuthVia 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 AuthVia 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 Order.

**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 AuthVia 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: [AuthVia technical guide](https://www.cloudsheer.com/integrations/authvia/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).