Escolher a versão da API do Payload: v1 ou v2

O Payload, o provedor de pagamentos por trás do REDA Pay, oferece duas versões da sua interface de programação. O REDA Pay pode usar qualquer uma delas, e a escolha é feita por Pay Profile com um único campo, Versão da API do Payload (Payload API Version). Um perfil deixado em branco, ou definido como v1, funciona exatamente como o REDA Pay sempre funcionou. Um perfil definido como v2 usa a interface atual do Payload e, com ela, as novas telas de pagamento: dados de cartão e de banco digitados em um formulário seguro que o Payload exibe dentro da tela, telas que funcionam em todos os tipos de site do Experience Cloud, mensagens de webhook assinadas, e suas próprias cores e fontes.

Este artigo explica o que muda, como decidir, como mudar um perfil e como voltar atrás.

Antes de começar

O Pay Profile existe com a chave de API armazenada — consulte Criar um Pay Profile e armazenar sua chave de API da Payload.
Você tem o REDA Pay - Admin User. O campo é editado apenas por administradores.
Se o campo não está na sua página de Pay Profile, sua organização foi atualizada a partir de uma versão anterior e o campo precisa ser colocado no layout primeiro — consulte Atualizar o REDA Pay.

O que muda entre v1 e v2

Tema	v1 (em branco)	v2
Tela de pagamento dentro do Salesforce	A tela clássica: o formulário de cartão ou conta faz parte da página	A tela v2 abre a partir do mesmo botão: blocos de métodos, o painel do valor e um formulário seguro exibido pelo Payload para o número do cartão, o código de segurança e o número da conta. Mensagens de progresso mostram o que está acontecendo
Para onde vão os números de cartão e de banco	Digitados na tela do REDA Pay, enviados ao Payload, nunca armazenados	Digitados no próprio formulário do Payload dentro da tela; nunca passam pelo Salesforce
Páginas do portal do cliente e do site público	Os componentes clássicos (NewPayOrder, NewPayOrderRequest …), que funcionam apenas em sites Aura	Os componentes v2 (REDA Pay - New Pay Order (v2) …), que funcionam em sites Aura e LWR. Um perfil v2 precisa dos componentes v2 nas suas páginas: os componentes clássicos recusam um perfil v2 com "Esta página requer um perfil de pagamento com a API v2 do Payload."
Webhooks	Dez webhooks em `…/payload/…`; Configurar webhooks remove todos os webhooks da chave de API	Onze webhooks em `…/payloadv2/…`, opcionalmente assinados com um segredo; Configurar webhooks remove apenas os webhooks deste perfil
Aparência	Logotipo, cabeçalho e rodapé da conta de processamento; cores fixas	O mesmo, mais as cores do tema do ambiente por padrão e suas próprias cores e fonte por meio de Aparência do pagamento ou das configurações do componente
Depósitos de garantia (EMD)	Disponíveis	Recusados: uma ordem EMD não pode ser criada em um perfil v2
Registros, clientes, métodos salvos, ordens, transações	Idênticos. As duas versões leem e gravam os mesmos registros e identificadores do Payload, então um cliente criado na v1 paga na v2 com o cartão salvo, e vice-versa
Botões, agendamentos, relatórios, API Apex	Idênticos

Como decidir

Uma instalação nova: escolha v2. É a interface atual do Payload, e o formulário seguro significa que sua organização nunca manipula um número de cartão.
Uma organização que já usa o REDA Pay em sites Aura e dentro do Salesforce: permanecer na v1 não muda nada. Mude para v2 quando quiser o formulário seguro, um site LWR ou webhooks assinados — e planeje primeiro as páginas do portal e do site público, porque um perfil v2 precisa dos componentes v2 nelas.
Um portal do cliente ou site público LWR: v2 é obrigatória; os componentes clássicos não funcionam em páginas LWR.
Depósitos de garantia (EMD): mantenha esse perfil na v1.

Você pode ter um perfil na v1 e outro na v2 na mesma organização. As telas leem a versão do perfil da ordem que está sendo paga.

Mudar um perfil para v2

Faça isso primeiro em um sandbox, depois em produção. A mudança em si leva um minuto; as páginas e os acessos de que ela precisa são a parte mais longa, então leia a lista inteira antes de começar.

Páginas do portal e do site público. Se este perfil atende um portal do cliente ou um site público de links de pagamento, coloque os componentes v2 nessas páginas e defina os nomes das páginas exatamente, como descrito em Permitir que os clientes paguem no seu portal e Configurar o site público de links de pagamento. Até a mudança, as páginas novas ficam ao lado das antigas; as páginas clássicas continuam funcionando para a v1.
Acesso para os seus próprios perfis. Se seus usuários, os usuários do portal ou o usuário convidado do site público têm seus próprios perfis ou conjuntos de permissões clonados em vez dos conjuntos do pacote REDA Pay, conceda as duas classes e a página listadas em Atualizar o REDA Pay. Organizações que atribuem os conjuntos do pacote já as têm.
Usuário convidado do site de webhooks. No site que recebe as mensagens do Payload, ative a classe Apex rpay.PayloadCallbackV2 para o usuário convidado, ao lado de rpay.PayloadCallback — Configurar webhooks, Parte 2.
Definir a versão. Abra o aplicativo REDA Pay → Pay Profiles → o perfil → Editar. Em Versão da API do Payload, escolha v2. Salve.
Segredo de assinatura (recomendado). Clique em Atualizar segredo do webhook (Update Webhook Secret), digite um segredo de até 64 caracteres que você guarde em lugar seguro e clique em Atualizar segredo. A mensagem "O segredo de assinatura do webhook foi atualizado. Execute Configurar webhooks para aplicá-lo." confirma.
Registrar os webhooks de novo. Clique em Configurar webhooks (Setup Webhooks) e confirme. A guia Configuração de webhooks do perfil agora lista onze linhas cujos endereços contêm /payloadv2/.
Publique de novo cada site do Experience Cloud que hospeda as telas v2, se você as colocou na etapa 1 sem publicar.
Teste como cada tipo de pagador: um usuário da equipe a partir de um Lead, um usuário do portal e um convidado abrindo um link de pagamento. Os dados de cartão e de banco são informados no formulário seguro; as mensagens de progresso aparecem; a Pay Transaction é criada; alguns minutos depois o status dela é atualizado pelos webhooks.

o registro de Pay Profile com Versão da API do Payload definida como v2, e a ação Atualizar segredo do webhook ao lado de Atualizar token de API, Sincronizar contas de processamento e Configurar webhooks

O campo de versão e as três ações com as quais ele trabalha. Todo o resto do perfil permanece igual.

Voltar para v1

Defina Versão da API do Payload como v1 (ou limpe o campo), salve e execute Configurar webhooks de novo para que o Payload envie para o endereço v1. Nenhum dado muda. As páginas que contêm os componentes v2 deixam de funcionar para este perfil ("Esta página requer um perfil de pagamento com a API v2 do Payload."), então aponte a navegação do seu portal de volta para as páginas clássicas antes. Como Configurar webhooks em um perfil v1 remove todos os webhooks da chave de API, registre de novo depois qualquer outro perfil ou sistema que compartilhe essa chave.

O que a mudança não faz

Não move, copia nem registra de novo clientes, métodos salvos, ordens ou transações. Eles são compartilhados.
Não altera suas contas de processamento, taxas, marca, controles ou configurações de links.
Não altera quais usuários podem pagar: os conjuntos de permissões são os mesmos.
Não substitui os componentes clássicos nas suas páginas. Quem coloca os v2 é você.

Erros comuns a evitar

Erro	O que acontece	Solução
Mudar para v2 antes de as páginas do portal ou do site público terem os componentes v2	Clientes e pagadores de links veem "Esta página requer um perfil de pagamento com a API v2 do Payload."	Coloque os componentes v2 primeiro, ou volte para v1 até que estejam prontos
Mudar sem executar Configurar webhooks	O Payload continua enviando para o endereço v1; os status param de atualizar	Execute Configurar webhooks depois de cada mudança da versão
Usuário convidado do site de webhooks sem `rpay.PayloadCallbackV2`	As mensagens v2 do Payload são recusadas; os status nunca atualizam	Ative a classe no perfil de convidado
Digitar o segredo de assinatura no campo Segredo de assinatura do webhook com Editar	O valor é armazenado sem criptografia e não corresponde ao que o Payload usa para assinar	Use a ação Atualizar segredo do webhook e depois Configurar webhooks
Esperar depósitos de garantia na v2	A ordem EMD é recusada	Mantenha um perfil EMD na v1

Perguntas frequentes

Não. A mesma chave atende as duas versões. O REDA Pay adiciona a versão a cada solicitação.

Ela clica no mesmo botão. A tela que abre é a v2: blocos para os métodos salvos, o formulário seguro para um cartão ou conta nova e mensagens de progresso enquanto o pagamento é executado.

Sim. Crie um segundo Pay Profile com a mesma chave de API, defina-o como v2 e limite uma página de teste a ele com Limit Profile Selection. Só um perfil por vez recebe os webhooks do Payload para uma chave compartilhada, então mantenha os webhooks do perfil de teste apenas para o teste.

O que vem a seguir

Configurar webhooks: o endereço v2, o segredo de assinatura e a classe do convidado.
Permitir que os clientes paguem no seu portal: as páginas v2 em um site Aura ou LWR.
Receber um pagamento: a tela v2 passo a passo.