Custom checkout domain

​

Why use a custom domain

​

What changes, and what doesn’t

​

Before you start

• A domain you own, and access to its DNS settings (at your registrar or DNS provider).
• A subdomain you don’t use for anything else, for example pay.yourstore.com or checkout.yourstore.com. Payviox serves the whole subdomain, so pick one that has no website, email or other DNS record on it. Deeper subdomains such as pay.shop.yourstore.com work too.
• The Manage settings permission on your Payviox business. Team members without it can see the domain and its status, but can’t add or remove it.

​

Set up your domain

​

Domain statuses

​

Use your domain

​

Without the SDK: redirect or iframe

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "checkout_url": "https://pay.yourstore.com/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

- https://secure.payviox.com/{session_id}
+ https://pay.yourstore.com/{session_id}

const response = await fetch('https://api.payviox.com/session', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PAYVIOX_SECRET_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(sessionParams)
});
const { checkout_url } = await response.json();

res.redirect(checkout_url); // https://pay.yourstore.com/{session_id}

<iframe
  src="https://pay.yourstore.com/SESSION_ID"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

const PAYVIOX_ORIGIN = 'https://pay.yourstore.com';

window.addEventListener('message', (event) => {
  if (event.origin !== PAYVIOX_ORIGIN) return;

  if (event.data?.type === 'payviox:redirect') {
    window.location.href = event.data.redirect;
  } else if (event.data?.type === 'payviox:close') {
    document.getElementById('payment-container').innerHTML = '';
  }
});

​

With the SDK: checkoutUrl

<script src="https://pay.yourstore.com/sdk.js"></script>
<script>
  const payviox = new Payviox('pk_live_your_key', {
    checkoutUrl: 'https://pay.yourstore.com'
  });

  async function checkout() {
    // Your backend creates the session with your secret key (sk_), on api.payviox.com
    const { session_id } = await fetch('/api/checkout', { method: 'POST' }).then((r) => r.json());

    // Opens https://pay.yourstore.com/{session_id}
    payviox.openSession(session_id);
  }
</script>

import Payviox from '@payviox/sdk';

const payviox = new Payviox('pk_live_your_key', {
  checkoutUrl: 'https://pay.yourstore.com'
});

​

Content Security Policy

​

Server side, webhooks and subscriptions

• Server-side calls with your secret key (sk_) stay on https://api.payviox.com: POST /session, GET /payment/{session_id}, subscriptions, balance. Don’t send them to your subdomain.
• Webhooks don’t change: same URL, same events, same HMAC-SHA256 signature.
• Payment links (emails, fallbacks): send the checkout_url from the session response. If you build links yourself, replace secure.payviox.com with your subdomain there too, ideally from a single setting so you can switch back in one place.
• Subscriptions: while your domain is active, the customer’s self-service management_url (in webhooks and the subscriptions API) points to your subdomain: https://pay.yourstore.com/subscription/.... Always use the URL Payviox gives you rather than rewriting its host. The same link also works on secure.payviox.com.

​

Switch back, remove or change your domain

• switch your integration first, and wait for open payment sessions to finish or expire;
• links on your subdomain that you already sent break, including subscription management_url links sent by email. New checkout_url and management_url values go back to secure.payviox.com.

​

Limits

• Subdomains only: root domains (yourstore.com) aren’t supported.
• One domain per business.
• A domain belongs to one business: the same subdomain can’t be connected to two Payviox businesses.
• The subdomain must be dedicated to the Payviox checkout: Payviox serves every path on it.

​

Troubleshooting

​

Related