Guía para desarrolladores
Sitio de VEX PayReferencia de API
Explorar documentación

Pon tu marca en el checkout hospedado

Muestra tu logo y el color de tu marca en la página de pago, en modo claro y oscuro. VEX Pay mantiene cada pantalla legible con cualquier color que elijas.

Resumen

Los compradores pagan con más confianza cuando la página de pago se parece al negocio al que le compran. El checkout hospedado puede mostrar tu logo, el nombre de tu negocio y el color de tu marca, en modo claro u oscuro. Lo configuras una vez en el portal y se aplica en todo lo que vendes: no hay nada que integrar ni que volver a publicar.

Lo que controlasLo que VEX Pay mantiene fijo
Logo y nombre del negocioLos colores de error, aviso y éxito, para que un pago fallido o vencido siempre se vea como tal
Color de marca: botones principales, opciones seleccionadas, enlaces, la cuenta regresiva y la línea del borde superior de la tarjeta de pago“Pago seguro procesado por VEX Pay” y la marca de VEX Pay al final de cada pantalla (nunca cambian de color y no se pueden ocultar)
Modo claro, oscuro o automáticoEl contraste del texto: VEX Pay ajusta tonos de tu color cuando hace falta para que todo se lea bien

Configúralo en el portal

  1. Abre Perfil del negocio

    En el portal, entra a Perfil del negocio. Si aún no lo has hecho, sube ahí tu logo: usa una imagen cuadrada (PNG, JPEG o WebP, hasta 2 MB) con algo de espacio alrededor.

  2. Elige tu color

    En Colores de tu página de pago, toca una muestra, usa el selector o escribe un valor como #0A7A5C en Color de marca. Déjalo vacío para mantener el morado de VEX Pay.

  3. Elige el modo

    Automático sigue el teléfono o la computadora de cada comprador, Claro es siempre claro y Oscuro es siempre oscuro.

  4. Revisa las vistas previas y guarda

    Las dos vistas previas muestran el paso de Pago Móvil tal como lo ve el comprador, en modo claro y oscuro. Si el color se lee mal en alguna, un aviso explica qué ajustará VEX Pay (ve Legible con cualquier color). Toca Guardar colores.

Tu cuenta de prueba usa el mismo perfil del negocio que tu cuenta live, así que puedes configurar y revisar tu marca en modo de prueba antes de salir a producción.

Lo que ve el comprador

La página tiene dos tarjetas. En computadora, la tarjeta de pago va a la izquierda y el resumen a la derecha, las dos a la misma altura. En el teléfono el resumen va primero mientras el comprador elige el método; cuando hay un pago en curso, la tarjeta de pago pasa arriba.

  • Tarjeta de pago: tu logo (o tu inicial en un círculo teñido con tu color) y el nombre del negocio, una línea fina de tu color en el borde superior, los pasos del pago y “Pago seguro procesado por VEX Pay” al final.
  • Total a pagar: el monto en grande. En los enlaces con precio en dólares muestra también el equivalente en dólares y la tasa (Tasa BCV o Tasa de mercado). Si el enlace vence, una etiqueta indica cuánto tiempo le queda.
  • Estás pagando: la foto del producto (o un ícono de recibo), su nombre y descripción, la cantidad y el desglose hasta el total.
  • Vendido por: tu RIF, WhatsApp, correo, sitio web y la insignia de verificado. Solo aparece si tienes al menos uno de ellos, para no repetir solo tu nombre.
  • Una nota de una línea al final del resumen: conexión cifrada y comprobante al pagar.

Legible con cualquier color

Todos los colores de la página salen del que eliges. VEX Pay garantiza contraste WCAG AA en los dos modos: al menos 4,5:1 para textos y 3:1 para bordes y anillos de foco. Tu color exacto rellena los botones y la línea del borde superior de la tarjeta de pago (salvo en el caso poco común de abajo, en el que ningún texto de botón se lee sobre él). Cuando tu color haría difícil leer un texto, VEX Pay usa un tono más oscuro en la página clara o uno más claro en la página oscura. El texto de los botones es blanco o casi negro, el que mejor se lea sobre tu color.

Tu colorBotonesEnlaces y textos, modo claroEnlaces y textos, modo oscuro
#6941C6 (morado de VEX Pay)#6941C6, texto blanco#6941C6#9978FF (más claro)
#1A1F5C (azul marino)#1A1F5C, texto blanco#1A1F5C#7180C6 (más claro)
#B5F23D (lima)#B5F23D, texto oscuro#587C00 (más oscuro)#B5F23D

El portal te avisa antes de guardar cuando tu color necesita ajustes. Siempre puedes guardarlo igual: el aviso solo te dice lo que verán los compradores.

AvisoCuándoQué hace el checkout
Muy claro para textosUn texto de tu color quedaría por debajo de 4,5:1 sobre la tarjeta blanca (amarillos, limas, pasteles claros)Usa en modo claro el tono más oscuro que muestra el aviso para enlaces y textos. El portal también sugiere hasta tres colores parecidos que funcionan tal cual.
Botón ajustadoNi el texto blanco ni el oscuro llegan a 4,5:1 sobre tu color (algunos naranjas y verdes de tono medio)Mueve el relleno del botón al tono más cercano en el que el texto se lee bien. El aviso indica ese tono.

Modo claro y oscuro

Tema de la página de pagoLo que ve el comprador
Automático (por defecto)Claro u oscuro, según la configuración de su teléfono o computadora
ClaroSiempre claro
OscuroSiempre oscuro

El modo se decide al cargar la página, así que el comprador nunca ve un destello del tema equivocado. El checkout embebido (@vexpay/js) sigue tu configuración, no los colores de la página que lo incrusta.

Dónde se aplica tu marca

SuperficieCon tu marcaNotas
Enlaces de pago y de productoSíDesde la siguiente carga de la página, incluidos los enlaces ya compartidos.
Sesiones de checkout (POST /v1/checkout/sessions)SíLa url de la sesión abre la página con tu marca.
Checkout embebido (@vexpay/js)SíSigue tu modo, no los colores de la página que lo incrusta.
Enlaces y sesiones de comercios del marketplaceSíEl color del comercio si tiene uno; si no, el tuyo. El modo siempre es el tuyo. Ve Comercios del marketplace más abajo.
Modo de pruebaSíMismo perfil del negocio que en live.
Comprobante impreso o en PDFNoMantiene colores fijos en blanco y negro para imprimirse bien en cualquier impresora.
Correos y webhooksNoLa marca solo cambia cómo se ve la página hospedada.

Comercios del marketplace (API)

Si tienes un marketplace, los enlaces de pago y las sesiones de checkout de cada comercio pueden llevar el color de ese comercio, igual que llevan su logo. Envía brandColor al crear o actualizar el comercio. El modo (claro, oscuro o automático) no se puede definir por comercio: siempre es el de tu cuenta.

El checkout elige el color en este orden: el brandColor del comercio, luego el color de marca de tu cuenta y por último el morado de VEX Pay.

Lo que envíasResultado
"brandColor": "#0A7A5C"Se guarda. Las lecturas del comercio devuelven "#0A7A5C".
"brandColor": "#0a7a5c"Se acepta y se guarda en mayúsculas: las lecturas devuelven "#0A7A5C".
"brandColor": nullBorra el color del comercio: sus enlaces usan el color de tu cuenta.
Campo omitidoSin cambios (al crear: sin color propio).
"", "0A7A5C" (sin #), "#0A7" (3 dígitos), "teal"Se rechaza con 400. No se guarda nada.
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' });

// Volver al color de tu cuenta
await vexpay.merchants.update(merchantId, { brandColor: null });
Pythonpython
vexpay.merchants.update(merchant_id, {"brandColor": "#0A7A5C"})

# Volver al color de tu cuenta
vexpay.merchants.update(merchant_id, {"brandColor": None})
PHPphp
$vexpay->merchants->update($merchantId, ['brandColor' => '#0A7A5C']);

// Volver al color de tu cuenta
$vexpay->merchants->update($merchantId, ['brandColor' => null]);

Un valor inválido responde 400 con el cuerpo de validación estándar. Muestra el message a quien escribió el color, o valídalo antes de enviarlo con /^#[0-9A-Fa-f]{6}$/.

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

Pruébalo antes de salir a producción

  • Crea un enlace de pago con tu clave de prueba y ábrelo. El modo de prueba usa el mismo perfil del negocio que live, así que muestra tu marca real.
  • Revisa los dos modos. En computadora, cambia el sistema a modo oscuro, o en Chrome abre DevTools → Rendering → Emulate CSS media feature prefers-color-scheme. En el teléfono, cambia la apariencia del sistema.
  • Recorre un pago completo: elección del método, el paso de Pago Móvil y la pantalla de resultado. En modo de prueba, Simular pago recibido completa el pago sin mover dinero.
  • Si embebes el checkout, pruébalo en tu página real: un sitio con fondo fijo claro u oscuro normalmente necesita Claro u Oscuro en lugar de Automático.
  • Para comercios del marketplace, crea una sesión de checkout con merchantId y confirma que aparecen el color y el logo del comercio.

Copiar o compartir los datos del Pago Móvil

En el paso de Pago Móvil, Copiar todos copia de una vez el banco, el teléfono, el RIF y el monto exacto, en el formato que esperan las apps de los bancos. En el teléfono, Compartir envía el mismo texto por WhatsApp o cualquier otra app, para compradores cuyo pago lo hace otra persona. El texto solo lleva tus datos de cobro y el monto: ni datos del comprador ni enlaces.

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

El monto no lleva separador de miles y usa coma para los decimales, porque así leen las apps de los bancos un monto pegado. Si el navegador bloquea el portapapeles, el texto aparece en un recuadro que el comprador puede seleccionar y copiar a mano.

Solución de problemas

Lo que vesPor quéQué hacer
Los enlaces se ven un poco más oscuros (o claros) que mi colorTu color es demasiado claro (u oscuro) para un texto legible en ese modo, así que VEX Pay usa un tono ajustado en enlaces y textos.Es lo esperado. Para usar un mismo color exacto en todo, elige una de las sugerencias del aviso en el portal.
El checkout se ve oscuro pero mi sitio es blancoAutomático sigue el dispositivo del comprador, no tu página.Fija Claro en Perfil del negocio.
Guardé un color nuevo pero un comprador sigue viendo el anteriorSu página ya estaba abierta.Se actualiza al recargar. No hace falta crear el enlace de nuevo.
Un enlace de un comercio muestra mi color y no el del comercioEl comercio no tiene brandColor, o el enlace se creó sin merchantId.Lee el comercio (GET /v1/merchants/:id) para revisar brandColor, y crea el enlace o la sesión con merchantId.
400 al enviar brandColorEl valor no es # seguido de exactamente 6 dígitos hexadecimales. Un texto vacío también falla.Envía #RRGGBB, o null para borrarlo.
Mi logo se ve apretado o cortadoLos logos se ajustan a un cuadrado.Sube una versión cuadrada con algo de espacio vacío alrededor.
No puedo cambiar el modo oscuro de un solo comercioEl modo se define por cuenta, no por comercio.Defínelo en Perfil del negocio. Aplica a todos tus comercios.