No primeiro artigo da série, mostro os primeiros passos e preparação para a integração de pagamentos por Multibanco (MB) e Débito Direto (DD) com a Easypay.
Neste primeiro artigo apresento a preparação, o que deves ter em conta e um resumo do que foi a minha experiência ao integrar uma aplicação com este serviço de pagamentos.
1. O que é a Easypay?
A Easypay é uma empresa portuguesa que disponibiliza uma solução para integrar vários métodos de pagamento através de um único serviço. Entre as várias formas de pagamento tens disponível pagamentos por Multibanco (MB), Débito Direto (DD), MBWay, Cartão de Crédito (CC) e Boleto (usado no mercado brasileiro). Além destes métodos de pagamento, disponibiliza algumas integrações com outros sistemas, das quais se destaca a integração com o InvoiceXpress (ver demo).
Portanto, difere de soluções como o Stripe ou o Lemonway porque permite a integração de pagamentos específicos do mercado nacional. Fica a nota já no início: se apenas necessitares de pagamentos por Cartão de Crédito, recomendo vivamente que escolhas outra opção.
2. Disclaimer
Se continuares a ler esta série de artigos, vai parecer que eu tenho um “ódio de estimação” à Easypay. E é verdade. Mas importa desde já dizer que não é porque trabalho para a concorrência ou porque tenho algum problema direto com a Easypay.
Em 2016⁄2017 trabalhei num projeto para um cliente que usava este serviço e o nosso trabalho foi redesenhar o projeto do cliente e por consequência tivemos de desenvolver as integrações de raiz. Neste processo, esmiucei a documentação e falei inúmeras vezes com várias pessoas do suporte técnico.
Nunca consegui ter uma resposta clara e assertiva, sem ter de testar e fazer trial-error. Tive de fazer refactor ao código de notificações de pagamentos por débito direto 6 vezes! 6 vezes porque nunca me conseguiram explicar, de uma única vez, como é que o sistema está preparado para funcionar. Dá ideia que quem escreveu o código e sabia como o sistema funciona foi embora e agora ninguém sabe bem o que é que “lá está”.
E a documentação… A documentação parece ter sido escrita em português por um estagiário (atenção, há estagiários bons, mas este não foi um deles) e em inglês por um indiano (encontrei pelo menos uma frase que não fazia literalmente sentido).
Dito isto, o meu único objetivo com estes artigos é ajudar, da melhor forma, quem tentar integrar o seu sistema com a Easypay, para que não tenham de passar pelo mesmo caminho penoso que eu tive.
3. Antes de começares a integração…
A ideia base do serviço tem um potencial enorme. No entanto, fazer a integração com o serviço da Easypay é uma pequena batalha. Não por ser tecnicamente complexo (afinal é um conjunto de chamadas SOAP onde envias um conteúdo e esperas uma resposta), mas porque as nomenclaturas foram criadas algures em 1874 e a documentação não é muito extensa ou explicativa.
Como exemplo, seria de esperar que tivesses uma API com o nome create-reference. Ela existe, mas o nome é 01BG. Fixe, não é? E, se quiseres fazer um pedido de pagamento, tens de chamar uma API 05AG. Altamente expressivo? Pois é.. Além desta lógica magnifica no nome das APIs, grande parte dos parâmetros enviados e recebidos nos XML dos requests, também usam esta “lógica”.
A “documentação” oficial da Easypay está disponível neste endereço. Se tiveres de estimar o tempo de desenvolvimento para integrar o teu software com a Easypay, a minha experiência diz-me que deves multiplicar o tempo que prevês por 2.
4. Preparação / Setup
Para fazeres uma integração com a Easypay, independentemente do método de pagamento, precisas de ter uma conta e saber qual é o user, que é o Client ID que usas para aceder ao backoffice da Easypay. Deves também ter acesso à plataforma de testes. Se nunca fizeste nenhuma integração, é possível que tenhas de solicitar à Easypay que te disponibilize o ambiente de testes.
Nota que o backoffice de produção e o de testes muitas vezes não têm as mesmas opções disponíveis nem o mesmo comportamento. Também os dados de acesso podem ser diferentes. Ainda assim no caso específico das integrações com as API, pela minha experiência, se funcionarem em testes, vão funcionar em produção.
Quando estiveres a desenvolver a integração, lembra-te de usar sempre as API do ambiente de teste.
Além de teres conta na Easypay, precisas de ter contratado pelo menos um CIN (Client Identification Number). Este número, de seis dígitos, representa os primeiros seis dígitos da referência Multibanco. Por exemplo, numa referência 100123456, o CIN será 100123. Também é necessário uma entidade, que é associada ao cliente. Esta entidade, de cinco dígitos, representa a entidade para os pagamentos por MB (ex: 21000).
Antes de avançarmos para os meandros da integração em si, é importante referir que as API da Easypay têm uma autenticação específica que pode ser feita de duas formas: por IP ou por código.
Se fores implementar o sistema num servidor com IP dedicado podes usar a autenticação por IP (porque ele nunca muda). Para isto, basta acederes ao backoffice da Easypay e acederes ao menu Webservices » IP Configuration e definires o IP do servidor para o CIN onde pretendes usar a integração. Podes definir até 3 IPs para cada CIN.
Caso implementes a integração num servidor partilhado ou não queiras correr o risco do servidor dedicado mudar de IP e não te lembrares que tens de ir ao backoffice da Easypay, podes usar a validação por código. Neste caso deves aceder também ao backoffice da Easypay, ao menu Webservices » Code Configuration, selecionar a opção “Code” no CIN que pretendes integrar e guardares as alterações. Nesta altura é apresentado um código que tem de ser enviado em todos os requests das APIs.
As integrações vão ser demonstradas com código PHP, mas dado que as API estão disponíveis através de SOAP, bastará converter o código para a linguagem onde pretendes fazer a integração.
Se estiveres a fazer a integração com PHP, a Easypay tem um wrapper para chamadas disponível - após escrever estes artigos a Easypay mudou o owner do projeto no GitHub que agora pode ser encontrado neste repositório - que inicialmente comecei por usar. No entanto, o código não é PSR-2, não tem Composer e precisei de ajustar algum código para me entender. Acabei por fazer um fork e o meu wrapper está aqui.
Além disto a package contém exemplos completos, incluindo um schema de exemplo da base de dados, com as integrações que são apresentadas nos restantes artigos.
Este artigo faz parte da série “Como integrar pagamentos com a Easypay”
Imagem do artigo retirada de Freepik: Designed by Freepik