Construindo uma integração local

Com uma integração que usa comunicação local, sua caixa registradora e seu terminal se comunicam através da rede local.

Para iniciar um pagamento:

1. Sua caixa registradora faz uma solicitação de API ao terminal para iniciar o pagamento no dispositivo.
2. O terminal encaminha a solicitação para a plataforma de pagamentos da Adyen para processamento.
3. Opcional: você recebe notificações na tela de sua caixa registradora para informar a equipe da loja sobre o andamento da transação e o resultado.
4. Você recebe o resultado da transação de forma síncrona.

Antes de começar a fazer transações utilizando uma integração local, você precisará:

1. Configurar sua rede.
2. Instalar uma biblioteca de API (opcional).
3. Proteger seus pedidos. Isso é opcional para pagamentos de teste, mas necessário para transações ativas.
4. Criar seu fluxo de pagamento .
5. Aprenda a lidar com problemas de rede.

Primeira etapa: Configurar sua rede

Para que sua caixa registradora possa se conectar diretamente ao terminal, você precisará:

1. Adicionar os domínios da Adyen à lista de permissões do seu firewall.
   Configure seu firewall para permitir o tráfego HTTPS de saída dos endereços IP de suas caixas registradoras e terminais para:

   • *.adyen.com
   • *.adyenpayments.com

   A lista de permissões deve ser baseada no nome DNS desses URLs. Seu firewall deve verificar dinamicamente se há atualizações de endereço IP, pelo menos a cada 60 segundos.

   Não codifique os endereços IP da Adyen, porque eles podem mudar com o tempo. Não compartilhamos publicamente uma lista de nossos endereços IP.

2. Abra as portas:
   • tcp/443 para a internet.
   • tcp/8443 na sua LAN.

Segunda etapa: Instalar uma biblioteca de API (Opcional)

Em nosso GitHub, fornecemos bibliotecas de API em diversas linguagens. A instalação não é necessária, mas você pode economizar tempo de desenvolvimento, porque uma biblioteca:

• Está conectada a sistemas de pacotes gerenciados (Gradle, Maven, npm, NuGet) e, portanto, fácil de incluir em seu projeto.
• Usa a versão mais recente da API.
• Constrói os endpoints TEST e LIVE corretos.
• Inclui todos os modelos de API de terminais para que você possa usá-los para criar solicitações e não precisar serializar solicitações para JSON.
• Envia a solicitação para a Adyen usando seu HTTP cliente interno, para que você não precise criar o seu próprio.
• Para comunicações locais, cuida de solicitações de criptografia e validação de certificados de terminal.

Para usar uma biblioteca, siga as instruções para uma dessas bibliotecas:

• C#
• Java

Terceira etapa: Proteja seus pedidos

Para proteger e autenticar solicitações entre sua caixa registradora e seu terminal, sua integração deve:

• Criptografar solicitações de transação: Isso impede que os invasores leiam as mensagens transmitidas entre sua caixa registradora e o terminal
• Validar certificados de terminal: Isso confirma que sua caixa registradora está se comunicando diretamente com um terminal da Adyen e não com um impostor.

Há duas maneiras de fazer isso:

• Realizar a implementação conforme descrito em nossa documentação sobre segurança de comunicações locais.
• Use uma de nossas bibliotecas.

Quarta etapa: Crie seu fluxo de pagamento

Os terminais Adyen recebem solicitações POST para /nexona na porta 8443. Por exemplo, se o seu terminal tem o endereço IP 198.51.100.1 você fará solicitações de API para: https://198.51.100.1:8443/nexo.

Quando você efetua um pagamento, o resultado é fornecido por meio de uma resposta de API síncrona. Para receber a resposta síncrona, sua caixa registradora precisa fazer solicitações HTTPS ao terminal usando um tempo limite prolongado de mais de 120 segundos. Durante esse período, a conexão é mantida ativa e uma resposta síncrona se seguirá.

Ao criar seu fluxo de pagamento, você também deve considerar:

• Como você deseja lidar com a resposta síncrona, incluindo como fornecer um recibo ao comprador.
• Se você deseja exibir mensagens em sua caixa registradora, para manter a equipe da loja atualizada com o andamento da transação.
• Instalar uma biblioteca API do lado do servidor (Opcional).

Como lidar com a resposta síncrona

A resposta da API síncrona inclui:

• O resultado do pagamento.
• Referência de transação exclusiva da Adyen.
• Sua referência de transação exclusiva.
• Dados que você pode usar para gerar um recibo. Você pode gerar um recibo impresso, exibi-lo na tela ou enviá-lo por e-mail ao comprador.

Para obter mais informações sobre a resposta da API síncrona, consulte nossos fundamentos da API do terminal.

Enquanto uma transação está sendo processada, podemos enviar webhooks para o seu servidor. Você pode usá-los para exibir notificações em sua caixa registradora.

Exibindo notificações em sua caixa registradora

Enquanto uma transação estiver sendo processada, você poderá exibir notificações em sua caixa registradora. Isso mantém a equipe da loja informada sobre o andamento da transação, por exemplo, se o comprador selecionou Conversão Dinâmica de Moeda ou terminou de inserir seu PIN (senha).

Para obter mais informações sobre como configurar notificações de exibição, consulte nossa documentação de notificações de exibição.

Quinta etapa: Lidar com problemas de rede

Para tornar sua integração mais resistente em caso de problemas de conexão, sua integração deve fazer automaticamente uma solicitação de status de transaçã quando não receber uma resposta de pagamento síncrona da Adyen.

O tempo limite das solicitações de pagamento é 120 segundos. Se você não receber uma resposta de pagamento (ou receber uma resposta indicando um tempo limite) após 150 segundos, sua integração deverá fazer automaticamente uma solicitação de status da transação.

A exibição do resultado da solicitação de status da transação na sua caixa registradora reduz o risco de que a equipe da loja tente desnecessariamente cancelar ou reembolsar a transação ou fazer uma transação duplicada.