Integração de Backend: Gerenciando Solicitações de SSO

Para autorizar operações e gerenciar o acesso de usuários, você deve expor um endpoint de API no seu sistema de backend. A plataforma Tap on Phone chama este endpoint para verificar as permissões de Single Sign-On (SSO) sempre que o seu aplicativo cliente solicitar uma operação sensível, como inicializar o terminal ou processar um estorno.

Este guia mostra como implementar e configurar este endpoint para receber, validar e responder a solicitações de SSO.

Passo 1: Configurar os requisitos do seu endpoint

O seu endpoint de backend deve atender a requisitos técnicos específicos para se comunicar com sucesso com a plataforma Tap on Phone:

Protocolo: O endpoint deve usar HTTPS.
Tempo de Resposta: O endpoint deve processar a solicitação e responder em um máximo de 5 segundos. Qualquer atraso além disso resulta em um erro de timeout.
IP Whitelisting: Você deve configurar o seu firewall ou proxy reverso para permitir solicitações de entrada dos seguintes endereços IP da plataforma Tap on Phone:
IPs do Ambiente de Teste: * 35.156.130.116
- 35.156.242.206
IPs do Ambiente de Produção:
- 3.124.56.20
- 63.176.190.170
- 18.158.202.149
- 18.197.125.190

Passo 2: Gerenciar a solicitação recebida

Quando um usuário aciona uma ação que requer autorização (como iniciar a InitActivity), a plataforma Tap on Phone envia uma solicitação POST para o seu endpoint.

Cabeçalhos

A plataforma passa o token de autenticação do usuário no cabeçalho da solicitação. Este token corresponde à string userToken que o seu aplicativo cliente passa durante a chamada do Intent.

X-Auth-Token: 1234567

Corpo da Solicitação

A solicitação inclui um corpo JSON detalhando a operação solicitada e seus metadados.

{
  "operation": "serviceInitialisation",
  "operationMetadata": {
    "ClientID": "4bac0922d476436697283b8238ba282b"
  }
}

operation: O tipo de operação que o usuário está tentando realizar. Os valores suportados incluem serviceInitialisation e refund.
operationMetadata: Contém metadados contextuais, incluindo o ClientID da sua organização.

Passo 3: Validar a solicitação

Ao receber a solicitação, o seu backend deve realizar os seguintes passos de validação:

Autenticar o usuário: Leia o cabeçalho X-Auth-Token e verifique se a sessão do usuário está ativa e válida dentro do seu sistema.
Autorizar a operação: Verifique o campo operation. Determine se o usuário autenticado tem as permissões necessárias para realizar esta ação específica (por exemplo, garantir que apenas usuários administradores possam realizar um estorno).

Passo 4: Retornar a resposta apropriada

Após validar a solicitação, você deve retornar uma resposta HTTP para instruir a plataforma Tap on Phone sobre como prosseguir.

Resposta Bem-sucedida

Se você aprovar a solicitação, retorne um código de status HTTP 200 OK com um payload JSON contendo os seguintes campos obrigatórios:

merchantId: O ID Tap to Pay (número inteiro) do estabelecimento comercial registrado na plataforma (obtido durante o processo de onboarding).
userId: O identificador único do usuário. Ele deve corresponder ao userId originalmente passado pelo seu aplicativo cliente no Intent.

{
  "merchantId": 19,
  "userId": "19"
}

Respostas com Erro

Se a solicitação não for autorizada ou encontrar um erro durante o processamento, o seu backend deve retornar um dos seguintes códigos de status HTTP padrão:

401 Unauthorized: Use isto se o X-Auth-Token for inválido, estiver expirado ou se o usuário não tiver as permissões necessárias para a operação solicitada.
405 Method Not Allowed: Use isto se o endpoint receber um método de solicitação diferente de POST.
500 Internal Server Error: Use isto se o seu backend encontrar um problema inesperado ao processar a validação.

Próximos Passos

Assim que o seu endpoint de SSO estiver ativo e processando corretamente as solicitações de autorização, você estará pronto para começar a iniciar intents a partir do seu aplicativo Android.

Prossiga para o Quick Start: Your First Initialization para inicializar a sessão do POS.