Add Your Logo to the Payment Page: Light and Dark SVG Logos
You can now add your logo to the MercanPay payment page: two SVG logos for light and dark themes, the file rules, security checks and practical design tips.
Adding your logo to the payment page is the simplest way to show customers they're in the right place when they pay. The MercanPay hosted payment page can now display your business logo. You can upload separate logos for the light and dark themes, so customers always see the version that matches the theme they're using. This post covers how it works, the file rules and some tips for good results.
Why a logo matters
When a customer leaves your site for the hosted payment page, there's a brief moment of "Am I in the right place?". That moment matters, especially for people new to crypto. A familiar logo:
- confirms the customer is paying the right business,
- makes the jump from your site to the payment page feel consistent,
- builds trust in payment links shared over social media or chat.
Your business name already appears on the payment page, and a logo takes that recognition a step further visually. Other factors that affect conversion are covered in 9 crypto checkout tips.
How to add your logo to the payment page
- Open the Settings page in the merchant panel.
- Find the Payment page logos card. The feature is optional.
- Upload your SVG files for the light and dark themes.
- You'll see a confirmation once each logo is saved, and it starts appearing on your invoices' payment pages.
To remove a logo, use the same card. When you replace a logo, the new version shows on the payment page right away.
Why two logos: light and dark themes
The payment page supports light and dark themes. It opens in the theme set by the customer's device, and the customer can switch with the theme button on the page.
A dark logo that looks great on a light background can disappear on a dark one, so you get two options:
- Upload two logos, and the one matching the customer's current theme is shown. If the customer switches themes, the logo switches too.
- Upload one logo, and it's used on both themes, placed on a white or dark tile where needed so it stays readable.
For the cleanest look, we recommend preparing both versions, for example dark lettering for the light theme and white lettering for the dark theme.
File rules
These rules apply when you upload a logo:
| Rule | Detail |
|---|---|
| Format | SVG only |
| Size | Up to 500 KB per file |
| Aspect ratio | Square or landscape, at most 4:1 (width:height) |
| Dimensions | The SVG needs a viewBox, or width and height |
The logo is shown at a fixed height with its width following the ratio. Portrait (tall) logos aren't accepted, and logos wider than 4:1 are rejected because they'd look tiny.
Why SVG only, and what's not allowed
SVG is vector-based, so it stays sharp on every screen and is usually small. But SVG is also an XML document that can carry active content such as scripts, and that has no place on a page where your customers pay.
So every uploaded SVG is checked before it's saved. Files containing any of the following are rejected:
<script>tags,- event attributes such as
onclickoronload, javascript:links,<foreignObject>and embedded content such asiframe,embed,objectorvideo,- DOCTYPE and ENTITY declarations,
- CSS
@importand links to external addresses.
In-document references (#id) and PNG, JPG, WEBP or GIF data embedded inside the SVG are allowed. Logos are also only ever served as images, with a strict content security policy, so even a logo opened directly can't run a script.
These checks are a deliberate choice to keep the payment page safe. Our wider approach to security is covered in crypto merchant account security.
Tips for preparing your logo
SVGs exported from design tools sometimes contain unnecessary or disallowed content. If an upload fails, try these:
- Convert text to outlines so the logo doesn't depend on external font files.
- Remove external references, such as
hreforurl()values pointing to outside images or fonts. - Trim the padding. Extra whitespace makes the logo smaller when it's shown at a fixed height.
- Add a
viewBox. Most tools do this automatically. If it's missing, open the file in a text editor and add it to the root<svg>tag. - Keep the file lean. Stripping unneeded metadata reduces its size.
Where the logo appears
The logo appears at the top of the payment page, next to your business name. Customers see the same branding while choosing a coin, while viewing the address and QR code, and when the payment is confirmed. Other payment page features are covered in hosted crypto payment page features.
The logo appears the same way on payment links you create in the panel and on invoices created through the API. Creating invoices in the panel is covered in create your first crypto invoice, and if you sell on social media, see crypto payment links for Telegram and Instagram sellers.
Other settings that round out your branding
A logo does a lot on its own, but a few other settings complete the customer's experience:
- Business name: shown next to your logo. Use the name your customers know.
- Description: an invoice's
descriptionis shown to the customer. Something clear like "Premium membership · 1 month" tells them exactly what they're paying for. - Back to store address:
return_urlis where the "Back to store" button leads. - Post-payment redirect:
success_urltakes the customer to your own thank-you page after paying.
You can set these addresses as defaults in Settings or pass them per invoice.
FAQ
Can I upload a PNG or JPG logo?
Not directly. Only SVG is accepted, but an SVG file can contain embedded PNG, JPG, WEBP or GIF data. Where possible, we recommend a vector version of your logo.
Is a logo required?
No, the feature is optional. Without a logo, the payment page keeps showing your business name.
I get an aspect ratio error. What should I do?
Your logo is either portrait or wider than 4:1. Trim the padding or use a square or landscape variant of your logo.
I changed my logo, so why do I still see the old one?
The new logo is used as soon as it's saved. Refreshing a payment page that was already open is enough to show it.
Get started with MercanPay
To accept crypto payments under your own brand, apply for a merchant account. Payment page and integration details are in the documentation.
