Para quem tem um app de academia, curso ou agendamento e quer cobrar dentro dele, o caminho mais curto costuma ser um SDK mobile ou um checkout pronto, pois mantém os dados do cartão fora do servidor e reduz o escopo de segurança. A API direta faz sentido quando o fluxo de pagamento precisa ser totalmente personalizado e a equipe tem estrutura de backend para sustentar isso. Em qualquer caso, o app só vai a produção depois que o webhook estiver confirmando o status de cada cobrança de forma automática.
Ao longo deste artigo você vai encontrar os critérios para decidir entre integrar ou usar um link de pagamento, a comparação entre API, SDK e checkout pronto, um passo a passo com credenciais de teste e produção, o ciclo real de uma assinatura do mês 1 ao mês 6, as obrigações de segurança (tokenização, PCI DSS e LGPD) e um checklist antes de publicar.
Integrar cobranças no app ou usar link de pagamento: quando cada um vale
A decisão de integrar um gateway de pagamento ao app não é só técnica: ela depende do modelo de negócio, do volume esperado e do tempo de desenvolvimento disponível. Antes de escrever uma linha de código, vale responder se a integração resolve um problema real ou se um link de pagamento já daria conta.
Critérios que indicam que a integração faz sentido:
- O cliente paga dentro do fluxo do app, sem ser redirecionado para outra tela ou site
- O modelo envolve cobrança recorrente ou assinatura, que exige renovação automática
- A experiência de marca precisa ser consistente do início ao fim da compra
- O volume de transações justifica o tempo de desenvolvimento e manutenção
Critérios que indicam que um link de pagamento resolve:
- O pagamento é avulso e o cliente pode sair do app para concluir
- O app ainda está em fase de validação e a prioridade é testar o modelo de negócio
- A equipe não tem desenvolvedor disponível no momento
Um link de pagamento entrega o resultado mais rápido para quem está validando. Já o checkout dentro do app se torna necessário quando a experiência de compra é parte do produto em si, e não apenas um detalhe operacional.
API, SDK ou checkout pronto para integrar cobranças em um app próprio
As três opções de integração atendem perfis diferentes de app e de equipe. Cada uma transfere um nível distinto de responsabilidade técnica e de segurança para quem desenvolve.
API de pagamentos para app (integração direta)
A API direta dá controle total sobre o fluxo de pagamento: cada etapa, cada campo e cada resposta é tratada pelo backend próprio. Isso tende a exigir um servidor dedicado, conhecimento de autenticação OAuth e maior escopo de conformidade com o PCI DSS, pois os dados de pagamento passam pelo servidor da aplicação antes de chegar à plataforma. Pode ser adequada quando o fluxo de compra tem lógicas muito específicas que nenhuma biblioteca padrão cobre.
SDK de pagamento mobile
O SDK mobile é uma biblioteca nativa para iOS ou Android que cuida da coleta dos dados do cartão diretamente no dispositivo do usuário. O número do cartão nunca chega ao servidor do app: ele é convertido em um token pela própria biblioteca antes de qualquer transmissão. Esse mecanismo, chamado de tokenização, tende a reduzir o escopo de PCI DSS e a simplificar a manutenção de segurança ao longo do tempo.
Checkout Pro e Checkout Transparente
O Checkout Pro redireciona o usuário para uma tela de pagamento hospedada pela plataforma, com o menor esforço de integração possível. O checkout transparente embute a tela de pagamento dentro do app, mantendo a aparência da marca, mas ainda delegando a coleta dos dados à plataforma. Ambos transferem parte da responsabilidade de conformidade PCI DSS à plataforma de pagamento, o que pode ser adequado para apps que querem ir a produção com agilidade.
A escolha entre as três opções depende do nível de personalização necessário, da capacidade técnica da equipe e do prazo disponível. Nenhuma delas é a única correta: cada uma serve melhor a um contexto específico.
Passo a passo para integrar cobranças em um app próprio
O processo de integração segue uma sequência que começa no ambiente de testes e só vai a produção depois que o webhook estiver confirmando status de forma correta. Cada passo abaixo corresponde a uma ação concreta no painel de desenvolvedor.
1. Crie a aplicação e obtenha as credenciais de teste
O primeiro passo é criar a aplicação no painel de desenvolvedor da plataforma de pagamento escolhida. Por exemplo, no Mercado Pago Developers esse cadastro gera dois conjuntos de credenciais: um para o ambiente de teste e outro para produção. As credenciais de teste e produção são separadas por design, e publicar o app com o access token de teste é um erro que impede qualquer cobrança real.
2. Instale o SDK e configure o ambiente
Com as credenciais de teste em mãos, a instalação do SDK ocorre via gerenciador de pacotes do projeto (npm, CocoaPods, Gradle, conforme a plataforma). O guia inicial do SDK cobre os comandos de instalação e a configuração do ambiente de teste no código. Nessa etapa, o access token de teste vai para as variáveis de ambiente do projeto, nunca direto no código-fonte.
3. Faça pagamentos de teste e valide os retornos
A documentação da plataforma fornece cartões fictícios com diferentes cenários: aprovado, recusado e pendente. Esses cartões permitem simular o comportamento real da API de pagamentos para app sem movimentar dinheiro. Cada resposta da API devolve um status e um código de erro que o app precisa tratar, pois o usuário deve receber uma mensagem clara em cada cenário.
4. Configure o webhook para receber o status das cobranças
O webhook é o mecanismo pelo qual a plataforma avisa o servidor do app quando o status de um pagamento muda. Sem ele, o app não sabe se uma cobrança foi aprovada ou recusada, a menos que faça consultas manuais à API. Para cobrança recorrente, isso transforma cada renovação em uma conferência manual, o que é inviável em escala. O artigo sobre como configurar o webhook detalha o processo de registro do endpoint e a validação das notificações recebidas.
5. Troque para credenciais de produção e publique
Antes de publicar, o access token de teste precisa ser substituído pelo de produção nas variáveis de ambiente. O checklist mínimo antes de ir ao ar inclui:
- Webhook ativo e recebendo eventos de forma correta
- Credenciais de produção no lugar das de teste
- Política de privacidade atualizada conforme a LGPD
- Um pagamento real de valor mínimo para confirmar o fluxo completo no painel
Só depois dessa validação o app está pronto para receber cobranças reais.
Cobrança recorrente dentro do app: do mês 1 ao mês 6
A cobrança recorrente é onde a integração mostra seu valor real, e também onde os problemas aparecem quando o webhook não está configurado. O ciclo de uma assinatura tem momentos críticos que vão além do primeiro débito.
Alt text: Os momentos-chave do ciclo de uma assinatura:
- Mês 1 (alta): o cliente escolhe o plano, o checkout de assinatura dentro do app coleta os dados do cartão, a tokenização salva o cartão de forma segura e o primeiro débito é confirmado via webhook
- Mês 3 (troca de cartão): o cliente atualiza o cartão no app; o token é renovado sem cancelar a assinatura, mas o app precisa oferecer essa tela de atualização de forma acessível
- Mês 6 (renovação ou cancelamento): a renovação automática ocorre quando o webhook confirma o pagamento; o cancelamento deve ser possível dentro do próprio app, tanto por boas práticas quanto por exigência da LGPD
O recurso chamado Assinaturas nas plataformas de pagamento cuida da lógica de renovação, mas o app ainda precisa tratar os eventos que chegam pelo webhook. Sem esse canal ativo, o app não sabe se o pagamento do mês 6 foi aprovado ou se o cartão foi recusado, e a renovação vira um processo que alguém precisa conferir de forma manual a cada ciclo.
Segurança e dados de clientes na integração de cobranças
A segurança de uma integração de cobranças envolve três camadas que se complementam: tokenização, conformidade com PCI DSS e adequação à LGPD. Cada uma cobre um aspecto diferente do risco.
A tokenização substitui o número do cartão por um identificador gerado pela plataforma de pagamento. O servidor do app armazena esse token, não o número real do cartão. Isso pode reduzir o risco de exposição em caso de vazamento, pois o token isolado não permite realizar cobranças sem as credenciais da plataforma.
O PCI DSS define os requisitos de segurança para quem processa dados de cartão. Quem usa SDK ou checkout pronto tende a transferir parte do escopo de conformidade à plataforma de pagamento, pois os dados do cartão nunca passam pelo servidor do app. Quem integra por API direta assume um escopo maior de PCI DSS, o que pode exigir auditorias e controles adicionais dependendo do volume de transações.
A LGPD classifica dados de pagamento como dados pessoais. A política de privacidade do app deve informar quais dados são coletados, por quanto tempo ficam armazenados e com quais terceiros são compartilhados. Antes de ir a produção, essa documentação precisa estar atualizada e acessível ao usuário dentro do próprio app.
Perguntas frequentes sobre como integrar cobranças em um app próprio
Preciso de SDK ou API para integrar pagamento no meu app?
Depende do nível de controle necessário e do esforço disponível. O SDK tende a ser adequado para a maioria dos apps, pois reduz o volume de código e mantém os dados do cartão fora do servidor via tokenização. A API direta faz sentido quando o fluxo de pagamento precisa de personalização total e a equipe tem estrutura de backend para isso.
Como testar pagamentos antes de publicar o app?
O processo usa credenciais de teste separadas das de produção, com um access token específico para o ambiente de desenvolvimento. A documentação da plataforma fornece cartões fictícios que simulam diferentes cenários (aprovado, recusado, pendente). Cartões reais não devem ser usados no ambiente de teste.
Posso guardar o cartão do cliente dentro do app?
O servidor do app não deve armazenar o número bruto do cartão. A tokenização permite salvar uma referência segura ao cartão sem expor o número real: o token é gerado pela plataforma de pagamento e vinculado ao cliente, permitindo cobranças futuras sem que os dados sensíveis trafeguem pelo servidor do app.
Como cobrar assinatura dentro do app?
O recurso de Assinaturas da plataforma de pagamento cuida da lógica de renovação. No primeiro pagamento, a tokenização salva o cartão; nas renovações seguintes, o débito ocorre de forma automática com base no token armazenado. O webhook é indispensável nesse fluxo: sem ele, o app não recebe confirmação de cada renovação e não consegue liberar ou bloquear o acesso do usuário de forma automática.
O que verificar antes de ir a produção com a integração?
O checklist mínimo inclui: trocar o access token de teste pelo de produção, confirmar que o webhook está ativo e recebendo eventos de forma correta, atualizar a política de privacidade conforme a LGPD e fazer um pagamento real de valor mínimo para verificar o status no painel. Só depois dessa validação o app está pronto para cobranças reais.
Quem decidiu integrar cobranças no app próprio tem um ponto de partida concreto disponível: o Mercado Pago Developers reúne a documentação do SDK, os cartões de teste e o painel de configuração do webhook em um só lugar. O guia inicial do SDK é o próximo passo para quem quer sair do ambiente de teste e chegar à primeira venda real com o status de pagamento confirmado de forma automática.