Elegir la versión de la API de Payload: v1 o v2

Payload, el proveedor de pagos detrás de REDA Pay, ofrece dos versiones de su interfaz de programación. REDA Pay puede usar cualquiera de las dos, y la elección se hace por Pay Profile con un solo campo, Versión de la API de Payload (Payload API Version). Un perfil en blanco, o en v1, funciona exactamente como REDA Pay siempre lo ha hecho. Un perfil en v2 usa la interfaz actual de Payload y, con ella, las pantallas de pago nuevas: datos de tarjeta y cuenta escritos en un formulario seguro que Payload sirve dentro de la pantalla, pantallas que funcionan en cualquier tipo de sitio de Experience Cloud, mensajes de webhook firmados y tus propios colores y fuentes.

Este artículo explica qué cambia, cómo decidir, cómo cambiar un perfil y cómo volver atrás.

Antes de empezar

El Pay Profile existe y su clave de API está guardada — consulta Crear un Pay Profile y guardar la clave de API de Payload.
Tienes REDA Pay - Admin User. El campo solo lo modifican los administradores.
Si el campo no está en tu página de Pay Profile, tu organización actualizó desde una versión anterior y hay que colocarlo primero en el formato de página — consulta Actualizar REDA Pay.

Qué cambia entre v1 y v2

Tema	v1 (en blanco)	v2
Pantalla de pago dentro de Salesforce	La pantalla clásica: el formulario de tarjeta o cuenta forma parte de la página	La pantalla v2 se abre desde el mismo botón: mosaicos de métodos, el panel del importe y un formulario seguro servido por Payload para el número de tarjeta, el código de seguridad y el número de cuenta. Los mensajes de progreso muestran lo que está pasando
A dónde van los números de tarjeta y de cuenta	Se escriben en la pantalla de REDA Pay, se envían a Payload, nunca se guardan	Se escriben en el propio formulario de Payload dentro de la pantalla; no pasan por Salesforce en ningún momento
Páginas del portal de clientes y del sitio público	Los componentes clásicos (NewPayOrder, NewPayOrderRequest…), que solo funcionan en sitios Aura	Los componentes v2 (REDA Pay - New Pay Order (v2)…), que funcionan en sitios Aura y LWR. Un perfil v2 necesita los componentes v2 en sus páginas: los clásicos rechazan un perfil v2 con "Esta página requiere un perfil de pago con la API v2 de Payload."
Webhooks	Diez webhooks en `…/payload/…`; Configurar webhooks elimina todos los webhooks de la clave de API	Once webhooks en `…/payloadv2/…`, firmados opcionalmente con un secreto; Configurar webhooks elimina solo los webhooks de este perfil
Apariencia	Logotipo, encabezado y pie desde la cuenta de procesamiento; colores fijos	Lo mismo, más los colores del tema del entorno por defecto y tus propios colores y fuente con Apariencia del pago o los ajustes del componente
Depósitos de garantía (EMD)	Disponibles	Rechazados: no se puede crear una orden EMD en un perfil v2
Registros, clientes, métodos guardados, órdenes, transacciones	Idénticos en ambas versiones	Ambas leen y escriben los mismos registros e identificadores de Payload, así que un cliente creado en v1 paga en v2 con la tarjeta guardada, y a la inversa
Botones, programadores, informes, API de Apex	Idénticos	Idénticos

Cómo decidir

Una instalación nueva: elige v2. Es la interfaz actual de Payload, y con el formulario seguro tu organización nunca maneja un número de tarjeta.
Una organización que ya usa REDA Pay en sitios Aura y dentro de Salesforce: quedarse en v1 no cambia nada. Cambia a v2 cuando quieras el formulario seguro, un sitio LWR o webhooks firmados, y planifica antes las páginas del portal y del sitio público, porque un perfil v2 necesita ahí los componentes v2.
Un portal de clientes o un sitio público LWR: v2 es obligatorio; los componentes clásicos no funcionan en páginas LWR.
Depósitos de garantía (EMD): mantén ese perfil en v1.

Puedes tener un perfil en v1 y otro en v2 en la misma organización. Las pantallas leen la versión del perfil de la orden que se paga.

Cambiar un perfil a v2

Hazlo primero en un sandbox y luego en producción. El cambio en sí tarda un minuto; las páginas y el acceso que necesita son la parte larga, así que lee la lista completa antes de empezar.

Páginas del portal y del sitio público. Si este perfil sirve a un portal de clientes o a un sitio público de enlaces de pago, coloca los componentes v2 en esas páginas y escribe los nombres de página exactos, como se describe en Permitir que los clientes paguen en tu portal y Configurar el sitio público de enlaces de pago. Hasta el cambio, las páginas nuevas conviven con las antiguas; las clásicas siguen funcionando para v1.
Acceso para tus propios perfiles. Si tus usuarios, los usuarios del portal o el usuario invitado del sitio público tienen tus propios perfiles o conjuntos de permisos clonados en lugar de los conjuntos de REDA Pay del paquete, concede las dos clases y la página que se enumeran en Actualizar REDA Pay. Las organizaciones que asignan los conjuntos del paquete ya las tienen.
Usuario invitado del sitio de webhooks. En el sitio que recibe los mensajes de Payload, habilita la clase de Apex rpay.PayloadCallbackV2 para el usuario invitado, junto a rpay.PayloadCallback — Configurar webhooks, Parte 2.
Establecer la versión. Abre la app REDA Pay → Pay Profiles → el perfil → Modificar. En Versión de la API de Payload elige v2. Guarda.
Secreto de firma (recomendado). Haz clic en Actualizar secreto del webhook (Update Webhook Secret), escribe un secreto de hasta 64 caracteres que guardes en un lugar seguro y haz clic en Actualizar secreto. El mensaje "El secreto de firma del webhook se actualizó. Ejecute Configurar webhooks para aplicarlo." lo confirma.
Registrar los webhooks de nuevo. Haz clic en Configurar webhooks (Setup Webhooks) y confirma. La pestaña Configuración de webhooks del perfil muestra ahora once filas cuyas direcciones contienen /payloadv2/.
Vuelve a publicar cada sitio de Experience Cloud que aloja las pantallas v2, si las colocaste en el paso 1 sin publicar.
Prueba como cada tipo de pagador: un usuario del personal desde un Lead, un usuario del portal y un invitado que abre un enlace de pago. Los datos de tarjeta o cuenta se escriben en el formulario seguro; aparecen los mensajes de progreso; se crea la Pay Transaction; unos minutos después su estado se actualiza a través de los webhooks.

el registro de Pay Profile con Versión de la API de Payload en v2 y la acción Actualizar secreto del webhook junto a Actualizar token de API, Sincronizar cuentas de procesamiento y Configurar webhooks

El campo de versión y las tres acciones con las que trabaja. Todo lo demás en el perfil es igual.

Volver a v1

Pon Versión de la API de Payload en v1 (o déjala en blanco), guarda y ejecuta de nuevo Configurar webhooks para que Payload envíe a la dirección v1. No cambia ningún dato. Las páginas que tienen los componentes v2 dejan de funcionar para este perfil ("Esta página requiere un perfil de pago con la API v2 de Payload."), así que apunta antes la navegación del portal a las páginas clásicas. Como Configurar webhooks en un perfil v1 elimina todos los webhooks de la clave de API, vuelve a registrar después cualquier otro perfil o sistema que comparta esa clave.

Lo que el cambio no hace

No mueve, copia ni vuelve a registrar clientes, métodos guardados, órdenes ni transacciones. Son compartidos.
No cambia tus cuentas de procesamiento, tarifas, imagen de marca, controles ni ajustes de enlaces.
No cambia quién puede pagar: los conjuntos de permisos son los mismos.
No sustituye los componentes clásicos de tus páginas. Los v2 los colocas tú.

Errores que debes evitar

Error	Qué ocurre	Solución
Cambiar a v2 antes de que las páginas del portal o del sitio público tengan los componentes v2	Los clientes y los pagadores por enlace ven "Esta página requiere un perfil de pago con la API v2 de Payload."	Coloca primero los componentes v2, o vuelve a v1 hasta que estén listos
Cambiar sin ejecutar Configurar webhooks	Payload sigue enviando a la dirección v1; los estados dejan de actualizarse	Ejecuta Configurar webhooks después de cada cambio de versión
Usuario invitado del sitio de webhooks sin `rpay.PayloadCallbackV2`	Los mensajes v2 de Payload se rechazan; los estados nunca se actualizan	Habilita la clase en el perfil de invitado
Escribir el secreto de firma en el campo Secreto de firma del webhook con Modificar	El valor se guarda sin cifrar y no coincide con el que usa Payload para firmar	Usa la acción Actualizar secreto del webhook y luego Configurar webhooks
Esperar depósitos de garantía en v2	La orden EMD se rechaza	Mantén un perfil EMD en v1

Preguntas frecuentes

No. La misma clave sirve para ambas versiones. REDA Pay añade la versión a cada solicitud.

Pulsan el mismo botón. La pantalla que se abre es la v2: mosaicos para los métodos guardados, el formulario seguro para una tarjeta o cuenta nueva y mensajes de progreso mientras se ejecuta el pago.

Sí. Crea un segundo Pay Profile con la misma clave de API, ponlo en v2 y limita una página de prueba a él con Limit Profile Selection. Solo un perfil a la vez recibe los webhooks de Payload para una clave compartida, así que reserva los webhooks del perfil de prueba para la prueba.

Qué sigue

Configurar webhooks: la dirección v2, el secreto de firma y la clase del invitado.
Permitir que los clientes paguen en tu portal: las páginas v2 en un sitio Aura o LWR.
Cobrar un pago: la pantalla v2 paso a paso.