How to overcome 3 payment API integration challenges

When technology works as it should, we barely notice it’s there at all. When you’re watching TV, you’re not thinking about its semiconductors, circuit connections, input sockets and cables. That is, until the picture starts to distort or the sound disappears. Then you’re suddenly very interested in how all the components fit together and interact.

Ideally, you wouldn’t have to overthink your payment gateway integration, either. You want to take electronic payments from customers, and the payment API connects your website (or app) to the payment gateway. 

You choose the optimal configuration at the sign-up stage, then go ahead with it. Minimal stress. 

But, as any payment manager knows, the course of payment gateway integration never did run smooth. Bugs in your API set-up can impact the checkout experience, returning false declines. You’ll lose sales and damage customer trust if your gateway connection is faulty.

To put it plainly: payment API integration errors impact your acceptance rate (AR), and prevent your business from earning revenue to grow and scale. Your long-term success hinges on a brilliant API integration. 

When you don’t know what’s wrong with your integration, you can’t fix it. We’ll explain more about overcoming unseen API errors at the end of this blog – plus a tool that can achieve a 1.6% AR uplift within a day.

But first, let’s look at two common problems with integrating a payment gateway – you’ll want to consider these prior to signing up for the payment gateway in the first place.

Problem #1: Difficult integrations take too much time to implement

The more customization you require, the more time you’ll need to build the payment API integration. At the same time, the pressure is on, because your business needs a reliable way to accept online payments. In reality: the sooner you can complete the integration, the sooner you can benefit from the new revenue stream.

When you need to make updates to your payment gateway integration – such as adding new payment methods or changing fraud detection logic – you’re relying on that integration to be adaptive and customizable.

Unfortunately, some integration methods require hand-coding an entirely new piece of code each time you add a new payment method (such as Apple Pay, Kakao Pay or WeChat Pay). This is laborious, time-intensive, and requires repetitive engineering work. It’s a drain on resources that’s not always cost-effective.

Solution: Choose an API integration type that match your resources

Although timelines for implementation vary hugely depending on business needs, available resources and market conditions, you should still seek a clear overview of the effort needed to connect the payment API you’re considering. You can read our comparison of direct integration vs integration via PSP for your online payment gateway, to help you weigh the options.

Overall, you should consider the nature of the payment gateway API you’re most in need of. It’s important to be transparent with your potential PSP about the amount of engineering muscle you can realistically contribute to the integration process. If you need something simpler, more adaptable or more flexible than the solution you’re looking at, say so!

Alternative to a payment gateway API integration

If a full API integration is looking too complex, you could use a simpler option such as Flow, which can be integrated within a week. Flow allows you to add new payment methods easily (without code) once the initial implementation is complete. 

Solution: Locate documentation for different payment integration types

For all of our payment gateway integrations – including the more complex ones – we provide clear API reference documentation. For any payment gateway you’re considering, encourage your engineers to look at the available docs as early as possible in the process of gathering information. This will help them to get a better idea of the structure and functionality of the APIs in question.

Merchants processing payments with Checkout.com use our API to validate the payment methods available for processing before making a payment request. For example, you will only see payment methods such as Klarna, GooglePay and Apple Pay if these are all active and available to use.

Mobile payment gateway API integration

If you’re looking for mobile payment gateway integration, you can take a look at our mobile SDK documentation. This is relevant for merchants looking to take payment through iOS or Android mobile apps.

Ecommerce payment gateway API integration

You’ll need a different set of instructions for connecting a payment gateway to an ecommerce platform. You must download a specific plugin and obtain the correct API keys before you can carry out test payments.

Problem #2: Payment gateway and acquirer are owned by different parties

The distinction between a payment processor and merchant acquirer is an important one. The PSP you purchase your payment gateway API access from may not own and operate any other stages of the transaction lifecycle. That causes data loss – and unclear decline reasons.

For example, a transaction could look like this:

1. Customer enters payment details in your website (owner: you)‍
2. Payment gateway handles payment details (owner: vendor A)
3. Payment gateway requests authentication from separate entity (owner: vendor B)
4. Payment gateway sends data for fraud checks (owner: vendor C)
5. Payment gateway passes transaction to payment processor (owner: vendor D)
6. Payment processor contacts schemes, which contact issuer and acquirer (owner: vendor E)

Let’s say the payment request is declined. When the response has passed through a minimum of six parties, it’s almost impossible to track the reason for the decline.

All you see is the response from the payment gateway: transaction failed. When your payment API call delivers no tangible information about the reason behind the payment decline, there’s very little you can do to rescue the transaction. Your customer refuses to retry a false decline, and the revenue is lost to competitors. Big problem.

Solution: A PSP which owns the entire transaction lifecycle

Your payment tech stack may be complex, with multiple payment gateways. You should consider how much visibility you have into transaction lifecycle data from each one. Ask your PSP whether you can have more information about why your payments are failing, and how you can reduce false declines.

It’s often most efficient to have a centralized solution. Checkout.com is a full stack processor-acquirer, meaning data is available from all stages of the transaction lifecycle. 

So your checkout could look like this:

1. Customer enters payment details in your website (owner: you)
2. Payment gateway handles payment details (owner: Checkout.com)
3. Payment gateway requests authentication from separate entity (owner: Checkout.com)
4. Payment gateway sends data for fraud checks (owner: Checkout.com)
5. Payment gateway passes transaction to payment processor (owner: Checkout.com)
6. Payment processor contacts schemes, which contact issuer and acquirer (owner: Checkout.com)

If the payment is declined, then a call to the Checkout.com Unified Payments API (UPAPI, for short) can retrieve more data than a standalone payment gateway, so you can learn more about why the payment declined. 

Checkout.com owns products in each stage of the transaction lifecycle, so we can offer actionable insights, raw decline codes, next step recommendations, and more. Access to this data helps you to make meaningful adaptations to your payment strategy. UPAPI means all payment processing, analytics, and reporting can take place on one platform. 

Consolidating payment service providers under fewer gateways can also help reduce maintenance overhead. So there’s a financial benefit in addition to efficiency gains.

Problem #3: You don’t even know if your integration is correctly configured

Lack of visibility into API integration functionality is a common frustration for payment managers. You may be experiencing problems with false declines, customer complaints and technical issues – yet not know why.

Bugs in payment gateway integration can be really hard to detect. Think back to the television example; the picture is going fuzzy but there’s no clear reason why. It’s tricky to figure out the workings of a black box. Similarly, it’s tough to troubleshoot a faulty payment API integration. 

There are many reasons it’s hard to manually fix errors in your payments API, such as:

• There’s a lot of code to scroll through, and it’s easy to skip over sections you’re already familiar with and assume there’s nothing wrong there
• Your engineers are less experienced with online payment integration, and it’s unrealistic to expect effective troubleshooting
• Even if you do notice errors, you may not know how to fix them because payment systems are complex and industry standards update often‍
• There may be nothing obviously wrong, but your payments are failing because you’re not including enough data in your payment requests

A common example of a problem with your payment gateway integration is sending merchant-initiated transactions (MIT) with incorrect formatting. When submitting a recurring transaction request, you must include the previous payment ID. 

Yet the API integration can be configured wrongly, such that the logic to pull up the previous payment ID is faulty. The wrong data is pulled in, and the payment fails. Of course, this is the same script used for every identical type of payment, so all of your recurring MITs will fail. 

We’ll look at how to resolve this below.

Solution: Gain a clear overview of your integration integrity on a live dashboard 

While an engineer from your payment services provider (PSP) could investigate issues with your integration and suggest some solutions, this takes a lot of back-and-forth. It may not be the quickest or most effective way to resolve API integration issues. 

To help you fix API integration errors faster, our new Integration Health dashboard feature pinpoints problems and offers self-serve troubleshooting. That means you’ll see a clear list of your current integration issues plus plain English suggestions on how to resolve each one. Bugs are listed in order of impact on your acceptance rate.

The tool gives you an integration health rating on a scale of “very poor” to “very good” to help you easily understand the quality of your payment gateway API integration. If you have lots of errors, you’ll score lower on the scale. Resolving bugs will nudge you up towards “very good”.

You’ll see the number of transactions affected by your integration issues, followed by a list of issues you ought to fix. Each integration error will have its own rating of low, medium or high impact on your acceptance rate to help you prioritize the most valuable use of your time and resources.

As for resolving faulty merchant-initiated transactions, the Integration Health dashboard view contains a quick overview of scheme requirements for previous payment IDs. If you need more information, you’d follow the link to the more detailed documentation. 

Each integration issue comes with a pop-up box that gives instructions to resolve it, as above.

How effective is the Checkout.com Integration Health tool?

Searching online or waiting on email responses isn’t always the best experience when your revenue is at stake. Our team built Integration Health to enable you to understand and remedy your own revenue-harming API bugs. You can see important acceptance rate uplift by taking action on the API flaws identified.

Based on in-house tests, the team behind the tool estimates an acceptance rate uplift of around 0.47% from fixing basic integration issues that would take a merchant roughly one day to fix.

To give another example, one of our fintech merchants could see 1.6% AR uplift from fixing three errors identified by Integration Health. Our engineers estimate these would take less than a day to fix. That’s a very short time to make significant revenue gains.

Benefit from a custom-built unified payments API integration

Maintaining a single, modern API to process payments is easier for an engineering team than maintaining a host of inefficient legacy APIs. But aside from keeping the engineering team happy, a single API provides additional efficiency benefits including simplified integration with other systems, streamlined reporting and analytics, reduced risk of errors, and the ability to rapidly adapt to changing business needs.

An API integration that delivers actionable payments data is just one of the many routes to improving payment acceptance rates. Find more about rescuing failed payments in our Acceptance Rate Playbook.