USAePay SPF, DKIM and DMARC setup, step by step

USAePay documents include:spf.usaepay.com for SPF and three DKIM CNAME records for custom sending domains. Publish those records safely, check the relevant merchant or partner portal status, and verify the intended branded From address and an aligned passing DKIM signature on a delivered message. USAePay's own help supplies this procedure; it is not an assumption that every NMI product uses the same setup. USAePay SPF and DKIM instructions.

The documented gps2 and gps3 selectors are rotation reserves whose public keys may be empty. Publish their CNAMEs as instructed, but assess a message using the selector it actually carries. An empty reserve is different from an invalid key on an active signature.

No merchant account, DNS record, receipt, payment or delivered message was tested in preparing this guide.

Choose the correct USAePay sending route

The scope is gateway-generated mail, not a message sent by your own webshop simply because it contains a USAePay transaction reference.

The merchant validation guide and partner validation guide describe distinct controls. The merchant guide is in USAePay's Legacy Console documentation. Match the account interface to that documented route; a differently branded or newer portal is not proof that every setting is interchangeable.

Before editing, inventory the merchant/partner account, affected message type, desired Email From address, domain owner, DNS administrator and any per-template or application overrides. Confirm whether the gateway or another application actually sends each message. Do not treat a green status in one partner field as approval for every merchant domain.

Prerequisites and a safe change plan

You need an authorized account administrator, control of the intended sending domain's DNS, the current sender settings, and a recipient mailbox controlled by your organization. Save the existing SPF, DKIM, DMARC and relevant sender configuration with an approved rollback plan.

A public webmail address is unsuitable for this custom-domain workflow because you cannot publish USAePay authorization under someone else's domain. If you cannot control the desired domain, use the provider-supported sender option rather than attempting to send as that domain. The official instructions describe leaving the From setting blank or choosing another address. USAePay domain-ownership guidance.

Keep payment data out of authentication diagnostics. Use an approved non-production or otherwise harmless sending workflow with dummy content. Do not create, refund or replay a real payment to obtain a sample, and do not trigger real customer password resets or settlement reports. If no safe sample path exists, ask the account owner or USAePay support for a supported test route and leave message acceptance pending.

Add USAePay to one SPF policy

USAePay's documented authorization mechanism is:

include:spf.usaepay.com

This is not a complete SPF policy. Locate the existing SPF TXT policy at the domain USAePay instructs you to configure, and insert the mechanism before its terminal all. Preserve other approved senders and the existing qualifier. The provider discourages copying its sending IPs because they may change. Official SPF setup.

Illustrative merge only; spf.existing-provider.example is a placeholder, not a real authorization:

Before: v=spf1 include:spf.existing-provider.example -all
After: v=spf1 include:spf.existing-provider.example include:spf.usaepay.com -all

Keep the space before -all. Joining it to spf.usaepay.com changes the token and breaks the intended policy. If the existing policy uses redirect=, review the resulting evaluation instead of blindly appending a mechanism. If there is no policy, inventory every legitimate sender before choosing a complete policy and terminal qualifier.

If the existing SPF policy uses redirect=, do not blindly append an all mechanism or a complete canned policy: any all mechanism makes redirect ignored. Preserve the redirect-authorized senders and approved final semantics through a reviewed policy design. SPF redirect semantics.

Publish only one SPF policy at each evaluated owner. Unrelated TXT records may coexist and must not be deleted. Two independent v=spf1 records do not combine authorizations and can cause permerror. A root policy does not automatically cover a subdomain. SPF record selection, safe SPF merging.

The SPF limit is ten evaluated DNS-dependent terms, counting nested include, a, mx, ptr, exists and redirect operations. It is not merely ten top-level includes or ten packets. Literal ip4, ip6 and all do not consume that budget. Analyze all relevant evaluation paths; adding one include can introduce multiple nested terms. RFC 7208, section 4.6.4.

SPF checks the SMTP MAIL FROM identity, not the visible From header. The setup instruction to authorize a custom domain does not prove what envelope identity a particular gateway message uses. Record the actual smtp.mailfrom during acceptance. Adding an include cannot make an unrelated provider envelope domain align with your brand.

Publish all three documented DKIM CNAMEs

For a sending domain of example.com, USAePay publishes the following exact mappings. Replace the customer domain only; do not change the provider targets or invent a public key. Official DKIM record table.

These are provider-documented shared delegation targets, not sample tenant keys. Apply them only to the USAePay route covered by the source. If your actual account supplies a different record set, resolve the product/route difference with support rather than replacing an existing working configuration by analogy.

For receipts.example.com as the sending domain, the first full owner would be gps1._domainkey.receipts.example.com. In the example.com zone, an editor that appends the zone suffix normally takes gps1._domainkey.receipts; in a separately delegated receipts.example.com zone it normally takes gps1._domainkey. Some editors require a full name instead. Inspect the saved owner so the suffix is not doubled.

For an existing delegated _domainkey.receipts.example.com authority, full owner gps1._domainkey.receipts.example.com maps to relative gps1; map gps2 and gps3 likewise. Preserve the NS delegation and publish at that authority without deleting other selectors. Relative DNS names.

Before adding a CNAME, check that its owner has no conflicting TXT, A, CNAME-to-another-target or other ordinary data. Do not remove a selector used by another service without a coordinated transition. The targets must remain visible as ordinary, unflattened DNS aliases, not be hidden behind a website proxy. If a sending subdomain or _domainkey subtree is legitimately delegated, publish in its actual authoritative child zone; do not delete the delegation to make the parent-zone editor accept a record. Delegated DNS ownership. Do not change MX records for this procedure; USAePay's cited setup asks for SPF TXT and DKIM CNAMEs.

If you use Cloudflare, set these authentication CNAMEs to DNS only, keep their record-level Flatten option off where available, and check that the zone-wide CNAME flattening for all CNAME records setting is not flattening them. DNS-only does not by itself rule out flattening. Cloudflare warns that flattening can hide the CNAME required by a third-party verifier, and an enabled zone-wide setting cannot be overridden per record. Coordinate any shared-setting change with the DNS owner and other services, then verify that each selector query returns its intended CNAME. Do not alter unrelated website records or legitimate child-zone delegations. Cloudflare flattening controls.

Keep the required literal CNAME answer: turn relevant per-record Flatten off where available and ensure applicable whole-zone settings do not suppress the alias. On Cloudflare, apex CNAMEs are flattened by default and same-zone targets are flattened regardless of that setting; flatten-all cannot be overridden per record. If mandatory behavior or a shared setting prevents the required answer, stop and coordinate a supported configuration without breaking other services or removing NS delegation. These are DNS-host behaviors, not controls assumed in the sending provider. Cloudflare flattening controls and limits.

USAePay explicitly says gps2 and gps3 may have empty public keys reserved for later rotation and still asks customers to publish their CNAMEs. A generic key checker can flag those reserves without proving current mail fails. Conversely, if an actual message uses one of those selectors and its key cannot validate the signature, that is a real failure to resolve with the provider. Do not create replacement key material or delete reserve delegations to silence a scanner. Rotation-reserve explanation.

Check portal validation and the selected From address

Use the portal location appropriate to the account:

• Merchant: Settings > General, Email under Account Information.
• Partner: Settings > Console Branding, applicable email fields.

Both guides describe green DOMAIN VALIDATED / OK, yellow UNABLE TO VALIDATE, and red INVALID EMAIL ADDRESS states. Yellow can still allow saving; saving therefore is not evidence that authentication is ready. An invalid address is not saved. Merchant states, partner states.

The merchant documentation says validation refreshes daily and the display can take 24–48 hours to change. Separate that refresh delay from authoritative DNS correctness. A correct DNS answer and an old yellow banner call for a timed recheck, not repeated record edits; a wrong owner requires correction, not waiting.

The cited workflow does not give a separate customer-operated DKIM signing switch. Publish the supported records, retain the intended sender configuration, and use portal validation plus a delivered-message test to establish that signing is active. Do not invent an activation button.

USAePay says custom branding can fall back to a safewebservices.com sending domain when the required authentication is missing. A delivered receipt using that fallback is not successful custom-domain setup. Record the actual From address, even if all receiver authentication results are green. Fallback behavior.

Preserve DMARC and confirm alignment

A DMARC pass needs at least one passing, aligned identifier: SPF's authenticated MAIL FROM or DKIM's signing domain. The comparison is against the visible From domain. Relaxed alignment allows an organizational-domain match; strict alignment requires the exact domain. RFC 9989 alignment rules.

With From: receipts@example.com, d=example.com can align strictly or relaxed. d=receipts.example.com can align relaxed but not strictly with that From domain. d=safewebservices.com does not align with example.com. A CNAME pointing into safewebservices.com does not itself make that the signing domain: the signature's d= determines where DKIM starts its key lookup. DKIM signature identities.

Do not claim a custom return-path feature: the reviewed USAePay setup pages do not document one. Use the observed envelope identity and distinguish SPF authentication from SPF alignment. See custom MAIL FROM and alignment for that distinction.

Before editing DMARC, inspect the existing record and any applicable inherited parent policy. Preserve enforcement, reporting recipients and adkim/aspf modes. Adding a monitoring record beneath a protected parent can weaken that subdomain's policy, so it is not a routine setup shortcut.

Only if no direct or applicable inherited policy exists and the domain owner approves the monitoring and review plan, use the correct owner:

Example monitoring value only:

v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com

Replace the address with the approved reporting destination, publish one applicable DMARC policy at the owner, and ensure someone reviews the reports. An external report destination may require authorization under RFC 9990. Restrict access and retention; do not send real receipt content to public analyzers or add ruf without a privacy review. Failure-report considerations.

Compare the Organizational Domain of the aggregate report URI’s host with the Organizational Domain of the domain where the DMARC policy was found, not necessarily the visible From domain. If they differ, the report-generating receiver must check DNS authorization. A destination within the same Organizational Domain as that policy domain is excepted; a different hostname alone does not make it external. This protocol check is separate from the domain owner’s approval to share report data with that recipient. RFC 9990 section 4.

p=none monitors and does not request quarantine or rejection. RFC 9989 removed pct, so do not promise a percentage-based rollout. Review every legitimate sender before stronger enforcement. A domain using p=reject must apply valid DKIM and must not rely solely on SPF. Interoperability requirements.

Validate DNS, then accept a harmless gateway sample

Substitute your exact sending domain and authoritative nameserver in these read-only checks. They have not been run for a customer domain in this guide.

dig +short NS example.com
dig @AUTHORITATIVE_NS TXT example.com +noall +answer
dig @AUTHORITATIVE_NS CNAME gps1._domainkey.example.com +noall +answer
dig @AUTHORITATIVE_NS CNAME gps2._domainkey.example.com +noall +answer
dig @AUTHORITATIVE_NS CNAME gps3._domainkey.example.com +noall +answer
dig +short TXT gps1._domainkey.example.com
dig +short TXT _dmarc.example.com

For a sending subdomain, query its actual SPF and selector owners instead. Expect the merged SPF policy and all three exact CNAME targets. Follow the selector's CNAME chain to its public-key TXT data. Inspect any lookup error with a full DNS response; a blank +short result alone is inconclusive. Compare authoritative and recursive answers, allowing for TTL and negative caching.

Obtain a newly delivered, harmless sample through each authorized merchant or partner workflow you intend to use. Preserve the receiving service's raw headers privately. Trust only authentication results added by the recipient system or its trusted gateway, not sender-supplied lookalike fields. Use receiver-controlled message diagnostics or have the receiving administrator establish the trust boundary and how externally supplied authentication headers are removed or ignored. A familiar authentication-server identifier or a header’s position alone is not proof. Authentication-Results trust.

A passing SPF result alone does not complete this DKIM setup, even if it produces DMARC pass. Require the intended branded DKIM signature itself to pass and align. Both mechanisms need not align for a single message to pass DMARC, but an unrelated provider signature does not satisfy branded-DKIM acceptance.

The source's sample-IP SPF test is a diagnostic example, not proof of your message's current egress IP or MAIL FROM identity. Use observed evidence for the real workflow. Authentication does not guarantee inbox placement, authorize a payment request, or prove a message's contents are safe.

Diagnose failures and recover safely

For an incident, preserve a redacted header sample, portal state, DNS diff and timestamps. Pause the affected workflow or restore the previously approved sender configuration where possible. Revert only the incorrect change; do not delete shared records or weaken DMARC for the whole organization. Retain keys needed by delayed signed messages under an agreed retirement plan. Redact customer addresses, transaction details and secrets before sharing diagnostics with support.