Coletar informações

Além de efetuar pagamentos, os terminais da Adyen podem solicitar informações ao seu cliente ou equipe. Isso permite que você colete o endereço de e-mail do cliente, por exemplo, ou realize uma pesquisa. O fluxo de comunicação é entre sua caixa registradora e o terminal e não envolve o back-end da Adyen. Você precisa processar a informação coletada com sua própria lógica de negócios.

Existem vários tipos de InputRequest:

• Confirmação - Mostre algumas informações e peça ao cliente para confirmar se concorda.
• Assinatura - Mostre algumas informações e peça ao cliente que confirme fornecendo sua assinatura.
• Menu - Mostre uma pergunta de múltipla escolha e deixe o usuário selecionar uma das respostas. Você pode usar isso para pesquisas do NPS, listas de pedidos e outros.
• Numérico - Você normalmente usa isso para pedir ao cliente o número de telefone. Outro exemplo é um fluxo de pagamento na mesa em que você solicita à sua equipe o número da mesa.
• Texto - Você normalmente usa isso para pedir ao cliente o endereço de e-mail.

Para cada tipo de entrada, fornecemos elementos predefinidos para exibição no visor do terminal e campos que você precisa preencher com seu próprio texto. O usuário digita uma resposta na tela ou nos botões do teclado do terminal

Coletar informações do usuário

Esse é o procedimento geral para fazer uma pergunta ao cliente ou sua equipe e coletar a resposta. Consulte os tipos de entrada para detalhes específicos.

1. Faça uma solicitação POST para um endpoint da API de terminais, especificando:

   • Objeto MessageHeader: Segue a estrutra da MessageHeader padrão, explicada nos fundamentos da API de terminais:

     • ProtocolVersion: 3.0
     • MessageClass: Device
     • MessageCategory: Input
     • MessageType: Request
     • SaleID: Seu ID exclusivo para a caixa registradora.
     • ServiceID: 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: ID exclusivo do terminal. Isso indica para qual terminal o pagamento será roteado.

   • InputRequest.DisplayOutput: Esta parte do corpo da solicitação define o que é mostrado no terminal:

     • Device: CustomerDisplay

     • InfoQualify: Display

     • OutputContent.OutputFormat: Text.

     • OutputContent.PredefinedContent.ReferenceID: TO conjunto de elementos predefinidos que você deseja usar:

       • GetConfirmation: elementos predefinidos para solicitar confirmação.
       • GetSignature: elementos predefinidos para solicitar uma assinatura.
       • MenuButtons: elementos predefinidos para permitir que o usuário selecione uma resposta.
       • GetDigit: elementos predefinidos para solicitar uma informação numérica.

       • GetText: elementos predefinidos para solicitar uma informação de texto.

     • OutputContent.OutputText: Uma matriz de um ou mais campos Text contendo seu próprio texto para mostrar no terminal. Consulte os tipos de entrada abaixo para aprender como usar esses campos.

   • InputRequest.InputData: Esta parte do corpo da solicitação lida com a informação do usuário:

     • Device: CustomerInput.

     • InfoQualify: Input.

     • InputCommand: Comando para lidar com o tipo de informação do usuário:

       • GetConfirmation: solicite confirmação ou assinatura.
       • GetMenuEntry: peça para selecionar uma resposta para uma pergunta de múltipla escolha.
       • DigitString: solicita informação numérica.

       • TextString: solicita informação de texto.

     • MaxInputTime: Tempo limite em segundos. Este é o tempo que o usuário obtém para concluir sua resposta.

   O exemplo a seguir mostra os campos comuns para todos os tipos de informação.

   JSONJavaJSONJava

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
        "SaleToPOIRequest": {
          "MessageHeader": {
            "ProtocolVersion": "3.0",
            "MessageClass": "Device",
            "MessageCategory": "Input",
            "MessageType": "Request",
            "ServiceID": "0207111104",
            "SaleID": "POSSystemID12345",
            "POIID": "V400m-324688179"
          },
          "InputRequest": {
            "DisplayOutput": {
              "Device": "CustomerDisplay",
              "InfoQualify": "Display",
              "OutputContent": {
                "OutputFormat": "Text",
                "PredefinedContent": {
                  "ReferenceID": "PREDEFINED_ELEMENTS_ID"
                },
                "OutputText": [
                  {"Text": "Your own text"}
                ]
              }
            },
            "InputData": {
              "Device": "CustomerInput",
              "InfoQualify": "Input",
              "InputCommand": "INPUT_TYPE",
              "MaxInputTime": 30
            }
          }
        }
      }

   Alguns tipos de informações requerem campos adicionais ou valores específicos. Consulte os tipos de entrada abaixo.

2. Aguarde o usuário fornecer a informação solicitada usando os botões na tela ou o teclado do terminal.

   A informação fornecida pelo cliente ou sua equipe não é validada em um formato.

   Na resposta, o InputResult mostra se o usuário concordou ou discordou, forneceu uma assinatura, selecionou uma resposta para a pergunta de múltipla escolha, inseriu números ou texto ou recusou-se a fornecer informações.
   Se o pedido expirar, a resposta conterá um EventNotification com os EventDetails: message=Did+not+receive+a+response+from+the+POI.

3. Passe os dados relevantes do InputResult para o seu sistema para validação e uso posterior.

Confirmação

Em um InputRequest solicitando que o cliente confirme alguma informação, é necessário especificar os campos comuns para coletar as informações do usuário, bem como os seguintes valores e campos específicos:

• DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetConfirmation.

• DisplayOutput.OutputContent.OutputText: Uma matriz de quatro campos Text contendo seu próprio texto para mostrar no terminal.

  1. O primeiro campo Text é o título.
  2. O segundo campo Text representa um texto adicional que pode ser longo e é rolável.
  3. O terceiro campo Text é o título do botão 'decline' à esquerda.

  4. O quarto campo Text é o título do botão 'agree' à direita.

• InputData.InputCommand: GetConfirmation

O exemplo a seguir pede ao cliente para confirmar que concorda.

{
    "SaleToPOIRequest":{
        "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Device",
            "MessageCategory":"Input",
            "MessageType":"Request",
            "ServiceID":"0207111104",
            "SaleID":"POSSystemID12345",
            "POIID":"V400m-324688179"
        },
        "InputRequest":{
            "DisplayOutput":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "OutputContent":{
                    "OutputFormat":"Text",
                    "PredefinedContent":{
                        "ReferenceID":"GetConfirmation"
                    },
                    "OutputText":[
                        {
                            "Text":"Terms & Conditions"
                        },
                        {
                            "Text":"Do you accept our Terms and Conditions? The full text is available on our website."
                        },
                        {
                            "Text":"Decline"
                        },
                        {
                            "Text":"Agree"
                        }
                    ]
                }
            },
            "InputData":{
                "Device":"CustomerInput",
                "InfoQualify":"Input",
                "InputCommand":"GetConfirmation",
                "MaxInputTime":30
            }
        }
    }
}

Na resposta, ConfirmedFlag: true indica que o cliente tocou no botão 'agree' à direita ou pressionou para confirmar o seu acordo. ConfirmedFlag: false significa que o cliente tocou no botão 'decline' à esquerda ou pressionou .

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560867383%22%20%7d"
        },
        "Input": {
          "ConfirmedFlag": true,
          "InputCommand": "GetConfirmation"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

Assinatura

Em um InputRequest solicitando que o cliente assine algo e confirme, é necessário especificar os campos comuns para coletar a informação do cliente bem como os seguintes valores e campos específicos:

• DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetSignature. Além do texto que você especificar, o terminal mostrará uma caixa de entrada para o cliente desenhar sua assinatura.

• DisplayOutput.OutputContent.OutputText: An array of four Text fields containing your own text to show on the terminal.

  1. O primeiro campo Text é o título.
  2. O segundo campo Text contém informações adicionais.
  3. O terceiro campo Text é o título do botão 'decline' à esquerda.

  4. O quarto campo Text é o título do botão 'agree' à direita.

• InputData.InputCommand: GetConfirmation

O exemplo a seguir solicita a assinatura do cliente.

{
    "SaleToPOIRequest":{
        "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Device",
            "MessageCategory":"Input",
            "MessageType":"Request",
            "ServiceID":"0207111104",
            "SaleID":"POSSystemID12345",
            "POIID":"V400m-324688179"
        },
        "InputRequest":{
            "DisplayOutput":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "OutputContent":{
                    "OutputFormat":"Text",
                    "PredefinedContent":{
                        "ReferenceID":"GetSignature"
                    },
                    "OutputText":[
                        {
                            "Text":"Please sign"
                        },
                        {
                            "Text":"Do you accept the Delivery Waver form?"
                        }
                    ]
                }
            },
            "InputData":{
                "Device":"CustomerInput",
                "InfoQualify":"Input",
                "InputCommand":"GetConfirmation",
                "MaxInputTime":30
            }
        }
    }
}

Na resposta, o AdditionalResponse contém a assinatura fornecida pelo cliente. ConfirmedFlag: true indica que o cliente tocou no botão 'agree' à direita ou pressionou para confirmar o acordo. ConfirmedFlag: false significa que o cliente tocou no botão 'decline' à esquerda ou pressionou .

Seleção de menu

Em um InputRequest solicitando ao cliente que responda a uma pergunta de múltipla escolha, é necessário especificar os campos comuns para coletar informações do cliente bem como os seguintes valores e campos específicos:

• DisplayOutput.OutputContent.PredefinedContent.ReferenceID: MenuButtons. O terminal mostra as respostas para escolher como uma lista rolável de caixas que o usuário pode tocar para selecionar.

• DisplayOutput.OutputContent.OutputText: Uma matriz de apenas um campo Text contendo seu próprio texto para mostrar no terminal. Use isso para especificar a pergunta.

• MenuEntry: Uma matriz de até 15 itens representando as respostas para você escolher. Cada resposta tem:

  • OutputFormat: Text

  • OutputText: uma matriz de três campos Text com seu próprio texto que juntos formam a resposta.
    O primeiro campo Text será exibido em negrito. Use uma sequência vazia para os campos Text não utilizados.
    Por exemplo, você pode escrever uma resposta abreviada no primeiro campo, a resposta longa no segundo campo e não usar o terceiro campo. Ou você pode usar os três campos para o nome, descrição e rótulo do artigo.

• InputData.InputCommand: GetMenuEntry

O exemplo a seguir solicita que o cliente responda a uma pergunta da pesquisa.

Na resposta, a matriz MenuEntryNumber indica a resposta que o usuário selecionou. Por exemplo, se a terceira resposta foi selecionada, o terceiro item na matriz é 1 e todos os outros itens da matriz são 0.
Se o usuário se recusou a responder (pressionado ), o InputResult possui uma Response.Result: Failure e Response.ErrorCondition: Cancel.

Entrada numérica

Em uma InputRequest solicitando que o cliente insira numerais, é necessário especificar os campos comuns para coletar informações do cliente bem como os seguintes valores e campos específicos:

• DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetDigit. Além do texto que você especificar, o terminal mostrará uma instrução sobre como confirmar a informação.
• DisplayOutput.OutputContent.OutputText: Uma matriz de apenas um campo Text contendo seu próprio texto para mostrar no terminal.
• InputData.InputCommand: DigitString
• InputData.DefaultInputString: Espaço reservado para a caixa de entrada, para que o usuário saiba qual formato de informação você está esperando.

O exemplo a seguir mostra uma solicitação de número de telefone ao cliente.

Na resposta, o campo DigitInput contém os numerais que o usuário digitou. Se o usuário se recusou a forncer a informação (pressionando ), o InputResult possui Response.Result: Failure, Response.ErrorCondition: Cancel, e um campo DigitInput vazio.

Entrada de texto

Em uma InputRequest solicitando que o usuário insira texto, é necessário especificar os campos comuns para coletar informações do cliente, bem como os seguintes valores e campos específicos:

• DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetText. Além do texto que você especificar, o terminal mostrará uma instrução sobre como confirmar a informação.
• DisplayOutput.OutputContent.OutputText: Uma matriz de apenas um campo Text contendo seu próprio texto para mostrar no terminal.
• InputData.InputCommand: TextString
• InputData.DefaultInputString: Espaço reservado para texto da caixa de entrada, para que o usuário saiba qual formato de informação você está esperando

O exemplo a seguir solicita ao cliente seu endereço de e-mail

Na resposta, o campo TextInput field contains the text that the user entered. Se o usuário se negou a fornecer a informação (pressionado ), o InputResult possui Response.Result: Failure, Response.ErrorCondition: Cancel, e um campo TextInput vazio.