Intro: why payments API concept is important for your business
Why is the concept of payments API so vital? Accepting payments is an integral part of any business. Therefore, selecting an optimal payment processing or gateway partner is extremely important. At the same time, it is not sufficient to just select the right partner. A lot will also depend on how you are going to handle the payment API integration process.
When selecting vendors, many businesses tend to make their decisions based on the price of the service. While price is, indeed, an important factor, other criteria and significant details may remain overlooked. At the same time, when it comes to payment processing and payment integrations, the devil, generally, hides in the details. Some things and aspects, perhaps unnoticed during the initial payment software product purchase phase (when you are licensing or buying the respective payment solution), might resurface during the coding and integration phase. So, you have to analyze all the important aspects in detail at the start of your project.
The right selection of a payments API and meticulous approach to the integration process stand as determinants of the future success of your SaaS platform. The selected payments API does not have to be the most budget-friendly or the one offering the most visually appealing website and exhaustive documentation. It is imperative to weight various factors, which we discuss below, and carefully approach the payment API integration routine. Even an impeccably designed API can cause problems if mistakes are made during the integration phase.
Now, let us explain why price is not always the most important factor when choosing a payments API and explore other pivotal factors that matter.
In our guide, we’ll be providing detailed insights on how to choose the right payment API for your needs. However, if you have any questions right now, please don’t hesitate to reach out. Schedule a consultation with us
Payments API: flavors and factors to consider
So, what exactly is a payments API? API is short for application processing interface. Most people commonly define payments API as the software logic required to process transactions, such as sales and refunds. For instance, it enables a business to charge customers for online purchases they made.
Examples of the leading payment API providers, frequently mentioned in articles on the subject, include Stripe, Square, Adyen, and others.
People often associate payments APIs exclusively with transaction processing. However, the reality is a bit more complex, as there are additional APIs, which complement the conventional payment API. These related APIs significantly expand the payment management capabilities of your SaaS platform.
Let us take a look at different supportive APIs and explain why they are also important for your business.
EMV Terminal API
A flexible, or should we say omni-channel, SaaS platform must be able to process all payment types its customers need to accept, including card-present transactions. That is why, your SaaS company will, most probably, need to support payment terminal solutions. Support for EMV payment terminals and necessity for smooth interaction with them might require a separate integration sub-project. It often happens that the terminal API provided by your main payment partner either has only a limited feature set, or significantly differs from the principal payments API. As a result, in order to be able to use it, you will need extra time and, possibly, even additional development efforts. So, if you are planning to accept card-present payments, then you need to do some homework on payment terminal support in advance.
Unlike the main transaction processing API, the terminal API is uniquely designed to support functions allowing you to interface with hardware, particularly, payment terminals. EMV payment terminal APIs can be further categorized into more specific types, such as fulfillment API, credit card reader API, and others.
Without an efficient payment terminal API, your team will have to perform various functions related to terminal solution implementation manually. Therefore, all your potential savings on transaction processing will be offset by terminal fulfillment costs.
Merchant onboarding
As a software platform, you will need to seamlessly onboard new merchants and setup merchant accounts. To support these features, you will need a digital merchant onboarding API. Based on this API, merchant services will be provided to your respective customers.
Therefore, first and foremost, you have to verify whether your chosen payment partner offers any merchant onboarding API at all. Additionally, you need to make sure that this API is harmonizable with the basic payments API.
Besides that, you must carefully analyze all the features the onboarding API should support. Preliminary analysis of your target features is even more crucial if you don’t plan to develop the necessary logic in-house and create forms for submitting online merchant applications during the onboarding process. The respective application forms, usually, include multiple fields, so developing the application submission logic on-premise is a considerable challenge.
As we can see, if a merchant onboarding API provided by your chosen partner does not support the target features, you will be unable to effectively onboard and provision new merchants. In such a scenario, even with minimum transaction processing costs, every new merchant onboarding endeavor becomes a drain on your resources, both in terms of finances and time.
Reporting and reconciliation API
It is very important for your SaaS platform to maintain a comprehensive record of all processed transactions and be able to generate diverse types of reports. Reporting and reconciliation API allows you to review the transactions processed during a business day and reconcile it.
Besides processed transactions, the functions of such an API might also include reports on chargebacks, ACH returns, deposits, and presentation of other significant information, regarding provided payment services.
If all the listed functions are provided by the reconciliation API, then they are fully automated. Otherwise, your personnel has to perform the reconciliation manually: download the reports in pdf format and reconcile the data (balances and other) from these reports to make sure that the numbers are correct.
Whatever money you save on transaction processing might not be enough to pay for manual report compilation labor.
Recurring billing
Numerous SaaS platforms provide software to subscription-based businesses, ranging from fitness centers and sport clubs to utility companies and beyond. It is possible that your platform falls within this category. So, if you are planning to process recurring payments, then you should take care of the respective functions. In some cases, these functions are supported by basic payment processing APIs. However, if you have elaborate recurring billing requirements, then you may need a more sophisticated payment integration API to manage subscriptions and process recurring payments. A smooth recurring billing API, equipped with advanced account updater logic and subscription management tools will save you a lot of money and effort. Without such an API savings resulting from low transaction processing costs will make little difference.
When crafting your integration strategy, it is paramount to take all the listed aspects into consideration.
Still have questions about choosing the right Payments API? Let’s chat! Schedule a free consultation with our payment experts, and we’ll address any questions or concerns you may have.
Payments API: pricing and selection criteria
As previously mentioned, while price is an important criterion, it is far from being the only one. Seasoned experts would advise you to opt for the most transparent and straightforward pricing models. The transaction pricing model you are offered should be set forth in a way that allows you to clearly understand how much you are actually paying and what you are paying for. Furthermore, it does not have to be the cheapest option available. Sometimes, it makes sense to pay more for an optimal value-for-money combination. As we can see from the preceding section, it is not the amount you are paying that matters but what you get for it. The functionality you are offered should, first and foremost, perfectly suit your business model and needs. Examples of such needs include EMV terminal solution implementation, merchant onboarding, recurring billing, reporting, payment reconciliation, chargeback handling, and others.
However, don’t forget that even when you choose the best API in terms of functionality and value-for-money, you need to integrate with it in a way that will ensure efficient operation of your platform in future and prevent costly mistakes and losses.
In the next section we will address payment integrations in greater detail and explain how to make your integration project a success.
Need detailed and professional guidance on Payments API pricing and selection? Allow our experts to assist you. Schedule a free consultation today for tailored recommendations.
How to make your payment API integration project a success
During integration, it is important to grasp several important issues, take them into account, and implement them properly. If you neglect or ignore these issues at the outset, they might lead to significant problems down the line.
All integration processes are regulated by PCI DSS standards. So, there are certain requirements that you should adhere to, and, consequently, certain approaches you should apply during the operational phase. Therefore, in order to satisfy the PCI compliance requirements, your integration strategy should cover some key issues.
Let us list some of these crucial points that deserve your attention.
1. Don’t hardcode your passwords!
Regardless of the type of authorization implemented in your system – be it username and password or using a key – the rotation process is mandatory. Passwords, in particular, have to be changed more frequently than keys. In either scenario, at a certain point, authorization data need to be rotated. If you hardcode a password, then every time you need to complete the rotation, you will have to perform a code release. This practice inherently curtails the flexibility of your product. Moreover, a security breach compromising the password could trigger the urgent need for a new release. Release process is not easy, so we strongly advise you to refrain from password hardcoding.
While communicating with the payment gateway, you frequently need to send passwords to the gateway for the purpose of transaction authorization. So, you need to store them securely. To align with PCI requirements and fortify payment security, it is imperative to store your passwords in an encrypted form, using PCI compliant encryption mechanisms, such as the AES 256 algorithm.
2. Organize automated password rotation
Like we said, passwords require frequent rotation. When it is time to change a password, the change should take place both at your platform’s and at the gateway’s end, and it is rather difficult to synchronize these two events. Orchestrating a manual process, where a team member modifies the password at a specific moment, can prove challenging. Any delays or discrepancies in synchronization between your platform and the gateway could potentially result in interruptions to transaction processing.
To prevent transaction processing interruptions during password changes, you can simultaneously support 2 passwords – the current one and the new one. In this case, you can set the new password in advance, prior to rotation. Thus, you won’t have to synchronize the password rotation moment with the time when the password is changed at the gateway’s end. Once the old password stops working (for example, during rotation at the gateway’s end), the new one comes into force. That is, once you get an error message after sending a transaction with an old password to the gateway, you switch to the new password, and, thus, complete the rotation process.
So, the most reliable option is to support usage of two passwords, an old one and a new one, while being able to use them without redeploying the source code. It is essential to note that both passwords should be stored in encrypted form using a PCI compliant algorithm.
The mechanism allows you to keep processing transactions smoothly, regardless of authentication data changes and synchronizations.
3. Log your requests and responses
As your integration goes live, you might receive complaints from your customers or detect some issues at the system level, which will require your prompt attention. For example, some transactions might get declined without apparent cause. Moreover, sometimes, a user might complain about a certain behavior that you are unable to replicate and debug. In these and similar cases it might be useful to have a log of the transactions or API calls, as they might provide some insight into what was going on at the moment when an issue occurred. Thus, you will be able to lookup the details of specific issues and respond accordingly.
So, when exchanging messages with the gateway, in order to keep track of submitted transactions, you should keep a log of your requests and the gateway’s responses. While sensitive fields, such as passwords and card data must be excluded from the logs, you need to log other parameters. Your system should either maintain logs on a regular basis, or have a mechanism of turning them on and off on demand. You may also consider logging fewer details on a regular basis and implementing more detailed logging as part of the debug mode that could be enabled through user interface.
Hence, if any complications arise during processing, the debugging process remains manageable and relatively straightforward. Certain issues can, indeed, be particularly difficult to trace and diagnose due to their sporadic nature, so logs are always a helpful and valuable resource in such scenarios.
4. Maintain cross-system references
One of the main challenges when doing payment integrations is to keep both systems in sync and be able to cross-reference the information from one system within the other. For example, in case of transaction declines the originating system should be able to identify, which transaction has been declined. Under recurring billing scenario, the system should also be able to identify, which customer is associated with a subscription, that is past due.
That is why, when submitting transactions or creating customers and subscriptions in a gateway, you should provide identifiers for these records that would have meaning in your own system. Ideally, you will have corresponding records for these transactions, customers, and subscriptions in your system and be able to supply their identifiers within the corresponding API calls that you send to the gateway.
Thus, the process becomes more transparent and easily traceable. Let us briefly explain how the respective mechanism works.
When you send a transaction to a payment gateway, this gateway will assign its own unique identifier to the transaction. If you are using recurring billing logic, then in addition to transaction identifiers, the gateway will assign unique identifiers to customers and subscriptions. Recurring transactions will be identified based on these values.
However, for you as an integrator it might be difficult to operate the identifiers, generated by the gateway if you have corresponding records (i.e. transactions, customers, subscriptions) in your own database. Therefore, it might be easier for you to locate and lookup records using your own identifiers. So, it is highly advisable to supply your identifiers when processing or creating respective objects, using fields, specially designated for this purpose.
In order to have a clearer picture, it is useful to additionally pass these identifiers from the originating system to the gateway.
Using these identifiers, it is easier to track transactions such as rejects, declines, chargebacks, or ACH returns, because the gateway response can be easily tied to the original transaction within the submitting system. Additionally, if some reports or reconciliation documents are required, the respective data can also be easily tied to the records in the originating system. The approach is much more transparent than keeping track of transactions based solely on the values generated by the gateway.
So, as you are planning your integration, it is essential to identify which fields in the payments API can accept identifiers from your system, and decide which values you are going to pass to the gateway using these fields.
5. Properly handle declines and errors
During integration testing it is generally clear that an approval scenario needs to be implemented and verified. However, it is important to understand that transactions as well as any API calls in general might not always be successful. Therefore, when it comes to payment processing API calls you need to be able to handle decline scenarios.
Declines must be handled in a specific way, depending on the nature of every decline, and on the requirements of your particular system. If you are processing transactions in real time (for instance, e-commerce transactions), then the nature of the decline will not matter and the customer will just have to use a different card. However, if you have a recurring billing system, you might choose to activate different types of functionality depending on the decline, which occurs.
For example, in case of “insufficient funds” you might need to retry the transaction on the day following the decline, while in case of “account closed” scenario, there is no point in retrying the respective transaction. In this case, you might need to contact the customer and ask him to get a new card.
Besides declines, different types of errors may occur. These errors should not result in interruption of your system’s work. Instead, different error scenarios must be envisioned and properly handled by the system.
Errors and declines must be carefully logged in a transparent way. Error and decline logs might be used for further analysis and introduction of necessary adjustments into the integration.
6. Develop timeout handling mechanisms
In addition to declines and errors, there are other scenarios that should be taken into account, especially within payment integrations. We are talking about timeouts.
A timeout is a more delicate issue than an error or decline that should also be addressed in a proper way. Timeouts can be one of the two types: connection timeouts and read timeouts.
Connection timeouts occur when you attempt to connect to a payment gateway, but your request times out before you manage to send any data. Such a timeout can be caused by problems with a server, DNS, or network. In case of a connection timeout, after some time, the platform trying to connect to the gateway receives a timeout message.
If your system receives such a message, it might indicate some broader processing issue, so, it makes sense to notify the system administrator of the potential problem and ask him to look into it.
Read timeout occurs when you successfully connect to a payment gateway and send your request, but receive no response. The transaction may have been processed or not, but without the response, this outcome remains unclear. That is why, a recommended procedure for such cases involves trying to void the transaction, making up to three attempts, usually, performed one after another. The idea is to attempt to void the transaction, and if the initial void is unsuccessful, follow it by two more attempts. This way you increase your chances of reversing authorization of the transaction, if it has taken place, and successfully submitting the next one.
Generally, to send a void request, you should reference the original transaction using its unique identifier. This may create a potential problem in a timeout situation, if you are not assigning your own identifiers to transactions, as recommended above. During a read timeout no response from the gateway arrives. So, there is no gateway-assigned transaction identifier, which could be used for reference. Therefore, read timeouts provide an additional reason to assign identifiers to transactions on the originating system’s end, as these identifiers can be used for reference when attempting to void the transactions during which timeouts occur.
No matter how well the system and the gateway work, timeouts happen on a regular basis. Problems might be caused by issues with databases, Internet connection, or other factors, both on the integrator’s and the gateway’s end.
Therefore, if the integrator wants to have a truly robust API, then he needs to check whether it features the timeout handling logic.
7. Manage card data storage and flow
PCI compliance, the major payment security enforcement paradigm, revolves around two aspects of card data handling: card storage and cardholder data flow (transmission).
When organizing card storage, the integrator has to remember two important points:
- Some values (such as CVV codes) cannot be stored;
- Some values (such as card numbers) can be stored only in an encrypted form using key management approach which might be difficult to implement, especially within the systems that do not specialize in card data handling.
Hence, if you actually need to store sensitive card information, then you have to use some tokenization mechanism and develop a tokenization-based operation strategy. The fundamental principle of tokenization is usage of a token instead of card number during card data storage and transmission.
While most people understand the challenge of credit card data storage and look for payment gateways supporting tokenization, some remain unaware of the limitations related to cardholder data flow.
Many platforms strive to have their own native payment form matching the style of their core application. This allows them to get greater control over the process and make the interface more visually attractive. However, this approach is not secure, because every piece of software code that touches sensitive card data automatically falls within the scope of PCI regulations. This involves risks and potential audit requirements.
Web forms operate as follows: when a user fills out the form and hits the “submit” button, the data from this form is to the server. In case of a payment form this data will also include card number. If that card number reaches the server of the SaaS application, the application immediately becomes exposed to the PCI (PA) DSS regulations.
The situation is even more complex for applications that use AJAX, because the data might end up on the application’s server, even when the user just types it in.
Even though the card number is not stored by the software platform, it still flows through the system, opening the possibility for the server-side code to be compromised and the card data intercepted.
8. Payment pages and proxynization concept
The most common solution to protect cardholder data is usage of payment pages. If you use an external (third-party) payment page, your system never touches card data.
At the same time, many platform owners want to customize their payment pages beyond the extent allowed by the payment page mechanism.
If a payment page is not a suitable solution for you, you can use an approach called proxynization, based on JavaScript and AJAX standards. Proxynization approach allows you to embed a client-side script, which is executed at the browser without sending anything to the software platform’s server, and tokenize the card data before the web form is submitted. This way, when the software platform receives the data from the form, the card number is no longer there, as it is replaced with the token, obtained by the proxynization script.
Proxynization mechanism is generally considered less secure than payment pages. So, not all PCI auditors accept it as a sufficient card data security guarantee. You may want to consult your QSA before undertaking this approach.
You should be especially careful while using proxynization script, when your form is AJAX-based. That is, you should ensure that the fields into which card numbers are input are not synchronized with the server as a cardholder types the values in (a default behavior for a number of AJAX libraries). You need to be sure that the proxynization script has enough time to execute and your server-side code only touches the resulting token and not the original card number.
Want to be sure that your payment API integration will be a success? Talk to our experts. Schedule a consultation with our specialists to go through each step of your payment API integration project
Conclusions
A universal payments API should include many functions, ensuring flexibility and security of payment experience. Truly flexible solutions, such as Zift, feature most of the logic we talked about in the article.
Judging from our experience, the three pillars of a successful payment API implementation are:
- functionality;
- value-for-money, and
- proper payment API integration procedure.
Feel free to consult our specialists to familiarize yourselves with Zift solution powered by UniPay Gateway technology, and learn how your business can benefit from our unified payments API.