Introdução

Objetivo

• Realizar Transações de Pagamento: Com o APP iFood Pago, você poderá efetuar pagamentos usando diversos métodos de pagamento (Débito, Crédito, Pix, Voucher).
• Processar Estornos: Realizar estornos em transações quando necessário.
• Acompanhar as transações: Receber informações sobre o status das transações conforme eles ocorrem em seu aplicativo.

Como funciona

1. Iniciar uma transação a. Você deverá criar um deeplink com informações codificadas em Base64, como método de pagamento, valor da transação, ID e demais informações.b. A transação será capturada e processada pelo APP iFood Pago, que redirecionará para uma URL que você nos informará.
2. Processar um estorno a. Para realizar um estorno, você precisa gerar um link semelhante com o ID da transação a ser estornada e demais informações.b. O App do iFood Pago redirecionará para a URL que você fornecer, com o status da transação após completar o estorno.

Lista com Permissões Compatíveis com o Terminal

• Aplicativos que funcionam como "launchers" não são permitidos.
• Não é permitido usar a flag testOnly no arquivo AndroidManifest.xml.
• Não é permitido criar serviços de acessibilidade.
• O modo de depuração (debug) não está disponível nos terminais.
• Não há navegadores instalados nos terminais.
• Os terminais não têm Google Play Services instalados.
• Não é possível reverter para versões anteriores de um aplicativo; você pode apenas atualizá-lo ou desinstalá-lo.
• Prefira soluções que não usem WebView, mas o terminal é compatível com a versão 123.0.6312.0.

Compatibilidade do Aplicativo

Realizar venda

Chamada para o APP da Maquinona

https://portal.ifood.com.br/make-payment?content={conteudo_base64}

{
  "paymentMethod": "DEBIT", //STRING – DEBIT OR CREDIT OR PIX OR VOUCHER
  "value": 2000, //INTEIRO – VALOR EM CENTAVOS
  "transactionId": "", //STRING ID DA TRANSAÇÃO (PARA FINS DE CONTROLE)
  "tableId": "", //STRING NÚMERO DE MESA QUE ESTÁ TRANSACIONANDO
  "printReceipt": true, //BOOLEAN QUE DEFINE A IMPRESSÃO OU NÃO DO COMPROVANTE
  "urlToReturn": "", //NULLABLE
  "sendResultInSameIntent": false, //BOOLEAN QUE DEFINE SE O RETONRO PARA O APP SERÁ VIA UMA NOVA INTENT OU VIA INTENT RESULT
  "phoneNumber": null //NULLABLE
}

Descrição dos parâmetros

• paymentMethod: Método de pagamento que será processado. Valores possíveis: DEBIT, CREDIT, PIX, VOUCHER.
• value: Valor da transação em centavos. Exemplo: Para R$ 20,00, envie 2000.
• transactionId: ID da transação do seu sistema interno, retornado após a finalização do pagamento.
• tableId: Número da mesa que está realizando o pagamento. Este valor é opcional e retornado após a transação.
• printReceipt: Define se o comprovante será impresso pelo POS.
• urlToReturn: URL para onde o APP da Maquinona irá redirecionar após a transação, enviando as informações do resultado. Ex:
  • https://anota.ai/payment-result?result= ➔ Aqui é definido o deeplink que o APP da Maquinona irá chamar quando finalizar a transação. No exemplo acima, o dentro do result será enviado um JSON em Base64 com as informações definidas via contrato.
• sendResultInSameIntent: Define se o retorno para o APP que está chamando será via Intent Result.
• phoneNumber: O número de telefone do cliente é utilizado para atribuir um valor de cashback. Este valor é opcional.

Exemplo de chamada

https://portal.ifood.com.br/make-payment?content=eyAicGF5bWVudE1ldGhvZCI6ICJERUJJVCIsICJ2YWx1ZSI6IDIwMDAwLCAidHJhbnNhY3Rpb25JZCI6ICJ0cmFuc2FjdGlvbklkUmV0b3JuYWRvIiwgInRhYmxlSWQiOiAidGFibGVJZCIsICJwcmludFJlY2VpcHQiOiB0cnVlLCAidXJsVG9SZXR1cm4iOiAiaHR0cHM6Ly9hbm90YS5haS5jb20uYnIvcGF5bWVudC1yZXN1bHQ/cmVzdWx0PSIsICJzZW5kUmVzdWx0SW5TYW1lSW50ZW50IjogZmFsc2V9

{
  "paymentMethod": "DEBIT",
  "value": 20000,
  "transactionId": "transactionIdRetornado",
  "tableId": "tableId",
  "printReceipt": true,
  "urlToReturn": "https://anota.ai.com.br/payment-result?result=",
  "sendResultInSameIntent": false,
  "phoneNumber": "11976212083"
}

Retorno do APP da Maquinona

{
  "transactionIdAnotaAi": "", //STRING ID DA TRANSAÇÃO DO ANOTA AI
  "tableIdAnotaAi": "", //STRING NÚMERO DE MESA QUE ESTÁ TRANSACIONANDO
  "transactionIdAdyen": "", //nullable
  "status": "", //STRING - SUCCESS OR ERROR
  "deviceSerialNumber": "000158224211090",
  "cardBrand": "", //STRING - BANDEIRA DO CARTÃO UTILIZADO PARA REALIZAR O PAGAMENTO
  "errorReason": "", //STRING - RAZÃO DO POSSÍVEL ERRO DA TRANSAÇÃO
  "transactionDate": "09-06-2025",
  "transactionTime": "20:03:34",
  "authCode": "123456",
  "nsu": "S6281CZJ4MA3GCVA",
  "subsidyInformation": [
      {
          "subsidyType": "IFOOD",
          "discountInCents": 1500
      }
  ]
}

Descrição dos parâmetros de retorno

• transactionIdAnotaAi: ID da transação retornado do parâmetro transactionId.
• tableIdAnotaAi: Número da mesa retornado do parâmetro tableId.
• transactionIdAdyen: ID da transação processada na Adyen (opcional).
• status: Status da transação, podendo ser SUCCESS ou ERROR.
• deviceSerialNumber: Número de série do POS que realizou a transação.
• cardBrand: Bandeira do cartão utilizado na transação.
• errorReason: Razão do possível erro na transação.
• transactionDate: Data da transação no formato DD-MM-YYYY;
• transactionTime: Hora da transação no formato HH:MM:SS;
• authCode: Código de autorização do banco;
• nsu: Número Sequencial Único (NSU) da transação;
• subsidyInformation: Lista que identifica a origem do desconto e seu valor. Valores possíveis para subsidyType: IFOOD, MERCHANT ou null. Em um futuro próximo o valor total do desconto poderá ser dividido por mais de uma origem.

Exemplo de chamada

https://anota.ai/payment-result?result=eyJ0cmFuc2FjdGlvbklkQW5vdGFBaSI6InRyYW5zYWN0aW9uSWRBbm90YUFpIiwidGFibGVJZEFub3RhQWkiOiJ0YWJsZUlkQW5vdGFBaSIsInRyYW5zYWN0aW9uSWRBZHllbiI6IjFjNzRmMGU1LTNmNTctNGI4Ni05MGMxLTlkZjZmZmM4YmE3ZiIsInN0YXR1cyI6IlNVQ0NFU1MiLCAiZGV2aWNlU2VyaWFsTnVtYmVyIjogIjAwMDE1ODIyNDIxMTA5MCIsICJjYXJkQnJhbmQiOiAiTUMiLCAiZXJyb3JSZWFzb24iOiBudWxsfQ==

{
  "transactionIdAnotaAi": "transactionIdAnotaAi",
  "tableIdAnotaAi": "tableIdAnotaAi",
  "transactionIdAdyen": "1c74f0e5-3f57-4b86-90c1-2f6ffc8ba7f",
  "status": "SUCCESS",
  "deviceSerialNumber": "000158224211090",
  "cardBrand": "MC",
  "errorReason": null
}

Fluxo na Maquinona

1. O aplicativo do terceiro chama o deeplink do APP da Maquinona.
2. O APP da Maquinona processa a transação.
3. Após a transação, o APP da Maquinona redireciona para a URL especificada com o resultado da transação.

Realizar estorno

Chamada para o APP da Maquinona

https://portal.ifood.com.br/make-refund?content={conteudo_base64}

{
  "transactionIdAdyen": "125a0b07-160c-4365-b687-e3b8136851fd", //STRING
  "printReceipt": true, //BOOLEAN QUE DEFINE A IMPRESSÃO OU NÃO DO COMPROVANTE
  "urlToReturn": "https://anota.ai/refund-result?result=", //STRING
  "sendResultInSameIntent": false //BOOLEAN QUE DEFINE SE O RETONRO PARA O APP SERÁ VIA UMA NOVA INTENT OU VIA INTENT RESULT
}

Descrição dos parâmetros

• transactionIdAdyen: ID da transação processada pela Maquinona e retornada para o seu sistema ao final da ação de pagamentotransação de pagamento.
• printReceipt: Define se o comprovante será impresso pelo POS.
• urlToReturn: URL para onde o APP da Maquinona irá redirecionar após a transação, enviando as informações do resultado. Ex:
  • https://anota.ai/refund-result?result= → Aqui é definido o deeplink que o APP da Maquinona irá chamar quando finalizar o estorno. No exemplo acima, o dentro do result será enviado um JSON em Base64 com as informações definidas via contrato.
• sendResultInSameIntent: Define se o retorno para o APP que está chamando será via Intent Result.

Exemplo de chamada

https://portal.ifood.com.br/make-refund?content=eyJ0cmFuc2FjdGlvbklkQWR5ZW4iOiIxMjVhMGIwNy0xNjBjLTQzNjUtYjY4Ny1lM2I4MTM2ODUxZmQiLCJwcmludFJlY2VpcHQiOnRydWUsInVybFRvUmV0dXJuIjoiaHR0cHM6Ly9hbm90YS5haS9yZWZ1bmQtcmVzdWx0P3Jlc3VsdD0iLCAic2VuZFJlc3VsdEluU2FtZUludGVudCI6IGZhbHNlfQ==

{
  "transactionIdAdyen": "125a0b07-160c-4365-b687-e3b8136851fd",
  "printReceipt": true,
  "urlToReturn": "https://anota.ai/refund-result?result=",
  "sendResultInSameIntent": false
}

Retorno do APP da Maquinona

{
  "status": "", //STRING - SUCCESS OR ERROR
  "deviceSerialNumber": "000158224211090"
}

Descrição dos parâmetros de retorno

• status: Status da transação, podendo ser SUCCESS ou ERROR.
• deviceSerialNumber: Número de série do POS que realizou a transação.

Exemplo de retorno

https://anota.ai/refund-result?result=eyJzdGF0dXMiOiAiU1VDQ0VTUyIsICJkZXZpY2VTZXJpYWxOdW1iZXIiOiAiMDAwMTU4MjI0MjExMDkwIn0=

{
  "status": "SUCCESS",
  "deviceSerialNumber": "000158224211090"
}

Impressão local de arquivos

Chamada para o APP da Maquinona

https://portal.ifood.com.br/print-local?content={conteudo_base64}

{
  "integrationApp": "integrationApp", //STRING
  "filePath": "", //STRING
  "urlToReturn": "https://anota.ai/print-result?result=", //STRING
  "sendResultInSameIntent": false //BOOLEAN QUE DEFINE SE O RETONRO PARA O APP SERÁ VIA UMA NOVA INTENT OU VIA INTENT RESULT
}

Descrição dos parâmetros

• integrationApp: Nome da empresa/integrador que está chamando a Maquinona.
• urlToReturn: Endereço para onde o app da Maquinona redirecionará após concluir a impressão (não “estorno”). O retorno envia um payload no parâmetro result.
  • Ex.: https://anota.ai/print-result?result= → Aqui é definido o deeplink que o APP da Maquinona irá chamar quando finalizar o estorno. Formato do result: JSON Base64 URL-safe (sem +//, de preferência sem padding).
• sendResultInSameIntent: Define se o retorno para o APP que está chamando será via Intent Result.
• filePath: Path do arquivo que o APP da Maquinona irá abrir para poder fazer a impressão.

Exemplo de chamada para a Maquinona

1. Criar res/xml/file_paths.xml

<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Expõe a pasta de arquivos internos -->
    <files-path name="shared" path="." />
</paths>

2. Configurar FileProvider no AndroidManifest.xml

<application ...>
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="${applicationId}.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/file_paths" />
    </provider>
</application>

3. Criação do arquivo e chamada do deeplink

    private fun createFile(): File {
        val fileName = "fileToPrint.txt"
        val fileContent = "" //BASE64 DA IMAGEM QUE DEVERÁ SER IMPRESSA
        val file = File(requireContext().filesDir, "shared/$fileName")

        file.parentFile?.mkdirs()
        file.writeText(fileContent)
        return file
    }

    private fun createAndSendFile() {
        val file = createFile()
        val fileUri: Uri = FileProvider.getUriForFile(
            requireContext(),
            "${requireContext().packageName}.fileprovider",
            file
        )

        val content =  PrintFileLocalModel(
            urlToReturn = null,
            integrationApp = "Integradora", //NOME DE SUA INTEGRADORA
            sendResultInSameIntent = true,
            filePath = fileUri.toString()
        )

        val deeplink = Uri.parse("https://portal.ifood.com.br/print-local?content=$content")

        val intent = Intent(Intent.ACTION_SEND, deeplink).apply {
            putExtra(Intent.EXTRA_STREAM, fileUri)
            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
        }
        resultLauncher.launch(intent)
    }

Impressão de arquivos

1. Na primeira etapa haverá uma requisição para obter um token de autorização para que as impressões possam ser realizadas.
2. Na segunda etapa, deverá ser realizada uma chamada para nossa API onde deverá ser enviado o token de autorização junto com a imagem em base64 que poderá ser impressa.

Chamada para o APP da Maquinona - Obter Autorização

https://portal.ifood.com.br/print-file?content={conteudo_base64}

{
  "integrationApp": "integrationApp", //STRING
  "urlToReturn": "https://anota.ai/print-result?result=", //STRING
  "sendResultInSameIntent": false //BOOLEAN QUE DEFINE SE O RETONRO PARA O APP SERÁ VIA UMA NOVA INTENT OU VIA INTENT RESULT
}

Descrição dos parâmetros

• integrationApp: Nome da empresa que está fazendo a integração com a Maquinona.
• urlToReturn: URL para onde o APP da Maquinona irá redirecionar após a transação, enviando as informações do resultado. Ex:
  • https://anota.ai/print-result?result= → Aqui é definido o deeplink que o APP da Maquinona irá chamar quando finalizar o estorno. No exemplo acima, o dentro do result será enviado um JSON em Base64 com as informações definidas via contrato.
• sendResultInSameIntent: Define se o retorno para o APP que está chamando será via Intent Result.

Exemplo de chamada

https://portal.ifood.com.br/print-file?content=eyJpbnRlZ3JhdGlvbkFwcCI6IkFub3RhQWkiLCJ1cmxUb1JldHVybiI6Imh0dHBzOi8vYW5vdGEuYWkvcHJpbnQtYXV0aG9yaXphdGlvbj9yZXN1bHQ9IiwgInNlbmRSZXN1bHRJblNhbWVJbnRlbnQiOiBmYWxzZX0=

{
  "integrationApp": "AnotaAi",
  "urlToReturn": "https://anota.ai/refund-result?result=",
  "sendResultInSameIntent": false
}

Retorno do APP da Maquinona

{
  "status": "", //STRING - SUCCESS OR ERROR
  "hash": "token",
  "createAt": "2025-03-23 18:13:51.070184",
  "deviceSerialNumber": "000158224211090"
}

Descrição dos parâmetros de retorno

• status: Status da transação, podendo ser SUCCESS ou ERROR.
• hash: Token que será utilizado para realizar a impressão do arquivo na segunda etapa;
• createAt: Hora de criação do token em nossos servidores (Vale lembrar que temos um fuso +3h, em relação ao horário de Brasília);
• deviceSerialNumber: Número de série do POS que realizou a transação.

Exemplo de retorno

https://anota.ai/print-authorization?result=eyJzdGF0dXMiOiJTVUNDRVNTIiwiaGFzaCI6IjBmMDA2ZmIzNjRlMDY1NmExMDE4ZDMyZmRhZjQwYmMxOWMzOTZlYjE3YTE5ODc2NTAxZDcyNzExYzdlNGQxZjMiLCJjcmVhdGVBdCI6ICIyMDI1LTAzLTIzIDE4OjEzOjUxLjA3MDE4NCIsICJkZXZpY2VTZXJpYWxOdW1iZXIiOiIwMDAxNTgyMjQyMTEwOTAifQ==

{
  "status": "SUCCESS",
  "hash": "0f006fb364e0656a1018d32fdaf40bc19c396eb17a19876501d72711c7e4d1f3",
  "createAt": "2025-03-23 18:13:51.070184",
  "deviceSerialNumber": "000158224211090"
}

Chamada para API de Impressão

Request

POST:
https://movilepay-api.ifood.com.br/ifoodpay/mobile/api/v1/print/file

{
  "authorizationHash": "TOKEN", //STRING
  "contentBase64": "IMAGEM EM BASE 64" //STRING
}

Descrição dos parâmetros

• authorizationHash: Deverá ser utilizado o token obtido no passo anterior, onde o APP da Maquinona retornou;
• contentBase64: Imagem que deseja imprimir em Base64.
  • Importante: O tamanho máximo do conteúdo Base64 é de 256 KB. Caso este limite seja excedido, a API retornará um erro 413 Payload Too Large.
  • Vale ressaltar que a imagem deverá atender alguns requisitos da Adyen, quando a resolução como o padrão da imagem: Documentação sobre padrão de impressão da Adyen → Padrão de impressão da Adyen

Emulador para testes

1. Introdução
   • O que é o Emulador "Small Phone API 30":
     • O emulador "Small Phone API 30" é uma ferramenta que simula um dispositivo móvel com Android 11, usada para testar a aplicação em um ambiente próximo ao de produção. Ele permite que os desenvolvedores validem a funcionalidade e a compatibilidade do aplicativo antes de implantá-lo nos dispositivos físicos.
2. Por que usar o emulador
   • Benefícios para o Parceiro:
     • Testar a aplicação em um ambiente seguro e controlado.
     • Simular o comportamento do aplicativo como se estivesse rodando no dispositivo físico (smartPOS).
     • Detectar e corrigir problemas de compatibilidade e funcionalidade antecipadamente.
3. Download e instalação do Android Studio
   • Passo a passo para baixar o Android Studio:
     • Acesse o site oficial do Android Studio: Download Android Studio & App Tools - Android Developer
     • Faça o download da versão mais recente do Android Studio para o seu sistema operacional (Windows, macOS ou Linux).
     • Siga as instruções de instalação fornecidas no site para configurar o ambiente de desenvolvimento.
4. Configuração do emulador "Small Phone API 30"
   • Criando o dispositivo Virtual (AVD):
     • Abra o Android Studio e navegue até o "AVD Manager" (Ferramentas > Gerenciador de Dispositivos Virtuais).
     • Clique em "Create Virtual Device" e selecione um dispositivo com tela pequena, por exemplo, "Small Phone".
     • Configure o sistema operacional Android para API 30 (Android 11).
     • Ajuste as configurações, como a orientação (portrait) e resolução de tela, conforme as especificações recomendadas.
     • Clique em "Finish" para concluir a configuração do emulador.
5. Testando a aplicação no emulador
   • Passos para instalar o APK no emulador:
     • Inicie o emulador "Small Phone API 30" no Android Studio.
     • Arraste e solte o arquivo APK no emulador ou use a linha de comando para instalar o aplicativo.
     • Execute os testes e verifique o funcionamento conforme as diretrizes.
6. Orientações adicionais
   • Boas práticas para o uso do emulador:
     • Testar diferentes cenários de uso e comportamentos do aplicativo.
     • Manter o emulador atualizado com as últimas configurações e imagens de sistema.
   • Links úteis:
     • Documentação oficial do Android Studio:Develop for Android | Android Developers
     • Guia sobre como usar o AVD Manager:Create and manage virtual devices | Android Studio | Android Developers .
7. Suporte
   • Contato para Suporte Técnico:
     • Caso o parceiro encontre dificuldades para configurar ou usar o emulador, entre em contato com o time de suporte técnico através do e-mail integracaoifoodpago@ifood.com.br ou acesse o portal de ajuda.
   • Contato para Suporte Técnico:
     • Caso o parceiro encontre dificuldades para configurar ou usar o emulador, entre em contato com o time de suporte técnico através do e-mail integracaoifoodpago@ifood.com.br ou acesse o portal de ajuda.

FAQ

Checklist de segurança

1. WebView e execução de código

• WebView seguro: WebViews não devem permitir execução de JavaScript desnecessária (‘setJavaScriptEnable’), nem acesso universal a arquivos (‘allowFileAccessFromFileURLs’, ‘allowUniversalAccessFromFileUR’).
• Interface JavaScript: Não deve haver uso inseguro de addJavascriptInterface (addJavascriptInterface).
• Debug em WebView: WebView debugging deve estar desabilitado em produção (setWebContentsDebuggingEnabled).

Links de referência:

• Developer Android | WebView Native Bridges
• Developer Android | Carregamento de URI Inseguro

2. Permissões e exportação de componentes

• Componentes exportados: Activities, Services, BroadcastReceivers e ContentProviders não devem ser exportados sem necessidade (android:exported=\"true\").
• Permissões customizadas: Verifique se há permissões customizadas e se estão corretamente protegidas (ex: signature, signatureOrSystem) (<permission[\\s\\S]*android:protectionLevel=\")

Links de referência:

• Developer Android | android:exported
• Source Android | Signature Permission

3. Depuração e build

• Debuggable: O APK não deve estar com android:debuggable=\"true\".
• Build de produção: Certifique-se de que não há certificados de debug, nem APKs não assinados. (CN=Android Debug, META-INF/.\.RSA, META-INF/.\.DSA)

Links de referência:

• Developer Android | android:debuggable
• Developer Android | App Signing - Considerations

4. Armazenamento e dados sensíveis

• Backup: O backup deve estar desabilitado (android:allowBackup=\"false\").
• Dados sensíveis: Não deve haver dados sensíveis armazenados em texto claro, nem em áreas acessíveis por outros apps (SharedPreferences.*MODE).
• Banco de dados: Se usar banco de dados local, deve usar criptografia forte (ex: SQLite SQLiteDatabase\\.openOrCreateDatabase).

Links de referência:

• Developer Android | Backup Best Practices
• SQLite - Using The SQLite Encryption Extension

5. Comunicação com o APP principal

• Intents seguras: Toda comunicação via Intent deve ser explícita e, se possível, restrita por permissões. (Intent\\(.*\\))
• Validação de origem: O APK deve validar que as Intents vêm do app principal (verificar assinatura, package name, etc).
• Broadcasts: Não deve enviar/receber broadcasts sensíveis sem proteção.
• Developer Android | Insecure Broadcast Receiver
• Developer Android | Detectar Inicializações de intents Não Seguras

6. Criptografia e segurança de tráfego

• SSL/TLS: Toda comunicação de rede deve usar HTTPS com validação de certificado (sem aceitar todos os certificados).
• Sem algoritmos fracos: Não usar SHA1, MD5, IVs fracos, nem modos de criptografia inseguros (ex: ECB).
• Certificate Pinning: O app deve implementar certificate pinning para evitar ataques MITM. Use libs como OkHttp
• Sem logs sensíveis: Não logar dados sensíveis, nem informações de hardware ou transação.
• Não armazenar certificado PEM na pasta assets assets/.*\\.pem.

Links de referência:

• Developer Android | Cryptography
• Developer Android | Keystore
• Developer Android | Security SSL