In this post, I'm going to tell the challenges I faced integrating with another payment gateway and document the process for myself (mainly). The gateway in question here is Ezzebank, which isn't very popular, and it's only for Brazilian PIX I guess.

First of all, this integration was a difficulty 06/10. Especially because I only had to integrate PIX, which is a Brazilian free money transfer method. This API doesn't even offer the option to credit card I think, so, it's very specific.

The API offers a sandbox for testing environment and production endpoints. I wrongly decided to go straight to production, which I regret… just a little bit.

Authentication

Before making any real request to generate payment QRCode or check for payment status, you have to request the authentication endpoint, passing your client_idand client_secretwhich you receive when registering for API usage. After that, you can use the brand-new generated token response to make the API requests.

Integration

The integration itself was pretty much:

1. Generate a PIXQRCode;
2. Make a PIXPIX payment;
3. Receive the webhook confirming the QRCode of the first step was paid;

To generate the code it was pretty much requesting the appropriate endpoint passing the Authentication credentials, the value, the payer name, and other related information. Then I received a Base64 image representing the QRCode, which I displayed on the screen using a simple <img> tag. I was using React at the interface, so I used the Image component of ChakraUI which we all know it's an img tag at the end of the day.

At the interface, I had to keep doing short-polling to check for the payment status of the QRCode. My API was in Nest.js, at the API level I was storing the information of the paid status, I didn't have to request the payment gateway endpoint to check the status. As soon as I received the webhook confirming the payment, the status at my database would be updated, and therefore I would know at the interface due to the shot-polling request I was making over and over every 2 seconds.

To make a payment (step 3) it was even easier. Just passing correct PIX information was enough, as well as the value. The only problem here was financial limits, but it's much more related to the account configuration.

Webhooks

This part of the API I found really smart. They're really extra safe about the webhooks. When you're setting up your API credentials, you define a username and password, that are used to be sent as encoded headers to your webhook endpoint. So every time you receive a webhook they have these credentials encrypted in BASE64 at the Authorization header

The second part of the validity checking of the webhook was really more interesting. At the header Verify-Signature, you receive a timestamp and an HMAC. Long story short: You have to hash the payload with the timestamp and your secret API key and afterward compare it with the HMAC you received at the Verify-Signature. Kind of complex, but it's comprehensible since it's a sensible webhook.

Doing all that verification part, I can pretty much trust the payload I receive at the webhook. It's truly the payment information saying it's confirmed, and you can update your system database \o/

Challenges

The biggest challenge I faced was the IP restrictions of this API. The API itself doesn't segment your requests to the production endpoint and your request to the doc website: dev.ezzebank.com. When I was first making the WIP requests I got an IP restriction, and when I tried to access the API documentation page I saw a Cloudflare message saying I was blocked 🤣

Besides this fact. The IP was a true bottleneck. I was deploying my API at Heroku, doesn't have and cannot have a fixed IP. Every time Heroku restarts its dyno you get a brand-new address. So I had to either move to AWS and use an Elastic IP or use some kind of reverse proxy. Of course, I choose AWS 😊

So I had to change the architecture of my system just to make this integration possible. It was a hard decision, but it ended up paying great dividends, AWS was a really better option when the system scaled.

Quite some learnings, I would rate this API 07/10, especially because the Webhook endpoint has to be fixed, I would rather say the webhook when requesting the payment QRCode… anyway, it was a good experience, quite some learning. Hopefully, you also learned something, since you got that far 😁