In this first article of a series I’ll show you the first steps to integrate Portuguese Easypay payment gateway with your software so you can use Multibanco and SEPA Direct Debit payments in an automated fashion.
You can expect to see what you should consider and take into account when you need to integrate Easypay with your software. What I’m writing here is a direct result from my personal experience with this payment gateway system.
1. What is Easypay?
Easypay is a Portuguese company that provides a payment gateway system. You can integrate your software with their API, enabling you to accept payments from Multibanco (Portuguese payment type), SEPA Direct Debit, credit card, Boleto (for the Brazilian market) and a few others. Besides, it allows some integrations with other software systems, for instance with InvoiceXpress (view demo).
It’s a bit different from Stripe or Lemonway because it’s primarily used for the Portuguese market - that is, it complies with all the Portuguese (and European) payment rules and requirements.
However, I must advice right now that if you only need Direct Debit payments you should really choose another option. Want to know why? Read on.
2. Disclaimer
When reading this series of articles you might find yourself thinking that I “hate” Easypay. Well, and it’s a bit true. But I must disclose right now that I don’t work for their competition, nor have I any kind of dispute with Easypay company.
I’ve worked on a project around 2016⁄2017 for a client that already used their service and my work was to create their solution from the scratch which implied integrating with their payment gateway. In this process I’ve read the documentation, talked multiple times (by email and by phone) with different Easypay support people.
I have to say I never got a straight and clear answer without the need to test and trial-error the APIs. I had to refactor the Direct Debit notifications code 6 times! I don’t consider myself dumb and the truth is they could never explain in a straight manner how their system is supposed to work. It’s like the guy who wrote it left the company and no one knows how it works.
And the docs… oh! The Portuguese documentation seems to be written by an intern (and I mean - a bad one - because there are good interns) and in English by a poorly sentenced Indian/Chinese/Icelandic guy. I actually found a sentence that literally didn’t make sense.
Having said this my one and only purpose with this series of articles is to help, the best way I can, whoever is brave enough to integrate Easypay payment gateway, so you don’t have to go through all the things I had.
3. Before you begin…
The concept of the service has a huge potential. However, integrating with Easypay will be quite challenging. Not because it’s technically complex - after all, it’s a small set of SOAP requests where you send some data and expect a response - but because the naming seems to be taken from the 17th century and the documentation is not clear.
For instance, you could expect and endpoint with the name create-reference. The endpoint exists, but it’s name is 01GB. How cool is that? And, if you want to make a payment request you need to call the 05AB endpoint. Can’t be more clear than this, can it?.. Also, most of the parameters for the endpoints also use this “logic”.
The official Easypay docs can be found here. If you need to estimate the amount of time you’ll take to integrate with their system I would multiply the number of hours you have in head by 2.
4. Preparation / Setup
In order to integrate with Easypay, no matter the payment type you’ll be using, you need to have an account and know what’s the user - the same as the Client ID - that you’re using to login to Easypay’s backoffice. You’ll also need to access their demo platform so you can screw around and test your integration. If your client never developed any integration you might need to ask Easypay so they allow you access to this test platform.
Beware that the production backoffice and the testing backoffice are different and many times don’t have the same features or the same behaviour. Even so, from my experience, if your integration code works with the test API it will work on the production endpoints.
When developing remember to always use the testing API to avoid creating false payment requests.
Your client will also need to have a CIN (Client Identification Number), which is a six digit number and represents the first digits of a Multibanco reference. For instance, in the reference 100123456 the CIN is 100123. And you’ll need an Entity which is a five digit number and is associated with your client’s account and represents the Entity number when paying by Multibanco (like 21000).
Before we go deep into code I must say there are two ways of authenticating your application in Easypay so you can use their APIs. You can either IP authentication or Code authentication.
If you are deploying your system in a server with a dedicated IP address you can use the IP authentication (because it never changes). For this you can go into Easypay’s backoffice » Webservices » IP Configuration and set the IP of your server for the CIN you want to use in your integration. You can use up to three CIN.
In case you’re using a shared hosting or you don’t want to risk an IP change in the future you can authenticate your application by Code. If you wish to do so, go to Easypay’s backoffice » Webservices » Code Configuration and select the “Code” option for the CIN you want to use on the integration. Click on the Save button and at this point you should see the Code you must send on all Easypay API requests.
I’ll display all the integrations using PHP code but since the APIs are available through SOAP you should be able to convert the code to whatever language you wish to do the integration in.
If you happen to be using PHP Easypay has a wrapper for the API calls - after writing this article they’ve changed the ownership of the repository that can be found here - that I started using. However the code is not PSR-2 compliant, doesn’t have Composer and I needed to tweak some code. I ended up forking the project and creating my own wrapper that you can find on GitHub.
Besides the package has a set of working examples and a demo database schema you can use to bootstrap your integration.
This article is part of the series “How to integrate with Easypay.pt Payment Gateway”
Article image from Freepik: Designed by Freepik