Fundamentos da API de terminais

A API de terminais permite efetuar pagamentos, realizar reembolsos, coletar informações do comprador e outras interações cliente-terminal.

Antes de efetuar qualquer pagamento no terminal, é importante entender como nossa API de terminais funciona e como as solicitações e respostas são estruturadas.

Aqui descreveremos:

• Os endpoints e autenticação.
• A estrutura da API.
• Como fazer pedidos.
• Como receber respostas.
• Como receber webhooks.
• Como lidar com erros.

Endpoints e autenticação

Os endpoits que você precisa usar e como você deve autenticar solicitações depende de como sua integração se conecta à plataforma de pagamentos Adyen:

• Comunicações locais.
• Comunicações em nuvem.

Comunicações locais

Se sua integração usa comunicações locais, todas as suas solicitações de API são feitas de uma caixa registradora diretamente no endereço IP de um terminal. Como alternativa, se você atribuir um nome de host ao seu terminal, poderá fazer solicitações ao nome do host terminal.

O terminal recebe solicitações POST /nexo na porta 8443. Por exemplo, se o seu terminal tiver o endereço IP 198.51.100.1 , você deverá fazer solicitações de API para: https://198.51.100.1:8443/nexo

Para autenticar suas solicitações, você precisará adicionar o certificado da Adyen à sua caixa registradora e criptografar suas mensagens.

Comunicações na nuvem

Se sua integração usa comunicações em nuvem, sua caixa registradora faz solicitações de API para a plataforma de pagamentos Adyen. Nossa plataforma encaminha a solicitação para o terminal.

O terminal que você precisará usar dependerá de duas coisas:

• Se sua integração receberá resultados de transação de forma síncrona ou assíncrona.
• Se você está fazendo transações de teste ou transações reais (live).

	Test endpoints - para todas as transações de teste
Resultado síncrono:	https://terminal-api-test.adyen.com/sync
Resultado assíncrono:	https://terminal-api-test.adyen.com/async

Quando você estiver pronto para entrar no ar, precisará mudar para um endpoint de transações reais (live) que esteja geograficamente mais próximo do local da sua loja.

	Live endpoints - Europa
Resultado síncrono:	https://terminal-api-live.adyen.com/sync
Resultado assíncrono:	https://terminal-api-live.adyen.com/async

	Live endpoints - Australia
Resultado síncrono:	https://terminal-api-live-au.adyen.com/sync
Resultado assíncrono:	https://terminal-api-live-au.adyen.com/async

	Live endpoints - USA
Resultado síncrono:	https://terminal-api-live-us.adyen.com/sync
Resultado assíncrono:	https://terminal-api-live-us.adyen.com/async

Para autenticar suas solicitações, você precisará de uma chave da API da Adyen. Se você ainda não possuir uma chave de API, poderá obtê-la aqui. Você precisará incluir essa chave de API no cabeçalho de cada solicitação na API de terminais.

Estrutura da API

Nossa API de terminais se comunica com o terminal usando mensagens JSON. Todas as solicitações e respostas têm a seguinte estrutura de cabeçalho-corpo:

• cabeçalho (header): identifica o tipo de transação, o terminal que está sendo usado e identificadores exclusivos de transação.
• corpo (body): um objeto de solicitação ou resposta, dependendo do tipo de transação. Por exemplo, quando você faz uma solicitação de pagamento, este é um objeto PaymentRequest quando você recebe uma resposta de pagamento, é um objeto PaymentResponse.

O cabeçalho e o corpo das respostas e solicitações da API de terminais são descritos em mais detalhes abaixo.

Solicitações

Cada solicitação da API de terminais que você faz está contida em um objeto SaletoPOIRequest object. Neste, será necessário fornecer um:

• ObjetoMessageHeader.
• Objeto do corpo da solicitaçã correspondente ao tipo de transação. Por exemplo, este é um objeto PaymentRequest correspondente ao tipo de transação. Por exemplo, este é um objeto InputRequest quando está solicitando a entrada do comprador.

Solicitar MessageHeader

Em cada solicitação MessageHeader, especifique o seguinte:

Nome	Requerido	Tipo	Descrição
ProtocolVersion	Sim	String	Versão da API do terminal da Adyen. A versão atual é 3.0
MessageClass	Sim	Enum	Quase sempre é Service, mas também pode ser Device ou Event. Vamos especificar qual MessageClass é necessário ao longo da documentação.
MessageCategory	Sim	Enum	O tipo de transação. Por exemplo, Payment para uma solicitação de pagamento. Vamos especificar qual MessageCategory é necessário ao longo da documentação.
MessageType	Sim	Enum	Sempre é Request.
SaleID	Sim	String	Seu ID exclusivo para sua caixa registradora.
ServiceID	Sim	String	Seu ID exclusivo para a tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor precisa ser exclusivo nas últimas 48 horas.
POIID	Sim	String	O ID exclusivo do terminal, no formato [modelo do dispositivo]-[número de série]. Por exemple, P400-123456789. Você pode encontrar o modelo do dispositivo e o número de série de um terminal na sua Customer Area, em In-person payments > Terminals. O número de série (ou s/n) também é impresso na parte inferior de cada terminal.

O exemplo abaixo mostra o cabeçalho que você forneceria se quisesse efetuar um pagamento.

{
  "SaleToPOIRequest":{
    "MessageHeader":{
      "ProtocolVersion":"3.0",
      "MessageClass":"Service",
      "MessageCategory":"Payment",
      "MessageType":"Request",
      "SaleID":"POSSystemID12345",
      "ServiceID":"0207111104",
      "POIID":"V400m-324688179"
    },
    "PaymentRequest":{...}
  }
}

Corpo da solicitação

Os valores que você precisa incluir no corpo da solicitação dependem do tipo de transação que você está fazendo. Fornecemos exemplos e informações de referência para cada tipo de transação em toda a documentação dos terminais.

Respostas

Cada resposta da API do terminal que você recebe está contida em um objeto SaleToPOIResponse e inclui um:

• Objeto MessageHeader: reproduz os valores do MessageHeader que você forneceu na solicitação da API.
• Objeto do corpo da resposta: corresponde ao tipo de solicitação de transação que você fez.
  Por exemplo, quando você faz um PaymentRequest você recebe um objeto PaymentResponse.

Resposta MessageHeader

O MessageHeader que você recebe na resposta reproduzirá os valores que você forneceu na solicitação. A única exceção é a MessageType, que será uma Resposta.

O exemplo a seguir mostra o cabeçalho que você receberia em resposta à solicitação de pagamento do exemplo fornecido acima .

{
  "SaleToPOIResponse":{
    "MessageHeader":{
      "ProtocolVersion":"3.0",                  // Echoed from request
      "MessageClass":"Service",                 // Echoed from request
      "MessageCategory":"Payment",              // Echoed from request
      "MessageType":"Response",                 // Response
      "SaleID":"POSSystemID12345",              // Echoed from request
      "ServiceID":"0207111104",                 // Echoed from request
      "POIID":"V400m-324688179"                 // Echoed from request
    },
    "PaymentResponse":{...}                     // Response body object
  }
}

Corpo de resposta

Os valores que você recebe no corpo da resposta dependem do tipo de solicitação de transação que você fez. Fornecemos exemplos e informações de referência para cada tipo de transação ao longo da documentação dos terminais.

O corpo da resposta geralmente inclui um identificador de transação, exclusivo e dados que você pode usar para gerar seus recibos.

Identificador de transação

Toda solicitação de API que cria uma transação ou interage com seu fluxo de dinheiro (como pagamento ou reembolso) retorna um identificador de transação exclusivo no POITransactionID.TransactionID:

Este identificador contém dois valores, separados por um ponto:

• Referência tender: valor exclusivo gerado pelo terminal para a transação.
• Referência PSP: valor exclusivo gerado pela plataforma de pagamentos Adyen para a transação.

  Se você estiver usando a Adyen para pagamentos on-line u comércio unificado, a Referência PSP será o equivalente a pspReference que você recebe pelas transações feitas on-line.

Você deve armazenar cada identificador de transação que receber, você irá precisar deles para:

• Fazer um reembolso.
• Realizar um pagamento com os detalhes do cartão adquirido.
• Identificar a transação em sua Customer Area, ou nos relatórios gerados pela Adyen.

Identificadores de transação para pagamentos offline

Se sua integração usar comunicações locais, seus terminais poderão fazer transações store-and-foward e EMV offline. Quando você tem um problema de rede, um pagamento Aprovado gera apenas um identificador de transação com a referência Tender:

Assim que o terminal puder se conectar à Internet novamente, a plataforma de pagamentos da Adyen processará o pagamento e gerará uma referência PSP. A referência do PSP e a referência tender podem ser encontradas na sua Customer Area, e nos relatórios gerados pela Adyen.

Dados do recibo

Quando você faz uma transação como um pagamento, o resultado do pagamento contém um objeto PaymentReceipt. Você pode adicionar os pares de valores-chave desse objeto ao recibo que você imprime, exibe em tela ou envia por e-mail ao seu cliente.

Para mais informações, consulte a nossa documentação de recibos.

Recebendo webhooks

À medida que você realiza pagamentos e outras interações com sua integração, seu terminal gera notificações. Estes são webhooks formatados em JSON que podem ser enviados para terminais em sua caixa registradora e usados para informar a equipe da loja sobre eventos importantes.

Existem dois tipos de notificações que podem ser enviadas para sua caixa registradora:

• Notificações em display : informa a equipe da loja sobre eventos relacionados a uma transação, como indicar se o comprador está interagindo com o terminal ou indicar o resultado do pagamento.

  Se sua integração usar comunicações em nuvem com um resultado assíncrono, você precisará integrar notificações em display para receber o resultado de suas transações.

• Notificações de evento: informe a equipe da loja sobre a disponibilidade e o estado de um terminal, inclusive quando o terminal estiver iniciando a manutenção ou desligando.

Além disso, a Adyen pode enviar notificações de plataforma para o servidor de back office. Você pode usá-los para ajudar a automatizar processos de negócios, como relatórios e reconciliação, ou para manter o sistema de gerenciamento de pedidos (OMS) atualizado.

Lidando com erros

À medida que você se integra, você pode receber uma mensagem de erro na resposta da API. Para obter informações sobre esses erros e como resolvê-los, consulte Cenários de erros.

Se você não receber uma resposta a uma solicitação de API, sua conexão poderá ter caído após o envio da solicitação. Para obter mais informações sobre como lidar com esse cenário, consulte a verificação do status de uma transação.

---

Agora que você conhece os fundamentos da nossa API de terminais, você já pode começar a realizar pagamentos.