White-labelling

White-labelling removes VoPay from the addresses your customers see. It has two independent parts:

• Custom URLs serve the portal, eLinx and other hosted pages from your own hostname, with your page title and favicon.
• Custom email domain sends notification emails from an address on your own domain instead of [email protected].

Both build on Branding. A white-labelled page still needs your logo and colours to look like yours, and a custom email domain is only used on emails that carry your branding.

Custom URLs

What can be served from your domain

Each hosted product can be mapped to a hostname on your domain. VoPay derives your root domain from the hostname you register and serves every related page from the matching subdomain.

Once a hostname is active, every link VoPay generates for that product uses your domain automatically: eLinx payment request URLs, the iFrame URL returned by the eLinx access-token endpoint, and the verification, approval and cross-border links in emails. No change to your integration is needed.

What a white-labelled login page shows

When the portal is opened on your hostname, the login page is built from your configuration before anyone signs in:

• Your Portal branding (logo and colours)
• Your page title, shown in the browser tab
• Your favicon
• Your configured SSO providers, if any

Page title and favicon are part of the hostname configuration, not the branding settings, so they are set up with VoPay (see below). They are also returned in the PageTitle and Favicon fields of GET /account/branding-details.

Inheritance

A hostname can belong to an account or to a partner. Resolution follows the same chain as branding: the account's own hostname, then each parent account, then the partner. A partner therefore needs one hostname per product and every sub-account shares it. A sub-account that needs its own URL can have one registered for it directly.

Setting up a custom URL

Custom URLs are configured by VoPay, not self-serve. To set one up, send your VoPay account manager:

1. The product(s) you want white-labelled and the hostname for each, for example account.acmepayments.com.
2. The page title to show in the browser tab.
3. A favicon image.
4. Whether the hostname belongs to your account or to your partner account (for a partner, all sub-accounts inherit it).

VoPay will reply with the DNS records to publish for each hostname and will activate the hostname once DNS resolves. Sandbox hostnames (the -dev variants) are provisioned separately, so ask for both if you want to test before going live.

After activation, make sure your Portal and eLinx branding is set. A white-labelled page with no branding shows VoPay's default logo and colours.

Custom email domain

By default, every email VoPay sends on your behalf comes from [email protected]. With a verified sending domain, white-labelled emails come from an address on your domain instead, with your name as the sender. Emails are signed with DKIM and use a return path on your domain, so they pass DMARC checks for your domain.

Prerequisites

• The Email Domain feature enabled on your account by VoPay.
• Email branding enabled, since only emails sent with your branding use the custom sender. See the list of branded emails in Branding.
• A portal user with the Manage Email Domains permission to make changes.
• Access to the DNS for the domain you want to send from.

One sending domain can be registered per account. To change domains, remove the existing one first.

Setting up a sending domain

1. Add the domain. In the portal go to Settings → Email Domain and click New domain, or call POST /account/domain/add. VoPay registers the domain and returns two CNAME records.

2. Publish the two CNAME records at your DNS provider. One is the DKIM key, the other is the return path:

   Record	Host	Points to
   DKIM	{selector}._domainkey.yourdomain.com	dkim.smtp2go.net
   Return path	{selector}.yourdomain.com	return.smtp2go.net

   The exact selectors are shown on the Email Domain page and returned by the API. The page has a copy button for each value.

3. Verify. Click Verify on the Email Domain page, or call POST /account/domain/verify, once the records have propagated. The domain status changes from unverified to verified when both records resolve.

4. Optionally set sender addresses (see below). Without one, emails are sent from [email protected].

Sender addresses and display names

You can configure which address on your domain is used, with an optional display name. Each sender is tied to a purpose. The purposes are default, payments, onboarding, portal and statements.

Today every branded email uses the default sender. The other purposes are accepted so that specific email types can be routed to their own address as that support is added, without changing your configuration. Set a default sender first.

The address chosen for an email is the sender configured for that email's purpose, then the default sender, then [email protected]. The display name is the sender's FromName when one is set, otherwise your account's short name.

Sender addresses must be on your registered domain. They are managed through the API:

Partners and sub-accounts

If your partner has a verified sending domain and your account does not, branded emails for your account are sent from the partner's domain with the partner's name. Partner-level domains are configured by VoPay; ask your account manager.

API reference

All domain endpoints require account credentials (AccountID, Key, Signature) and the Manage Email Domains user permission when called with a portal user token.

Add a domain

POST /api/v2/account/domain/add

AccountID=...&Key=...&Signature=...&Domain=acmepayments.com

{
  "Success": true,
  "ErrorMessage": "",
  "Domain": {
    "Domain": "acmepayments.com",
    "Status": "unverified",
    "Registrar": null,
    "CnameRecords": {
      "DKIM": {
        "Hostname": "s123456._domainkey",
        "Target": "dkim.smtp2go.net",
        "Text": "The full hostname will be s123456._domainkey.acmepayments.com",
        "Verified": false
      },
      "ReturnPath": {
        "Hostname": "em123456",
        "Target": "return.smtp2go.net",
        "Text": "The full hostname will be em123456.acmepayments.com",
        "Verified": false
      }
    }
  }
}

Adding a second domain returns Email domain already exists for this account. Please remove the existing domain before adding a new one.

Verify a domain

POST /api/v2/account/domain/verify

AccountID=...&Key=...&Signature=...&Domain=acmepayments.com

Returns the same Domain object with the current Status and per-record Verified flags. Call it again if DNS has not propagated yet.

Fetch the domain

GET /api/v2/account/domain?AccountID=...&Key=...&Signature=...

Returns the same Domain object, or an empty object when no domain is registered.

Remove a domain

POST /api/v2/account/domain/delete

AccountID=...&Key=...&Signature=...&Domain=acmepayments.com

Removes the domain and all of its sender addresses. Emails return to [email protected] immediately.

Set a sender address

POST /api/v2/account/domain/sender/set

AccountID=...&Key=...&Signature=...
[email protected]
FromName=Acme Payments
Purpose=payments

Purpose defaults to default. FromName is optional and limited to 100 characters.

{
  "Success": true,
  "ErrorMessage": "",
  "Purpose": "payments",
  "EmailAddress": "[email protected]",
  "FromName": "Acme Payments"
}

List sender addresses

GET /api/v2/account/domain/sender?AccountID=...&Key=...&Signature=...

{
  "Success": true,
  "ErrorMessage": "",
  "Domain": "acmepayments.com",
  "Senders": [
    { "Purpose": "default", "EmailAddress": "[email protected]", "FromName": "Acme" },
    { "Purpose": "payments", "EmailAddress": "[email protected]", "FromName": "Acme Payments" }
  ],
  "EffectiveSender": "[email protected]"
}

EffectiveSender is the address a branded email would be sent from right now. It is null while no verified domain applies to the account.

Delete a sender address

POST /api/v2/account/domain/sender/delete

AccountID=...&Key=...&Signature=...&Purpose=payments

Emails for that purpose fall back to the default sender, then to [email protected].

Checklist for a fully white-labelled setup

1. Ask VoPay to enable Portal, eLinx and Email branding, plus the Email Domain feature.
2. Set your logo and colours for each product under Settings → Branding Settings.
3. Send VoPay your hostnames, page title and favicon, publish the DNS records VoPay provides, and confirm the sandbox and production hostnames resolve.
4. Add your sending domain under Settings → Email Domain, publish the two CNAME records and verify.
5. Set a default sender address and display name, and any purpose-specific senders you want.
6. Send a test eLinx request or trigger a transaction notification in sandbox and confirm the link domain, the sender address and the branding all match.