Payments API: 7 tips for successful integrations
Master the challenges and solutions related to handling timeouts during API payment integrations.
- Handling Timeouts: The article emphasizes the importance of effectively managing two types of timeouts in payment integrations: connection timeouts and read timeouts.
- Connection Timeouts: These occur when there’s a failure to establish a connection with a payment gateway, often due to server issues or network instability. Prompt notification to system administrators is advised in such cases.
- Read Timeouts: Happen after a connection is made but no response is received to a request. The article suggests sending up to three void transactions to potentially reverse an unresponsive transaction.
- Transaction Identification in Timeouts: In read timeouts, where no transaction identifier is received, using a cross-referencing system with identifiers from the originating system is recommended.
- Essential Timeout Handling Logic: The necessity of having a robust timeout handling logic in place for a reliable Payments API, considering the inevitability of connection-related issues.
Payment API integration advice: tips to follow
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.
1. Password storage
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.
2. Password rotation
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.
3. Keeping a log of requests and responses
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.
4. Maintaining cross-system references
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.
5. Decline and error handling
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.
6. Timeout handling
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.
7. Card data storage and card data flow management
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”.
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.
Payments API Selection
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.
Payments API: types and features
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.
An API for EMV Payment Terminal Solution Implementation
If you want to make your SaaS platform a truly omni-channel one, then you should enable it to support a variety of payment types and methods, including both CNP and card-present transactions. In order to handle card-present transactions your platform should seamlessly interact with EMV payment terminals. Your chosen payment partner’s EMV terminal API might be unable to provide all the functions you need. As a result, you will have to initiate a separate integration project, in order to harmonize it with the main Payments API and add new features.
The distinguishing feature of an EMV payment terminal API is its ability to interact with payment hardware. If you want to interface with specific hardware, you might need, for example, a separate credit card reader API, or other API sub-types.
Lack of a payment terminal API means that your technical personnel will have to perform the respective tasks manually. As a result, payment terminal fulfillment costs might exceed the amounts you expect to save on transaction processing.
An API for Digital Merchant Onboarding
If you decide to implement a payment solution within your SaaS platform, then, you, probably, intend to service a portfolio of merchants. For smooth and seamless digital merchant onboarding you will need a separate API. Thanks to this special API, merchant services will become available to your existing and prospective clients.
When it comes to merchant onboarding, our first advice would be to check the availability of the respective API within your chosen payment partner’s offering and its compatibility with the principal payments API.
Additionally, you should define the target features you expect the digital merchant onboarding API to support. Analysis of these features is especially relevant if you do not intend to add the respective features on premise, using your own team. Keep in mind, that such a project would involve many hours of development efforts, dedicated to design of special forms with numerous fields that prospective merchants need to complete.
Lack of target features within your chosen payment partner’s native merchant onboarding API means that the respective functions have to be performed manually. So, the cost of merchant onboarding will, most probably, offset any savings on transaction processing.
An API for Reporting and Balance Reconciliation
As an omni-channel SaaS platform, you will have to process multiple transactions of various types and keep track of all of them. For this end you will need to keep an elaborate record and generate all kinds of reports. So, in order to lookup all the transactions processed during a specific period and reconcile the balance for this period, you will require a special API. Additionally, a reporting and reconciliation API should be able to generate reports with important data on your payment services, including deposits, chargebacks, and ACH returns.
Without an efficient reconciliation and reporting API, your team will have to reconcile the balances and other data from the reports manually. So, just like in case of other specialized APIs, described in this section, the cost of manual labor might easily offset any potential savings on transaction processing.
An API for Recurring Billing
If your SaaS platform offers services to subscription-based companies, then you will definitely need to support recurring billing functions. While some of them might be already available within the basic payments API, a comprehensive recurring billing solution might call for a special payment integration API. An efficient recurring billing API, capable of smoothly managing customer subscriptions and automatically updating account information, is worth the investment. Savings of time, money, and efforts will compensate its cost in no time. Otherwise, manual subscription management and account updating processes will level all the savings on “cheap” transaction processing.
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.