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.

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:

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 (33 no total)

Operação (12): Preço, Moeda, Tipo, Idioma, Apenas autorizar, MOTO, Aprovação parcial, POS, Terminal POS, Pontuação de fraude, Autorizações recorrentes, Subscrições recorrentes.

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 (12): 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.

🧐 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.

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 10 + Cliente 9 + Cartão 12). 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í.

Actualizado em: 01/09/2026