> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://academy.zrupay.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Criar e gerir as Orquestrações # O que é uma orquestração? Uma orquestração é um fluxo de encaminhamento que decide qual conexão gere cada pagamento. Pode definir rotas diferentes segundo variáveis do pagamento, do cliente ou do cartão e adicionar conexões alternativas que entram se a principal falhar. Para saber mais sobre o que é a orquestração de pagamentos e para que serve, pode ler [este artigo do Academy](https://academy.zrupay.com/pt/article/o-que-e-um-orquestrador-de-pagamentos-hi8u2m/). # Antes de criar uma orquestração - Pode orquestrar três coisas distintas, conforme o trigger que escolher: **processadores de cartão** entre si, **financeiras** entre si, ou as **contas de um mesmo método de pagamento**. O que não pode fazer é encaminhar entre métodos diferentes, por exemplo passar de Bizum para PayPal. - As conexões que quiser usar têm de estar adicionadas e ativas em **Conexões**. Se não as tiver adicionado antes, não lhe aparecerão ao construir a orquestração. - Se vai orquestrar processadores de cartão, o processador não pode estar em modo de redirecionamento. Ao adicioná-lo em **Conexões**, certifique-se de que indica **"Sem redirecionamento"**. Se aparecer "com redirecionamento", o fluxo sai da Zru e não pode ser redirecionado para outro processador. # A lista de orquestrações Vá à secção **Orquestrações** do menu vertical da esquerda. Verá dois separadores: **Ativos** e **Desativadas**. - Pode alternar entre **vista de grelha** e **vista de lista** com o toggle do canto superior direito. - O menu **Todos os triggers** filtra a lista por trigger: Primeiro pagamento, Pagamento recorrente, Pagamento físico, Financiamento e Métodos alternativos. - Na vista de lista, o menu **"..."** do cabeçalho da tabela abre **Personalizar tabela**, onde escolhe e reordena as colunas. Aplica-se com **Aplicar alterações**. - O botão **Exportar CSV**, no cabeçalho ao lado de **Criar orquestração**, descarrega o conteúdo da lista. > ✋ **Exportar CSV** só aparece se a sua função tiver a permissão **Exportar** dentro de **Ambiente → Orquestrações**. Funciona igual à permissão de exportação das Conexões. # Como criar uma orquestração? - Vá à secção **Orquestrações** do menu vertical da esquerda. - Clique em **"Criar orquestração"**. - Abre-se o canvas do editor. Escreva o nome da orquestração no campo superior. - Escolha o **trigger** com que quer que esta orquestração seja disparada (ver secção seguinte). - Se escolher **Método alternativo**, o que lhe é pedido a seguir é o método de pagamento dentro do qual vai encaminhar (ver **O cartão Método**). - A partir daí, construa o fluxo adicionando blocos a partir do painel da direita. - Quando terminar, clique em **Publicar** para que as alterações entrem em vigor. > ⚠️ Ao publicar, as alterações são ativadas imediatamente em todos os Checkouts que usem essa orquestração. # O canvas: como funciona O editor de orquestrações é um **canvas visual**. Pode deslocar-se por ele arrastando com o rato e fazer zoom com o scroll do trackpad. Ao abrir uma orquestração entra em **vista de consulta**, com o fluxo desenhado mas sem poder mexer nele. No cabeçalho encontrará: - Toggle de ativação da orquestração. - Data da última atualização. - Nome da orquestração. - Contador de uso: quantos Checkouts estão a usar esta orquestração. - Botão **Editar**. Ao clicar em **Editar** passa à edição e o cabeçalho acrescenta: - Botões **desfazer** (↶) e **refazer** (↷). - Botão **Publicar**. > 🧐 Na vista de consulta não são oferecidos os menus de eliminar e o toggle de ativação não pode ser movido. O botão **Editar** só aparece se a sua função tiver permissão de edição. # Os triggers Ao criar uma orquestração, o primeiro passo é escolher o trigger, ou seja, que tipo de pagamento a vai ativar: - **Primeiro pagamento**: pagamentos iniciados pelo utilizador no momento do checkout. - **Pagamento recorrente**: cobranças recorrentes de autorizações ou subscrições. - **Pagamento físico**: pagamentos realizados num terminal físico (POS). - **Financiamento**: pagamentos resolvidos por uma financeira. Vai do trigger diretamente à ação e só lista financeiras. - **Método alternativo**: encaminha entre as contas de um mesmo método de pagamento, como Bizum, PayPal ou Klarna. > 🧐 O trigger determina que blocos e que conexões estão disponíveis no canvas. Por exemplo, com o trigger "Pagamento físico" só aparecem processadores que admitem pagamento presencial. > ✋ **Financiamento** e **Método alternativo** encaminham dentro de um mesmo método de pagamento, não entre processadores de cartão. Por isso não oferecem **Executar 3DS**, **Criar Network Token** nem cadeia de novas tentativas: apenas **Rota** e **Dividir tráfego** como utilidades, e **Concluir pagamento** ou **Rejeitar pagamento** como ações. Ao escolher **Concluir pagamento**, abre-se diretamente a seleção da conta, sem ecrã intermédio. As contas que lhe são oferecidas em cada bloco dependem do trigger: processadores com os triggers de cartão, financeiras com **Financiamento**, e conexões do método escolhido com **Método alternativo**. # O cartão Método Só aparece com o trigger **Método alternativo**. É um cartão próprio, chamado **Método**, situado entre o trigger e o primeiro passo do fluxo. - Ao criar a orquestração, o primeiro que lhe é pedido é escolher o método de pagamento. - Para o mudar, clique sobre o método no cartão: abre-se um painel com um campo de pesquisa e a lista de métodos disponíveis. - Para o retirar, use o menu **"..."** do cartão, que oferece a opção de eliminar. - A partir desse método, os blocos de ação só oferecem contas desse método. > ⚠️ Ao eliminar o cartão **Método**, o trigger e tudo o que tiver construído abaixo são também retirados. # Os blocos Uma vez escolhido o trigger, constrói o fluxo combinando blocos. Há dois tipos: de **utilidade** (organizam o fluxo) e de **ação** (executam algo sobre o pagamento). **Blocos de utilidade:** - **Rota**: divide o fluxo em ramos segundo condições. Funciona como um switch/case (ver secção seguinte). - **Dividir tráfego**: reparte o tráfego entre ramos em percentagens configuráveis. **Blocos de ação:** - **Concluir pagamento**: envia o pagamento a uma conexão para que o processe. Dentro do cartão, **+ Adicionar fallback** adiciona conexões de nova tentativa que entram se a anterior falhar. - **Rejeitar pagamento**: corta o fluxo e devolve o pagamento como recusado. Ao configurá-lo escolhe que erro quer que seja devolvido, e o cartão mostra o seu código e o seu texto. - **Executar 3DS**: lança a autenticação 3D Secure de forma independente do processador. - **Criar Network Token**: tokeniza o cartão com o esquema de rede antes de processar. Não todos os blocos estão disponíveis com todos os triggers: | Bloco | Primeiro pagamento | Pagamento recorrente | Pagamento físico | Financiamento | Método alternativo | |---|---|---|---|---|---| | Rota | ✅ | ✅ | ✅ | ✅ | ✅ | | Dividir tráfego | ✅ | ✅ | ✅ | ✅ | ✅ | | Concluir pagamento | ✅ | ✅ | ✅ | ✅ | ✅ | | Rejeitar pagamento | ✅ | ✅ | ✅ | ✅ | ✅ | | Executar 3DS | ✅ | ❌ | ❌ | ❌ | ❌ | | Criar Network Token | ✅ | ✅ | ❌ | ❌ | ❌ | # O bloco Rota O bloco Rota é o mais potente do editor. Não é um simples "se/senão": funciona como um **switch/case**, onde cada condição que adiciona é um **ramo de saída independente** com o seu próprio fluxo. Ao adicionar um bloco Rota verá: - **Condição 1, Condição 2...**: cada uma é um ramo. Pode adicionar tantas quantas precisar com o botão **"+ Adicionar condição"** e eliminar cada uma com o seu ícone de lixo. - **Todos os demais**: ramo de fallback que se executa quando nenhuma condição se cumpre. Está sempre presente e não pode ser eliminado. Dentro de cada condição define as variáveis que o pagamento tem de cumprir para entrar por esse ramo. Se adicionar várias variáveis à mesma condição, todas têm de se cumprir ao mesmo tempo (lógica AND). ## Variáveis disponíveis numa condição (35 no total) **Operação (12):** Preço, Moeda, Tipo, Idioma, Apenas autorizar, MOTO, Aprovação parcial, POS, Terminal POS, Pontuação de fraude, Recorrente de autorização, Recorrente de assinatura. **Cliente (9):** Variável personalizada, Tipo de dispositivo, Sistema operativo, Browser, País IP, Região IP, País, Região, E-mail. **Cartão (14):** Marca, Tipo, Nível, País de emissão, Banco emissor, Carteira utilizada, BIN, Network Token, Tentativa Network Token, Titular, Mês de expiração, Ano de expiração, Pré-pago, Empresa. > 🧐 A categoria **Cartão** é exclusiva das orquestrações. Os dados do cartão só são conhecidos no momento de processar o pagamento, não antes, e por isso esta categoria não está disponível nos Checkouts. A **Pontuação de fraude** é também exclusiva das orquestrações pela mesma razão. As orquestrações de **Financiamento** e **Método alternativo** também não oferecem as variáveis de Cartão: resolvem num único método de pagamento e não há cartão para avaliar. # Notas nos blocos Cada bloco pode ter uma **nota** interna que explica porque está configurado assim. Assim, qualquer pessoa da equipa percebe o fluxo sem ter de perguntar a quem o montou. - Para a escrever, abra o menu **"..."** do bloco e escolha **Adicionar nota**. Abre-se a janela **Notas**: escreva o texto e clique em **Guardar**. - Quando um bloco tem nota, aparece um botão no seu cabeçalho que a abre para leitura. Nessa mesma janela pode editá-la ou apagá-la com **Eliminar**. - Na vista de consulta a nota pode ser lida, mas não editada. > 🧐 As notas são guardadas assim que clica em **Guardar**, sem necessidade de publicar a orquestração, e não são afetadas por desfazer/refazer. A única exceção é um bloco acabado de adicionar e ainda não publicado: a sua nota é guardada ao publicar. > 🧐 É uma nota interna: não afeta o encaminhamento nem aparece no checkout. # Configuração de uma conexão dentro de um bloco Para configurar uma conexão que já está num bloco, faça **clique direto** sobre ela. Abre-se um painel à direita, e o que contém depende do bloco e do trigger. Em todos os casos o cabeçalho do painel mostra a conexão com um botão **Alterar** para a substituir, e um botão **Guardar** em baixo. Com **Concluir pagamento** e um trigger de cartão, o painel chama-se **"Configuração do processador"** e traz as quatro secções que verá a seguir. Com **Financiamento** só lhe permite mudar a conexão: não há 3D Secure, nem Network Token, nem condição geral, nem conexões secundárias, porque não se aplicam. Em **Executar 3DS** o painel tem o nome do bloco e também só lhe permite mudar a conexão. ## Condição geral Permite que essa conexão só seja usada se se cumprirem certas condições (mesmas variáveis: Operação 12 + Cliente 9 + Cartão 14). Quando não há nenhuma, a secção mostra **"Sem condição"**, e adicionam-se com **+ Adicionar condição**. Se não adicionar nenhuma condição, a conexão será sempre executada. ## Conexões secundárias Permite definir conexões alternativas do mesmo processador que serão usadas em vez da principal segundo certas condições. Adicionam-se com **+ Adicionar conexão**. > ✋ Só pode adicionar conexões **do mesmo processador** que a principal. Por exemplo, se a principal é Adyen, as secundárias têm também de ser conexões de Adyen. Isto é útil quando tem várias contas do mesmo processador para mercados distintos (Europa, LATAM, EUA) e quer usar a conta correta segundo `País IP` ou `Moeda`, sem necessidade de criar blocos separados. ## 3D Secure Só disponível no bloco **Concluir pagamento**. Escolha como quer aplicar a autenticação 3DS nesse processador: - **Agnóstico**: usa a informação do 3DS que já foi executado num bloco anterior ("Executar 3DS") e envia-a ao processador, sem voltar a solicitar autenticação. - **Processador**: aplica o 3DS seguindo a decisão do processador e do banco emissor, segundo as suas regras de risco. - **Processador (Forçar 3DS)**: força a autenticação 3DS em todas as operações, independentemente do valor ou do risco. - **Sem 3DS**: não aplica autenticação 3DS, embora o emissor a possa solicitar de qualquer forma. ## Network Token Só disponível no bloco **Concluir pagamento**. - **Utilizar se existir**: se o cartão tiver um network token, será usado em vez do PAN para processar o pagamento, melhorando a segurança e a taxa de aprovação. - **Não utilizar**: o pagamento é processado com os dados originais do cartão, mesmo que exista um network token disponível. # Como modificar uma orquestração? - Vá à secção **Orquestrações** do menu vertical da esquerda. - Clique na orquestração que quiser modificar. Abrirá em **vista de consulta**. - Clique em **Editar** para passar à edição. - Faça as alterações de que precisar. - Clique em **Publicar** para que entrem em vigor. > ⚠️ Ao publicar, as alterações são ativadas imediatamente em todos os Checkouts que usem essa orquestração. > 🧐 Se sair de uma orquestração com alterações não publicadas, o painel pergunta-lhe antes de sair. Ativar ou desativar a orquestração conta como alteração, pelo que também não se perde sem aviso. # Como ativar ou desativar uma orquestração? A partir do canvas, use o **toggle de ativação** do cabeçalho para ativar ou desativar a orquestração. Na vista de consulta o toggle não pode ser movido: entre primeiro em **Editar**. Também o pode fazer a partir da lista: na vista de lista, cada orquestração mostra o seu estado e pode geri-la a partir daí.