Construindo uma integração na nuvem

Com uma integração que usa comunicações na nuvem, sua caixa registradora e seu terminal se comunicam pela Internet.

Para iniciar um pagamento:

1. Sua caixa registradora faz uma solicitação na API para a plataforma de pagamentos Adyen.
2. A plataforma de pagamentos da Adyen direciona a solicitação para o seu terminal, para iniciar o pagamento no dispositivo.
3. O terminal envia a transação para a plataforma de pagamentos da Adyen para processamento.
4. Você recebe o resultado da transação. Você pode criar uma integração que receba essas informações de forma:
   • Síncrona: quando sua caixa registradora faz uma solicitação na API, ela mantém a conexão aberta até que o resultado da transação seja conhecido.
   • Assíncrona: sua caixa registradora faz uma solicitação na API e fecha a conexão. Depois que a transação é processada, o resultado da transação é recebido em uma notificação.

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

1. Configurar sua rede.
2. Instalar uma biblioteca de API (opcional) .
3. Criar seu fluxo de pagamento.
4. Aprender a lidar com problemas de rede.

Etapa 1: Configurar sua rede

Para que sua caixa registradora possa se conectar à Adyen, 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 de 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, pois eles podem mudar com o tempo. Não compartilhamos publicamente uma lista de nossos endereços IP.

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

Etapa 2: Instalar uma biblioteca de API (opcional)

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

• • Está conectada a sistemas de pacotes gerenciados (Composer, Gradle, Maven, npm, NuGet, PyPi, RubyGems) e, portanto, é fácil de incluir em seu projeto.
• Usa a versão mais recente da API.
• Constrói os pontos de e 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 cliente HTTP interno, para que você não precise criar o seu próprio.

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

• C#
• Java
• PHP

Etapa 3: Crie seu fluxo de pagamento

Ao criar seu fluxo de pagamento, você também deve considerar a forma como deseja receber o resultado dos pagamentos:

• Síncron, como uma resposta da API.
• Assíncrona, a partir de uma notificação de exibição que é enviada para o servidor webhook.

Recebendo um resultado síncrono

Se você deseja receber o resultado de suas transações de forma síncrona, sua caixa registradora precisa fazer solicitações HTTPS para o terminal:

• https://terminal-api-test.adyen.com/sync

Essa solicitação deve usar um tempo limite estendido de mais de 150 segundos. Durante esse período, a conexão é mantida ativa e uma resposta síncrona se seguirá.

Além do resultado do pagamento, a resposta síncrona da API fornece

• 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 cliente.

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

Ao criar seu fluxo de pagamento, você também deve considerar se deseja exibir notificações em sua caixa registradora. Isso é opcional se você estiver recebendo uma resposta de forma síncrona, mas mantenha a equipe da sua loja atualizada com o andamento da transação. Para configurar as notificações, você precisará de um servidor HTTPS webhook. Para obter mais informações sobre como configurar notificações de exibição, consulte nossa documentação de notificações de exibição.

Recebendo um resultado assíncrono

Se você não desejar usar um tempo limite prolongado de 150 segundos, poderá receber a resposta de forma assíncrona. Nesse caso, sua caixa registradora precisa fazer uma solicitação HTTPS para o terminal:

• https://terminal-api-test.adyen.com/async

Isso retornará uma resposta 200 HTTP OK, confirmando que recebemos sua solicitação.

Para receber uma resposta assíncrona, será necessário configurar um servidor HTTPS webhook para que você possa receber notificações de exibição em sua caixa registradora. Isso mantém a equipe da loja informada sobre o andamento da transação, incluindo o resultado.

Além do resultado do pagamento, as notificações de exibição assíncronas fornecem:

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

Etapa 4: Resolver problemas de rede

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

As solicitações de pagamento tem um limite de 150 segundos. Se você não receber uma resposta de pagamento (ou 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.

Agora que você já sabe como criar sua integração, pode aprender sobre o básico da nossa API de terminais.