Virtuous

Overview

The Virtuous integration syncs Donately donor and donation data to Virtuous CRM Constituents and Gifts. It supports custom field mapping and recurring gift tracking.

Once connected, syncs are triggered automatically when a donation is created, updated or refunded, when a donor’s details change, and when a recurring plan changes.

What Gets Synced

• Constituent — Donor identity, address, and contact information
• Gift — Each donation, including recurring subscription details

Connecting

Virtuous does not offer a standard OAuth authorization screen. Instead, it uses password-based authentication (OAuth 2.0 Resource Owner Password Credentials) to exchange your Virtuous username and password for an access token, which Donately stores and uses for all subsequent syncs.

To connect Virtuous to Donately:

1. In the Donately dashboard, go to Integrations and click Install on the Virtuous card.
2. Enter the email address and password you use to sign in to Virtuous CRM.
3. If your Virtuous account has multi-factor authentication enabled, you will be prompted for a one-time code after submitting your credentials. Enter the code Virtuous sends to your authenticator app or email and click Connect again.
4. On success, you are returned to the Integrations page and the Virtuous card shows Active.

Configuration

Per-account settings live on the Virtuous card's Configure page in the Donately dashboard (/native-integrations/virtuous/configure), listed here in the order they appear there:

Sync Modes

Gifts reach Virtuous by one of two routes, chosen per account with settings.sync_mode. The trade-off is immediacy vs. review: direct mode puts the gift in Virtuous within seconds, queue mode holds it for an admin to approve first.

Two consequences worth planning around:

• Project rules resolve differently. Queue mode matches the Project by name, so a Project renamed in Virtuous stops matching and the gift lands undesignated in the “Update Needed” bucket. Direct mode matches by ID and is unaffected by renames.
• Recurring gifts are linked by different mechanisms. In direct mode Donately creates the Virtuous RecurringGift record itself and attaches each charge to it as a payment, immediately. In queue mode every charge carries a shared series identifier and its frequency, and Virtuous’s import matching groups them into a recurring gift when the batch is approved. The practical difference is timing and control: the recurring record does not exist until someone approves the first charge, and because Donately never receives its ID, a later cancellation is matched to the recurring gift rather than addressed by ID.

When bank donations appear

Card gifts sync within seconds of the payment completing.

For most cards that is the moment the donor submits. If the donor’s bank requires 3D Secure — the extra verification step where they approve the payment in their banking app — the gift appears once they finish that challenge, not when they press Donate. That is usually still seconds, but a donor who switches devices or gets a slow bank page can take longer. If they abandon the challenge, no gift is created at all: the payment never completed, so there is nothing to record.

Bank transfers (ACH) do not settle immediately. The money takes several business days to clear, and by default Donately waits for it to settle before creating the gift. An account on direct sync mode can opt out of that wait — see Refunds & bank donation timing on the Configure page. Measured across 66 recent settlements, clearing took 3.5 to 6.5 days, averaging 5.1 — so a bank donation given on a Monday usually appears in Virtuous between Thursday and the following Monday.

PayPal usually settles within minutes and behaves like a card. The exception is when the donor pays from a bank account rather than a balance or card — PayPal then holds the payment while it clears, and that gift waits for settlement in the same way an ACH gift does. You cannot tell which it will be at the moment the donor gives.

If you turn that wait off, a transfer that later bounces is cleaned up for you: Donately removes the gift it created, so nothing is left claiming money that never arrived. Worth knowing about that:

• A deletion leaves no visible trace. The gift simply disappears, with no reversing entry in the donor’s giving history to explain it — so a total that moves between two reports has nothing in Virtuous to account for the change.
• A gift your team has already acknowledged or receipted is never deleted. Removing it would undo real work with nothing to show for it, so it stays and Donately raises a warning instead, for you to correct by hand.
• This applies only to gifts Donately created early and that never settled. A genuine refund is different — that money did arrive, so it is cancelled with a reversing transaction and both entries stay on the donor’s record.

Custom Fields

Donately sends a set of custom fields so your Virtuous records carry the Donately donation, transaction, subscription, campaign, fundraiser and form identifiers alongside the standard amount/date/donor data.

Most go on the Gift object. Three of them — the subscription fields — are sent on both Gift and Recurring Gift, so if you want them on the recurring record you have to create them twice, once on each object. The Object column below says which.

Where to create them in Virtuous

1. Open Settings (the gear at the bottom of the left sidebar) and choose the Data Customization tab.
2. Find the Custom Fields and Collections card and click Custom Fields. You can also go straight there: app.virtuoussoftware.com/Generosity/CustomField
3. Click New Custom Field.
4. Set OBJECT to the object named in the table below — Gift for most, Recurring Gift for the subscription fields’ second copy. It defaults to Contact, and a field created on the wrong object will not receive any of this data — this is the easiest step to get wrong.
5. Enter the NAME exactly as written in the table below, including the dntly_ prefix. The match is exact.
6. Set DATA TYPE to Text. Every field below is text, including the true/false ones — Donately sends "true" / "false" as strings.
7. Save Field, then repeat for each field you want.

DISPLAY and GROUP are optional and affect only how the field is labelled and grouped in the Virtuous UI.

The table is ordered by how much each field adds, so if you are not creating all fourteen, start at the top. Every one is Text type.

Every one of these is optional — skip any you don't want, and it is simply omitted. Nothing about the integration depends on them: gift matching, donor matching, amounts, dates, designations and recurring linkage all use Virtuous's built-in fields and work whether or not a single custom field exists.

If you only want a few, the ones that carry information not available anywhere else on the gift are dntly_donation_form, dntly_form_id, dntly_transaction_id and dntly_donation_status. Note that dntly_donation_id duplicates the gift's built-in Transaction ID, and anonymity and tribute text are already written to Virtuous's own fields.

Field Mapping

How Donately data lands on the Virtuous record.

Constituent

Gift

Built-in Virtuous fields are always written. Custom fields (dntly_*) are only stored if you created them first.

Recurring Gift

When a donor sets up a recurring gift, Donately also creates a RecurringGift record in Virtuous and attaches each charge to it as a payment. This happens in direct mode; in queue mode Virtuous builds the equivalent record itself from the series identifier on each transaction (see Sync Modes).

Each individual charge is then attached to that record from the gift side, as recurringGiftPayments: [{ id, amount, state: "Add" }].

Donately also sends three custom fields on the recurring gift record. Like the gift custom fields, they are only stored if you create them first — on the Recurring Gift object this time, not Gift:

These three are also sent on the Gift object, so they appear in the Custom Fields table too — creating them there does not create them here. Same steps, with Object set to Recurring Gift.

Frequency is a fixed Virtuous enum, and only these Donately cadences map onto it:

Any other cadence — daily, every 2 or 3 days, fortnightly, every 4 months — has no Virtuous equivalent. Those charges still sync as ordinary one-time gifts; only the recurring record is skipped, and the integration records a warning rather than misrepresenting the schedule on the donor’s record.

Cancelling in Donately cancels in Virtuous when Donately knows which record to cancel. Where it doesn’t — queue-mode subscriptions, and older ones set up before this was added — it will only act on an unambiguous match of amount and frequency for that donor. Anything less certain raises a warning for you to cancel by hand, because cancelling the wrong schedule cannot be undone.

Record Matching

The integration uses the following strategies to find existing records before creating new ones. Strategies are tried in order — the first match wins.

Constituent Matching

Gift Matching

Both use built-in Virtuous fields, so matching works whether or not any custom fields are installed.

Advanced

Project Linking

Each Virtuous gift can be designated to a Project — Virtuous's accounting object for funds, programs, or campaigns. Donately picks the Project for each gift by walking an ordered list of rules. Rules are evaluated top-to-bottom, and the first matching rule wins. A donation that doesn't match any rule will not be designated to a Project unless you add a fallback rule.

Each rule has a type and the fields specific to that type:

Order rules from most specific to least specific. If you use a fallback_project rule, put it last so it only fires when nothing earlier matched.

Example settings.project_rules:

[
  { "type": "form", "match_value": "frm_abc123", "virtuous_project_id": 12345 },
  { "type": "meta_data", "meta_key": "appeal", "match_value": "endofyear", "virtuous_project_id": 67890 },
  { "type": "campaign", "match_value": "cmp_xyz789", "virtuous_project_id": 11111 },
  { "type": "fallback_project", "virtuous_project_id": 99999 }
]

The matched rule designates the gift amount to that Project. If the donor covered the processing fee and you have configured a fee Project, the gift arrives with two designations instead — the fee amount to the fee Project, the remainder to the matched one. The wire shape differs by sync mode: direct sends giftDesignations: [{ projectId, amount, state }] and matches the Project by ID; import_queue sends designations: [{ name, amountDesignated }] and matches by name, so renaming a Project in Virtuous will stop queue-mode rules from matching.

Precedence: in direct mode, project linking sets the gift's projects array after the payload is built from the field mappings, so if a custom mapping override also writes to projects, the project rule wins. In queue mode the designations travel under a different key, so a custom mapping writing projects is left untouched and simply has no effect.

Missing Name Fallback

Virtuous expects a first and last name on every constituent, while Donately accepts donors with no name at all — anonymous donors, single-field donation forms, mobile flows that only ask for email. Without a fallback those donors have nothing to create a contact from, and their gifts cannot sync.

This applies when both names are missing. A donor with one of the two is sent through as-is.

Two strategies are available, configured via settings.missing_name_fallback:

Either way, if the donor has no name and no usable email (blank, or no @), the integration falls back to recording the skip — there's nothing to synthesize from.

Custom Field Mapping

You can override the default field mappings with a custom mapping. Custom mappings are defined as a JSON object where keys are Donately field names and values are the target Virtuous property names.

{
  "Person": {
    "unique_identifier": "referenceId"
  },
  "Donation": {
    "donation_amount_for_native_integrations": "amount",
    "donation_date_for_virtuous": "giftDate",
    "donation_name_for_native_integrations": "description",
    "currency": "currencyCode",
    "comment": "notes",
    "on_behalf_of": "tributeDescription",
    "anonymous": "isPrivate"
  }
}

• Person — Maps donor fields to Virtuous Constituent properties
• Donation — Maps donation fields to Virtuous Gift properties

Supplying a mapping with only one Donation key would stop sending the gift's date, description, currency, notes, tribute and privacy flag on every subsequent sync.

The keys are Donately method names, not column names, and several differ from what you might guess — donation_amount_for_native_integrations, not donation_amount. A key that isn't a real method fails the sync for that record.