Payments API: 7 tips for successful integrations

Now, let us underline the most important points which will allow you to make your integration process smoother, avoid costly mistakes, and properly follow the requirements of the PCI standard.

Rotation of authorization data, such as passwords and access keys, is a mandatory requirement during transaction processing. If a password is hardcoded, that is, stored within the body of the software code, then password rotation becomes a challenge, because every time a password is changed, you need to perform a new release of the respective software code. The need for another release also arises if the password is hacked. Software code release is a labor-intensive process, so if you want to save the effort don’t hardcode passwords.

Passwords often need to be sent to the gateway in order to enable transaction authorization. So, whatever mechanism you choose for password storage, it should be a secure and PCI-compliant one. An efficient and PCI-compliant practice is storing passwords in an encrypted form using special encryption algorithms, such as AES 256.

At the time of mandatory password rotation, the password should be changed on both the platform’s and the gateway’s ends. Failing to synchronize password changes on two ends might lead to interruption of transaction processing.

If you don’t want transaction processing to come to a halt, we advise you to store 2 passwords. If you support both the current password and the new one, and set the new password before rotation, then there is no need to strictly synchronize the password change with the gateway’s end. The old password will be automatically switched to the new one after being rotated by the gateway.

Again, you should store both passwords in an encrypted format, compliant with the PCI standard.

Following this advise will enable seamless transaction processing even during password rotation.

After you integrate your platform with the gateway, you might have to deal with various customer complaints or system issues, regarding, for instance, transactions declined for unclear reasons. Not all issues and behaviors can be easily debugged or replicated. For such cases it is useful to keep a log of transactions and API calls, as it might provide some details, helpful for diagnosing the cause of a particular issue.

Therefore, in order to be able to lookup all transactions you submit, it makes sense to log all your requests and the gateway’s responses. Requests and responses can be logged by the system on a regular basis, or, alternatively, you can develop a mechanism for activating the logging function when necessary. Additionally, you might want to log some basic data and activate detailed logs for debugging purposes.

Thus, logs provide a useful tool allowing you to deal with various kinds of problems, including both common and unique ones. Thanks to logs, debugging process becomes more transparent.

The next serious challenge encountered during payment gateway API integrations lies in maintaining synchronization between the two systems and effectively cross-referencing data between them. For instance, when a transaction has been declined, it is crucial for the originating system to pinpoint this specific transaction. Similarly, during recurring billing, the system should have the capability to identify customers whose subscriptions are overdue.

Therefore, it is imperative that as you submit transactions or create customer and subscription records within a payment gateway, you provide unique identifiers for these records that align with your internal system’s logic. Ideally, you should maintain corresponding records for transactions, customers, and subscriptions within your system and include their respective identifiers in the API calls directed towards the payment gateway.

This ensures seamless integration and accurate information retrieval between the systems.

The gateway assigns its unique identifiers to transactions, customers, and subscriptions. In order to simplify operating with these records on your system’s end, it makes sense to use your own identifiers. So, our recommendation is to create a system of such identifiers and share them with the gateway.

Based on such cross-reference mechanism, it will be much easier to lookup diverse transaction types, including declines, ACH returns, and chargebacks. Moreover, the mechanism also makes reporting process more transparent from the originating system’s standpoint.

So, while strategizing your integration process, we advise you to pinpoint the specific fields within the payments API that can accommodate identifiers from your system. Furthermore, you must carefully determine the values that will be transmitted to the gateway through these designated fields.

Both transactions and API calls can be either approved or declined. While approval scenarios are, usually, implemented by default, decline scenarios are often overlooked. At the same time, the ability of your payment processing API to handle declines is just as crucial.

Decline handling mechanisms vary, depending on decline causes and your system’s needs. For instance, in real-time transaction processing scenarios, a universal recommendation for the user whose payment has been declined, is to try a different card. At the same time, in recurring billing situations, the types of declines and respective decline handing features are more diverse.

In addition to declines, various errors might occur. None of the errors should bring your system’s operation to a halt. Instead, the system should incorporate error handling scenarios and mechanisms.

Our final recommendation in this section is to keep accurate and transparent logs of errors and declines. These logs will help you improve your integration in a competent and responsive way.

Handling of timeouts is another challenge to be taken into consideration during payment integrations.

All timeouts form two categories:

• connection timeouts;
• read timeouts.

Connection timeouts arise when you try to establish a connection with a payment gateway, but your request times out before any data has been transmitted. Common reasons behind such timeouts include server issues, DNS problems, or network instability. In the event of a connection timeout, the platform attempting to establish the gateway connection eventually receives a timeout message.

When your system encounters such a message, it could potentially signal a more extensive processing issue. Therefore, it is advisable to promptly notify the system administrator of this potential problem and request their investigation into it.

A read timeout happens after successful connection with the gateway, when you send the request but it remains without response. The problem is that having received no response, you cannot tell whether the transaction has been processed or not. Our recommendation for such cases is to try sending up to three void transactions in a row. Thus, you might be able to void the initial transaction, reverse its authorization, and, subsequently, submit the next one.

To be able to successfully void a transaction, you need to refer to it using its identifier. However, in a read timeout situation, you do not get such an identifier, as there is no response from the gateway. Under such a scenario, the cross-referencing system outlined above might prove handy, because transaction identifier, assigned by the originating system might be the only way to refer to the transaction you are trying to void.

Both your system and the gateway might experience connection-related and other issues at any moment, so timeouts are inevitable. That is why, in our view, timeout handling logic is a must-have for a reliable Payments API.

Card data storage and cardholder data flow are the two pillars of the PCI security standard.

As you develop your card storage strategy, you should keep in mind that businesses are allowed to store only some of the values, associated with payment cards (for instance, you cannot store CVV codes). Moreover, all the values should be properly encrypted.

Encryption and key rotation algorithms are not easy to implement. That is why, you need to choose the most suitable tokenization strategy for your business. To remind, a token is an encrypted value used instead of the actual card number during storage and transmission.

Judging from our experience, software platforms are, generally, aware of the card storage challenges, so they try to partner with gateways, supporting tokenization features. At the same time, they often overlook card data flow issues. Native payment forms of these platforms may look appealing and ergonomic, but they are not always secure.

Every piece of software that handles sensitive card data falls within PCI scope, which entails rigorous monitoring and audit requirements. For example, a customer inputs card data into a payment form and submits it to complete an online purchase. If the input data lands on the SaaS platform’s server, then the whole payment application falls within the scope of PCI regulations. Moreover, in AJAX-based applications, the data is transmitted to the server even before the customer submits the completed form.

Even though the platform does not store card data, it can still be intercepted during transmission.

In order to protect sensitive cardholder data, most companies that accept electronic payments, resort to usage of third-party payment pages. If a payment page is an external one, then it is the third-party provider and not the platform that has to deal with PCI regulations. However, many SaaS platforms want to introduce customized adjustments into their payment pages going “beyond their limits”.

So, if a conventional third-party payment page is unable to accommodate the needs of your platform’s customer base, then you can try the so-called proxynization concept, relying on JavaScript and AJAX. Proxynization means embedding of a client-side script and replacing card number with a token in the payment form before its submission to the server. Thus, the platform’s payment application server receives the payment data featuring the token instead of the actual card number.

Most specialists, including PCI auditors, consider proxynization approach to be less secure than conventional payment pages. That is why it makes sense to consult a QSA before you implement the proxynization mechanism.

Every business that wants to accept electronic payments has to select the most suitable payment processing or gateway solution. The right choice of a processing or gateway partner is a vital decision for the company.

However, the choice does not guarantee the success of future operations unless payment API integration is performed in a proper way. Payments API is the foundation of all payment integrations with processing and/or gateway partners that a company undergoes. That is why we decided to dedicate a comprehensive document to Payments API concept and the secrets of successful integration process.

One of the common mistakes made by companies that need to select a payment vendor, is making a choice based primarily on the cost of the respective solution and neglecting or ignoring other important factors. Such focus on the price of the product might lead to a situation when initially neglected aspects and details start to show only when it comes to payment gateway API integration phase, hampering the integration process.

Thus, it is the right choice of a payments API and careful supervision of the payment API integration rather than the price of the selected solution that define the success of your SaaS platform operations. The cheapest payments API is not necessarily the best one.

In subsequent sections we will outline the most significant factors and features that any integrator needs to take into consideration if he wants to avoid costly mistakes in future.

Let us start with the definition of the payments API concept. The abbreviation stands for application processing interface, while the term payments API means the logic needed for transaction processing. Among other things, this logic allows a company to accept electronic payments.

Many people erroneously assume that an API focuses solely on processing of transactions. In reality, besides the traditional payment processing API, there are several complementary APIs, which significantly expand the feature set your SaaS platform can offer. Now we are going to describe the most commonly used additional APIs and important functions they perform.

As you develop an integration strategy for your SaaS platform, you should take all the listed aspects into consideration.

When you choose a payments API, price is an important factor, but it is not the decisive one. Here is the rule of thumb we suggest: transparent pricing model combined with optimal value-for-money ratio.

Even the best API can fail you if you make mistakes during the integration process. These mistakes might cost more effort further down the road. So, in the subsequent sections we would like to focus on payment integrations and provide specific tips on how to find the shortest way to success when integrating with a payment processing solution.

A flexible and secure state-of-the-art payments API has to support a whole lot of features. Many present-day companies, such as Zift, try to include most of the logic described in our guidelines into their offerings.

As you are selecting and implementing an optimal payment API, we advise you to analyze its functionality and carefully plan your payment gateway API integration process.

Don’t hesitate to address our payment experts to learn more about Zift solution powered by UniPay Gateway technology, and get more helpful advice on how to make your payment integration a success.