Boas vindas à área do desenvolvedor

Inicie sua jornada de integração com a maquinona.

Visão Geral da API

A API de integração da maquinona foi desenvolvida para permitir uma comunicação simples e eficiente entre aplicativos externos e equipamentos POS no ecossistema iFood. A integração é baseada em Deep Links e comunicação via JSON codificado em Base64, proporcionando uma solução robusta para processamento de pagamentos, estornos e autorizações de impressão através da Adyen.

Arquitetura da Integração

Deep Links como Base da Comunicação

A comunicação entre o aplicativo do parceiro e a maquinona é realizada através de Deep Links, que funcionam como comandos específicos enviados via URL. Esta abordagem permite:

Simplicidade na implementação: Não requer bibliotecas complexas
Compatibilidade: Funciona independentemente da versão do Android
Segurança: Parâmetros são codificados em Base64 para proteção dos dados
Integração com Adyen: Transações processadas através do gateway Adyen

Estrutura das Chamadas

As chamadas são enviadas como URLs contendo parâmetros JSON codificados em Base64: https://portal.ifood.com.br/acao?content=conteudo_base64

Fluxo de Comunicação

Aplicativo cliente envia deeplink com parâmetros
APP da maquinona processa a transação
Redirecionamento para URL predefinida com resultados
Retorno Retorno via Intent (opcional)

Funcionalidades Disponíveis

1. Pagamento

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

Métodos de Pagamento Suportados
DEBIT	Cartão de débito
CREDIT	Cartão de crédito
PIX	Pagamento instantâneo
VOUCHER	Vale alimentação/ refeição

Parâmetros JSON (Base64):
paymentMethod	Método de pagamento
value	Valor em centavos
transactionId	ID único da transação
tableId	(Opcional) Número da mesa
printReceipt	Booleana para impressão
urlToReturn	URL de redirecionamento
sendResultInSameIntent	Retorno via Intent

2. Estorno

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

Parâmetros JSON (Base64):
transactionIdAdyen	ID da transação Adyen original
printReceipt	Controle de impressão no POS
urlToReturn	URL para receber resultados
sendResultInSameIntent	Retorno via Intent

3. Autorização de Impressão

Passo 1
Deeplink para autorização: https://portal.ifood.com.br/make-payment?content={conteudo_base64}

Parâmetros JSON (Base64):
integrationApp	Nome da empresa integrada
urlToReturn	URL de retorno após criação do token
sendResultInSameIntent	sendResultInSameIntent

Passo 2
API para impressão: https://movilepay-api.ifood.com.br/ifoodpay/mobile/api/v1/print/file

Parâmetros JSON (Base64):
authorizationHash	Token gerado no passo anterior
contentBase64	Arquivo codificado em Base64

Exemplos de Implementação

Exemplo de Pagamento

1{
2  "paymentMethod": "DEBIT",
3  "value": 20000,
4  "transactionId": "transactionIdRetornado",
5  "tableId": "tableId",
6  "printReceipt": true,
7  "urlToReturn": "https://anota.ai/payment-result?result=",
8  "sendResultInSameIntent": false
9}

Deeplink resultante: https://portal.ifood.com.br/make-payment?content=eyAicGF5bWVudE1ldG...

Resposta de Pagamento Bem-sucedido

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

Resposta de Estorno Bem-sucedido

1{
2  "paymentMethod": "DEBIT",
3  "value": 20000,
4  "transactionId": "transactionIdRetornado",
5  "tableId": "tableId",
6  "printReceipt": true,
7  "urlToReturn": "https://anota.ai/payment-result?result=",
8  "sendResultInSameIntent": false
9}

Segurança e Autenticação

Compliance PCI DSS

Limitações do sistema seguem padrões de segurança estabelecidos
Restrições rigorosas de permissões no terminal Android

Autenticação via Token

Tokens de impressão com validade de 24 horas
Geração obrigatória para operações de impressão
Sistema de autorização em duas etapas

Integração Adyen

transactionIdAdyen: Identificador único processado pela Adyen
Armazenamento obrigatório para futuros estornos
Rastreabilidade completa das transações

Ambiente de Desenvolvimento

Emulador Recomendado

Small Phone API 30 (Android 11)
Compatibilidade garantida com terminais físicos
Configuração via Android Studio

Permissões Compatíveis

ACCESS_BACKGROUND_LOCATION
BLUETOOTH
Lista rigorosa de permissões suportadas

Restrições do Terminal

Proibido: Debug, serviços de acessibilidade, navegadores
Não suportado: Aplicativos testOnly
Limitações: Instalação de APKs não autorizados

Códigos de Status

Status de Resposta
SUCCESS	Operação concluída com sucesso
ERROR	Operação falhou (verificar errorReason)

Informações Adicionais Retornadas
deviceSerialNumber	Número de série do equipamento
cardBrand	Bandeira do cartão (quando aplicável)
errorReason	Detalhamento de erros

Recursos para Desenvolvimento

APK de Debug/Mock

Ferramenta de simulação para testes
Reproduz comportamento real sem afetar produção
Compatível com emuladores Android Studio
Permite validação de integração antes da homologação

Download APK

Documentação Técnica

https://developer.ifood.com.br/pt-BR/maquinona/
Manual completo com exemplos de implementação
Especificações detalhadas de parâmetros
Casos de uso e cenários de erro
Guias de boas práticas

Processo de Homologação

Desenvolvimento seguindo especificações
Testes com emulador Small Phone API 30
Validação com APK mock
Análise de segurança pela equipe Adyen
Teste na maquinona fisica
Deploy via sistema interno

Suporte ao Desenvolvedor

Contato Técnico

E-mail: integracaoifoodpago@ifood.com.br
Suporte direto da equipe técnica
Orientações para Android Studio

Recursos Adicionais

Links para recursos do Android Studio
Documentação atualizada no portal
Exemplos de código e troubleshooting

Considerações Importantes

Armazenamento de IDs

Obrigatório: Armazenar transactionIdAdyen para estornos futuros
Recomendado: Manter log de todas as transações
Segurança: Proteger dados sensíveis conforme PCI DSS

Limitações Técnicas

Conexão obrigatória com internet para transações
Tokens temporais com validade de 24 horas
Compatibilidade específica com Android 10/11

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’).

Links de referência

Developer Android | WebView Native BridgesLink aqui

Developer Android | Carregamento de URI InseguroLink aqui

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:exportedLink aqui

Source Android | Signature PermissionLink aqui

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:debuggableLink aqui

Developer Android | App Signing - ConsiderationsLink aqui

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 PracticesLink aqui

SQLite | Using The SQLite Encryption ExtensionLink aqui

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.

Links de referência

Developer Android | Insecure Broadcast ReceiverLink aqui

Developer Android | Detectar Inicializações de intents Não SegurasLink aqui

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 | CryptographyLink aqui

Developer Android | KeystoreLink aqui

Developer Android | Security SSLLink aqui