Developer guide
VEX Pay siteAPI reference
Browse documentation

Brand the hosted checkout

Show your logo and brand color on the payment page, in light and dark mode. VEX Pay keeps every screen readable whatever color you pick.

Overview

Buyers pay with more confidence when the payment page looks like the business they are buying from. The hosted checkout can show your logo, your business name and your brand color, in light or dark mode. You set it once in the portal and it applies everywhere you sell: there is nothing to integrate and nothing to redeploy.

You controlVEX Pay keeps fixed
Logo and business nameError, warning and success colors, so a failed or expired payment always looks like one
Brand color: main buttons, selected options, links, the countdown and the line on the payment card’s top edge“Pago seguro procesado por VEX Pay” and the VEX Pay mark at the bottom of every screen (never recolored, cannot be hidden)
Light, dark or automatic modeText contrast: VEX Pay adjusts shades of your color when needed so every text stays readable

Set it up in the portal

  1. Open Business profile

    In the portal, go to Perfil del negocio. Upload your logo there if you have not yet: use a square image (PNG, JPEG or WebP, up to 2 MB) with some space around the mark.

  2. Pick your color

    Under Colores de tu página de pago, choose a swatch, use the color picker or type a value such as #0A7A5C in Color de marca. Leave it empty to keep the VEX Pay purple.

  3. Choose the mode

    Automático follows each buyer’s phone or computer, Claro is always light and Oscuro is always dark.

  4. Check the previews and save

    The two previews show the Pago Móvil step exactly as buyers see it, in light and in dark mode. If the color is hard to read on one of them, a warning explains what VEX Pay will adjust (see Readable with any color). Click Guardar colores.

Your test account uses the same business profile as your live account, so you can set up and check your branding in test mode before you go live.

What buyers see

The page has two cards. On a computer the payment card is on the left and the order summary on the right, both starting at the same height. On a phone the summary comes first while the buyer picks a method; once a payment is in progress, the payment card moves to the top.

  • Payment card: your logo (or your initial on a circle tinted with your color) and business name, a thin line in your color on its top edge, the payment steps, and “Pago seguro procesado por VEX Pay” at the bottom.
  • Total a pagar: the amount in large type. For dollar-priced links it also shows the dollar equivalent and the rate (Tasa BCV or Tasa de mercado). When the link expires, a pill shows how long it stays open.
  • Estás pagando: the product photo (or a receipt icon), its name and description, the quantity, and the breakdown down to the total.
  • Vendido por: your RIF, WhatsApp, email, website and verified badge. It only appears when you have at least one of them, so the page never repeats just your name.
  • A one-line note at the bottom of the summary: encrypted connection, and a receipt once the payment is made.

Readable with any color

Every color on the page is derived from the one you pick. VEX Pay guarantees WCAG AA contrast in both modes: at least 4.5:1 for text and 3:1 for borders and focus rings. Your exact color fills the buttons and the line on the payment card’s top edge (except in the rare case below where no button text can be read on it). When your color would make text hard to read, VEX Pay uses a darker shade of it on the light page, or a lighter shade on the dark page. Button text is white or near-black, whichever reads better on your color.

Your colorButtonsLinks and text, light modeLinks and text, dark mode
#6941C6 (VEX Pay purple)#6941C6, white text#6941C6#9978FF (lighter)
#1A1F5C (navy)#1A1F5C, white text#1A1F5C#7180C6 (lighter)
#B5F23D (lime)#B5F23D, dark text#587C00 (darker)#B5F23D

The portal warns you before you save when your color needs adjusting. You can always save it anyway: the warning only tells you what buyers will see.

WarningWhenWhat the checkout does
Too light for textText in your color would be under 4.5:1 on the white card (yellows, limes, light pastels)Uses the darker shade shown in the warning for links and text in light mode. The portal also suggests up to three similar colors that work as they are.
Button adjustedNeither white nor dark text reaches 4.5:1 on your color (some mid-tone oranges and greens)Shifts the button fill to the nearest shade where the text is readable. The warning names that shade.

Light and dark mode

Tema de la página de pagoWhat buyers see
Automático (default)Light or dark, following the buyer’s phone or computer setting
ClaroAlways light
OscuroAlways dark

The mode is chosen when the page loads, so buyers never see a flash of the wrong theme. The embedded checkout (@vexpay/js) follows your setting, not the colors of the page that embeds it.

Where your branding applies

SurfaceBrandedNotes
Payment links and product linksYesFrom the next page load, including links already shared.
Checkout sessions (POST /v1/checkout/sessions)YesThe session url opens the branded page.
Embedded checkout (@vexpay/js)YesFollows your mode setting, not the host page’s colors.
Marketplace merchant links and sessionsYesThe merchant’s color if it has one, otherwise yours. The mode is always yours. See Marketplace merchants below.
Test modeYesSame business profile as live.
Printed or PDF receiptNoKeeps fixed black-and-white print colors so it prints well on any printer.
Emails and webhooksNoBranding only changes how the hosted page looks.

Marketplace merchants (API)

If you run a marketplace, each merchant’s payment links and checkout sessions can carry that merchant’s own color, just as they carry the merchant’s logo. Set brandColor when you create or update the merchant. The mode (light, dark or automatic) cannot be set per merchant: it is always your account’s.

The checkout picks the color in this order: the merchant’s brandColor, then your account’s brand color, then the VEX Pay purple.

You sendResult
"brandColor": "#0A7A5C"Saved. Merchant reads return "#0A7A5C".
"brandColor": "#0a7a5c"Accepted and saved uppercase: reads return "#0A7A5C".
"brandColor": nullClears the merchant’s color: its links use your account’s color.
Field omittedNo change (on create: no merchant color).
"", "0A7A5C" (no #), "#0A7" (3 digits), "teal"Rejected with 400. Nothing is saved.
curlbash
curl --request PATCH "${API_URL}/v1/merchants/MERCHANT_ID" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "brandColor": "#0A7A5C" }'
Nodejavascript
await vexpay.merchants.update(merchantId, { brandColor: '#0A7A5C' });

// Back to your account's color
await vexpay.merchants.update(merchantId, { brandColor: null });
Pythonpython
vexpay.merchants.update(merchant_id, {"brandColor": "#0A7A5C"})

# Back to your account's color
vexpay.merchants.update(merchant_id, {"brandColor": None})
PHPphp
$vexpay->merchants->update($merchantId, ['brandColor' => '#0A7A5C']);

// Back to your account's color
$vexpay->merchants->update($merchantId, ['brandColor' => null]);

An invalid value answers 400 with the standard validation body. Show the message to whoever typed the color, or validate before sending with /^#[0-9A-Fa-f]{6}$/.

400 responsejson
{
  "statusCode": 400,
  "message": ["brandColor must be a 6-digit hex color, e.g. #0A7A5C"],
  "error": "Bad Request"
}

Test before you go live

  • Create a payment link with your test key and open it. Test mode uses the same business profile as live, so it shows your real branding.
  • Check both modes. On a computer, switch the system to dark mode, or in Chrome open DevTools → Rendering → Emulate CSS media feature prefers-color-scheme. On a phone, switch the system appearance.
  • Go through a whole payment: method choice, the Pago Móvil step and the result screen. In test mode, Simular pago recibido completes the payment without moving money.
  • If you embed the checkout, test it on your real page: a fixed light or dark site usually needs Claro or Oscuro instead of Automático.
  • For marketplace merchants, create a checkout session with merchantId and confirm the merchant’s color and logo appear.

Copy or share the Pago Móvil details

On the Pago Móvil step, Copiar todos copies the bank, phone, RIF and exact amount in one go, in the format bank apps expect. On phones, Compartir sends the same text through WhatsApp or any other app, for buyers whose payment is made by someone else. The text holds only your receiving details and the amount: no buyer data and no link.

Copied textbash
Pago Móvil
Banco: R4 Conecta (0169)
Teléfono: 04149333844
RIF: J-50832436-6
Monto: Bs 1837,53

The amount has no thousands separator and uses a comma for decimals, because that is how bank apps read pasted amounts. If the browser blocks the clipboard, the text appears in a box the buyer can select and copy by hand.

Troubleshooting

What you seeWhyWhat to do
Links look a little darker (or lighter) than my colorYour color is too light (or too dark) for readable text in that mode, so VEX Pay uses an adjusted shade for links and text.Expected. To use one exact color everywhere, pick one of the suggestions in the portal warning.
The checkout is dark but my site is whiteAutomático follows the buyer’s device, not your page.Pin Claro in Perfil del negocio.
I saved a new color but a buyer still sees the old oneTheir page was already open.It updates on reload. No link needs to be recreated.
A merchant link shows my color, not the merchant’sThe merchant has no brandColor, or the link was created without merchantId.Read the merchant (GET /v1/merchants/:id) to check brandColor, and create the link or session with merchantId.
400 when setting brandColorThe value is not # followed by exactly 6 hex digits. An empty string also fails.Send #RRGGBB, or null to clear.
My logo looks cramped or cutLogos are fitted into a square.Upload a square version with some empty space around the mark.
I can’t change the dark mode for one merchantThe mode is set per account, not per merchant.Set it in Perfil del negocio. It applies to all your merchants.