Configurar webhooks para que os status se atualizem sozinhos

Um webhook é uma mensagem que um sistema envia a outro quando algo acontece. A Payload envia uma ao Salesforce quando um pagamento é processado, recusado, reembolsado, cancelado ou rejeitado, e quando dinheiro é depositado na sua conta bancária ou sai dela. O REDA Pay recebe essas mensagens e atualiza a Pay Transaction correspondente, ou cria uma Statement Activity para um depósito. Sem webhooks, um pagamento aceito hoje e rejeitado pelo banco três dias depois continua "processed" no Salesforce até que alguém pressione Sync Transaction à mão.

A configuração tem cinco partes: um endereço público no Salesforce que a Payload consiga alcançar, acesso para o usuário convidado por trás desse endereço, o endereço no Pay Profile, acesso para o usuário do Salesforce que processa as mensagens e o botão Setup Webhooks, que registra o endereço na Payload.

Como as peças se encaixam

Payload ──(mensagem webhook)──▶ seu site público do Salesforce ──▶ REDA Pay ──▶ Pay Transaction atualizada
                                  /services/apexrest/…              (processada pelo usuário Automated Process)

A Payload precisa de um endereço que possa chamar sem fazer login. No Salesforce, isso é um site: um endereço da web público da sua organização, usado aqui apenas como caixa de correio para as mensagens da Payload. O REDA Pay informa à Payload o endereço completo; você só fornece o endereço base do site.

Parte 1: criar o site público

Se a sua organização já tem um site do Salesforce usado para integrações, você pode reutilizá-lo e passar para a Parte 2. Caso contrário:

1. Abra a Configuração, digite Sites na caixa Busca rápida e clique em Sites, em Interface do usuário → Sites e domínios.
2. Se você nunca criou um site, registre primeiro um domínio: informe um nome, clique em Verificar disponibilidade, aceite os termos e clique em Registrar meu domínio do Salesforce Site. O domínio tem a forma yourcompany.my.salesforce-sites.com.
3. Clique em Novo.
4. Preencha Rótulo do site (por exemplo, Payment Callbacks), Nome do site (preenchido automaticamente), Endereço padrão da web (um caminho curto como rpay, que passa a fazer parte do endereço) e Home page ativa do site: clique no seletor e escolha qualquer página, por exemplo UnderConstruction. Ninguém vai visitar essa página.
5. Marque Ativo e clique em Salvar.

Anote o endereço completo do site que aparece em URL do site, por exemplo https://yourcompany.my.salesforce-sites.com/rpay.

A página de detalhes do site dos callbacks de pagamento (chamado REDA Payload nesta organização de exemplo): Rótulo e Nome do site, Ativo marcado, login não permitido, as páginas iniciais e o botão Configurações de acesso público

Um site usado só para webhooks. A URL do site dele é o que vai no Pay Profile.

Parte 2: dar acesso ao usuário convidado do site

Todo site tem um usuário convidado, a identidade que o Salesforce usa para os visitantes que não fizeram login. As mensagens da Payload chegam como esse usuário, então ele precisa poder executar a classe do REDA Pay que as recebe.

1. Na página de detalhes do site, clique em Configurações de acesso público. Abre-se o perfil do usuário convidado.
2. Localize Acesso à classe do Apex ativado (na interface de perfil aprimorada, Acesso à classe do Apex) e clique em Editar.
3. Mova rpay.PayloadCallback da lista de disponíveis para a de habilitadas e clique em Salvar. O usuário convidado não precisa de mais nada: essa classe apenas repassa a mensagem ao REDA Pay.

A seção Acesso à classe do Apex do perfil do usuário convidado do site (interface de perfil aprimorada) com rpay.PayloadCallback

O usuário convidado precisa exatamente desta classe. Ela recebe a mensagem da Payload e a entrega ao REDA Pay.

Parte 3: colocar o endereço do site no Pay Profile

1. Abra o aplicativo REDA Pay → Pay Profiles → seu perfil → Editar.
2. Em Webhook API Base URL, cole o endereço do site da Parte 1, incluindo https:// e o caminho, por exemplo https://yourcompany.my.salesforce-sites.com/rpay.
3. Clique em Salvar.

O REDA Pay acrescenta o restante do endereço sozinho. Você nunca digita o endereço completo do webhook.

Parte 4: dar acesso ao usuário Automated Process

Quando chega uma mensagem, o Salesforce a entrega a um usuário de sistema integrado chamado Automated Process (o Salesforce em português o mostra como Processo automático). Esse usuário faz o trabalho: lê a mensagem, encontra a Pay Transaction, pede à Payload o status mais recente e atualiza o registro. Ele não tem acesso aos registros do REDA Pay até que você o conceda, e não aparece na lista normal de usuários, por isso o acesso é concedido com um script curto.

1. Abra Configuração → Conjuntos de permissões, abra o REDA Pay - Admin User e clique em Clonar. Dê à cópia o nome REDA Pay - Automated Process e clique em Salvar.
2. Copie o Id da cópia na barra de endereços (os 18 caracteres depois de /lightning/setup/PermSets/, ou os 15 caracteres depois de id=).
3. Abra a Developer Console (console do desenvolvedor) pelo menu da engrenagem e depois Debug → Open Execute Anonymous Window (a janela para executar código anônimo); a Developer Console mostra os menus em inglês. Cole a linha abaixo com o seu Id e clique em Execute:

insert new PermissionSetAssignment(
    AssigneeId = [SELECT Id FROM User WHERE Alias = 'autoproc' LIMIT 1].Id,
    PermissionSetId = '0PS000000000000AAA'   // o Id do seu conjunto de permissões REDA Pay - Automated Process
);

A janela informa que a execução foi bem-sucedida. Se informar que a atribuição já existe, a etapa já tinha sido feita.

Parte 5: registrar os webhooks na Payload

1. No Pay Profile, clique em Setup Webhooks.
2. Leia a caixa de diálogo: "System will delete all the existng webhooks and create new webhook setup." (o sistema excluirá todos os webhooks existentes e criará uma nova configuração).
3. Clique em Setup Webhooks. Aguarde a mensagem "Webhook setup created successfully." e feche a caixa de diálogo.
4. Abra a guia Webhook Setup do perfil. Ela lista dez registros Pay Profile Webhook, um por evento: payment, processed, authorized, credit, refund, reversal, void, decline, deposit e reject. Cada um mostra o Webhook Id atribuído pela Payload e a Webhook URL registrada pelo REDA Pay. O campo Webhook Setup Datetime [Payload] do perfil fica preenchido.

A guia Webhook Setup de um Pay Profile com dez Pay Profile Webhooks (payment, processed, authorized, credit, refund, reversal, void, decline, deposit, reject) e as colunas Webhook Id e Webhook URL

Dez webhooks, um por evento da Payload. Se aparecerem menos, o registro falhou no meio: corrija a causa e execute o Setup Webhooks de novo.

Execute o Setup Webhooks de novo sempre que mudar a Webhook API Base URL ou substituir a chave de API.

Verificar se funciona

Faça um pagamento de teste pequeno (consulte Receber um pagamento) e abra a Pay Transaction dele. Em poucos minutos, os campos Status, Status Code e Funding Status se atualizam sem que ninguém pressione Sync Transaction. Em um pagamento bancário, o status de liquidação passa de pending para batched quando a Payload o inclui em um lote, e mais tarde um depósito na sua conta bancária cria uma Statement Activity; consulte Conciliar depósitos e repasses.

Se nada se atualizar, verifique nesta ordem:

O que as mensagens contêm

Uma mensagem só informa ao REDA Pay qual transação mudou. O REDA Pay então pede à Payload o estado atual dessa transação e guarda a resposta, então o registro sempre reflete a Payload, não a mensagem. Mensagens sobre transações que o Salesforce nunca viu são ignoradas. As mensagens de depósito e de retirada criam ou atualizam uma Statement Activity.

Erros comuns a evitar

Perguntas frequentes

O que vem a seguir

• Como os status dos pagamentos se mantêm atualizados: o que cada evento faz com os registros.
• Ativar a recuperação de pagamentos com falha: o trabalho que cobre os pagamentos cujo resultado nunca chegou.