Products
Solutions
Full Stack Icon
Online Payments
Full Stack Icon
Full stack payments
Full Stack Icon
Payment gateway
Products
Product icon
Payment links
Product icon
Fraud prevention
Product icon
Reporting
Product icon
Authentication
Developers
Online payments icon
Developers

Integrate and update your payments.

Documentation

Mobile SDK
Web SDK
Upgrade to 3D Secure 2
Sandbox testing

Developer Hub

Explore Hub
Engineering blogs
Comms archive
Online payments icon
Support Centre
Online payments icon
API reference
Online payments icon
Changelog
Online payments icon
Status Page
Company
AboutCustomersBlogCareers
PartnersPricingSupportLoginGet in touch
SupportLogin
Get in touch

API Bridge Continued ~ Bringing the Bridge to Life...

Alison

Welcome to the second blog in our mini-series, featuring Judopay’s API Bridge.

Recapping from the first blog, we examined the circumstances behind Judopay’s decision to create an API Bridge. This was our solution to make the migration process for merchants from their current API, to Judopay’s Transaction API, as straightforward and seamless as possible.

Philip will now take you on the journey Judopay’s Engineering Team took, to bring this solution to life.

‍

Philip

The core task of the API Bridge - translation - turned out to be fairly simple. There were however, several obstacles along the way. I will briefly describe the core task of the API Bridge, before diving into the additional complexities we had to overcome.

‍

The core task of the API Bridge.

The payments industry is fairly standardised. There are a lot of services that overlap between PSPs, and the sort of information one PSP requires for a payment request, will tend to be the sort of information another PSP requires for the same type of request.

For the API Bridge, this meant the request / response translation was mainly a question of field-to-field mapping:

Translation: XML to JSON

The API Bridge could read in the raw XML request and start the translation task with an empty {} JSON object, building up the converted request by reading through the XML and adding any translated fields to the JSON.

On the return journey, the API Bridge would begin with an empty <Reponse></Response> XML, adding in the response tags, reading in values from Judopay’s JSON response.

However, there were complications to all of this.

What if the sender:

Submitted < amount currency="GBP">twenty five</amount>?
Our API expects amount to be expressed using digits; it won’t accept "amount": "twenty five".

Also, what if the sender:

Is attempting to refund a transaction, but mistypes the transaction's ID?
When Judopay’s API responds with a "not found" error, we will also need to translate this to some XML that the sender will understand.

So making our translation logic robust added extra complexity to the core task. I will consider some of these complexities in the next section.

‍

Complexities to overcome.

Firstly, I will examine the sorts of validations the API Bridge is required to perform against incoming XML.

Secondly, I will consider a case where the API Bridge needs to perform some orchestration, in order to support a particular type of request.

In this case the API Bridge needs to make multiple calls to Judopay's API in order to process a single XML request.

Thirdly, I will look at the issue of interlinked requests, where requests in the API are expected to be executed in a particular sequence.

And finally, I consider the error-handling and translation of the error messages.

Validation.

As I mentioned above, there is a danger that merchants may send a badly-formed request. It is key the API Bridge performs validations against incoming XML.

For example, maybe one of the fields has an invalid value, or maybe there's a mandatory field missing.

There is no point translating a request that we know from simple inspection will fail.

As a result, we needed to insert a validation step before the translation step, just after the XML request has been read-in.

If the request fails validation:

The API Bridge prepares an XML error response to send back to the merchant, outlining what went wrong. As much as possible, we tried to get the API Bridge to mimic the error XML that the current API would return in this case, right down to the error codes and error messages.

If the request passes validation:

The translation can continue. Because obvious request errors have been weeded out, the API Bridge's code can handle translation failures by dropping the involved field entirely. This sounds clumsy, but the preceding validation means these translation errors don't happen in practice.

‍

Orchestration.

As stated above, most requests could be mapped to Judopay’s requests on a one-to-one basis. However, there were situations where this wasn’t the case.

For example, in case the above change is accepted, Judopay lets merchants take card payments by either providing:

  • The consumer’s card details, or
  • A card token (that represents a card whose encrypted details have been saved in our systems).

The current API we were mimicking, offered an additional method:

Merchants could specify a previous transaction ID, and their current API would reuse the card details from that transaction for this one.

Judopay had nothing like this, so in order to honour these payment requests, meant introducing some basic business logic into the API Bridge. The problem was solvable, but it did require an orchestration capability to be added into the API Bridge.


Request flows.

Another complexity was with 3D Secure.

(This is a means of authenticating card holders, so that consumers can prove that they have access to the funds they are trying to use.)

A 3D Secure-backed transaction is not only more likely to be approved, but also means the merchant is not liable for any chargebacks.

However, 3D Secure requires a number of steps.

The current API we were mimicking followed the same flow as ours, except they included an extra call at the beginning with an enquiry about enrolment:

1. Submit the consumer’s card details to check if the card is enrolled for 3D Secure.

(There are some jurisdictions where 3D Secure isn’t so common).

Judopay however, bundles this as part of Step 1. We do not expose the enrolment check to the merchant as a separate call. When the merchant submits a payment request, we first check the card’s enrolment in 3D Secure. If the card is enrolled, then we begin a 3D Secure session.

As things stand, we were in luck. The current API flow I outlined was actually for version 2 of 3D Secure, and all their consumers had not yet moved from version 1.

This provided us with the freedom to redesign the current API’s 3D Secure (version 2) flow to match our own. While it may have been tempting to match the old flow, this would have meant (in our view), compromising the quality of the 3D Secure workflow.

‍

Error-handling.

The last complexity we faced was:

What to do when things go wrong?

I have already mentioned having to return errors if validations failed, or if the orchestration couldn’t find the previous transaction. But what about other errors?

What if the merchant gives us the wrong Judo ID, or they try to refund a non-existent sale?

These errors can only be detected once the request has been passed to Judopay’s API. Going further, what if our systems don’t respond in a timely manner?

There is nothing the API Bridge can do to prevent these errors from happening. It can only cope with them when they do happen.

“Coping” in this case means converting the Judopay error to an appropriate XML error.

The issue here is that Judopay has its own error codes and error messages, unfortunately bearing no relation to the current API’s error codes or error messages.

‍

How is the translation to be done?

In the end, we decided to draw up a list of Judopay error codes that we thought users of the API Bridge could possibly trigger. For instance, if you tried to capture a sale via Judopay’s API, you would receive a response like:

{
  "message": "Sorry, it looks like you're trying to make a collection on an invalid transaction type.

  Collections can only be performed on PreAuths.",
  "code": 43,
  "category": 2
}

The API Bridge would pick up code 43 and look up the associated error code and messages for the current API:

19, "Cannot fulfill transaction" 
and,
"You attempted to fulfill a transaction that either could not be fulfilled (e.g. auth, refund, cancelled) or already has been".

It's not an elegant solution, but it served as a useful backstop.

‍

For the final blog in the mini-series, Phillip will examine the security concerns and safeguards that needed to be addressed and future possibilities for Judopay’s API Bridge.

Recent posts.

Growth tips

Mobility taxi image for payments

Smooth & Seamless. Gen Z & Millennial payment preferences

Read morePurple background blob

Engineering

Judopay and Mobo2Go case study imageTeal background blob

API Bridge Continued ~ Bringing the Bridge to Life...

Read more

Growth tips

Strong Customer AuthenticationPink background blob

7 ways bars can reduce wait times and boost sales

Read more
Judo logo

Our solution

Online paymentsFraud protectionReporting tools

Company

AboutCustomersPartnersCareersBlogPress

Developers

DocumentationDeveloper hubChangelogAPI referenceStatus page

© Judopay 2023. All rights reserved.

Alternative Payments Limited (Company Number 07959933) t/a Judopay is wholly owned by Fabrick S.p.A., part of the Banca Sella Group.

Service agreementCertificatesLegal hubPrivacy policy
Terms & conditionsPrivacy notice for job applicants
Cookie Policy
PCI DSS
ISO27001 logo
Cyber Essential Plus logo
ico registered logo

© Judopay 2023. All rights reserved.