Integrating Third-Party Payment Gateways in Your Subscription App

While we use Google Play and Apple App Store because they offer reliable methods for handling in-app payments to manage user subscriptions in Android and iOS, their high commission fees and limited payment methods in most countries make it challenging to meet the diverse user needs. With a target global audience of more than 400 million, catering to users moving across platforms and preferring diverse payment options becomes essential.

We turned to third-party payment gateways as an alternative to address these challenges. This offers greater flexibility, lower costs, and broader regional payment method support.

Architecture Overview

Integrating a third-party payment gateway for a global app with a high user base requires a carefully designed architecture to ensure scalability, reliability, and compliance. We have integrated multiple payment gateways to handle diverse payment methods and provide a seamless subscription experience across platforms.

The architecture, at its core, revolves around modularity and abstraction, enabling support for multiple payment gateways while keeping the implementation flexible and reusable.

In the following sections, we will explain the intricacies of our approach to this integration, starting with the prerequisites and moving on to advanced considerations like managing the subscription lifecycles across regions.

Prerequisites

Before diving into the API documentation or writing code, there are a few necessities to prepare for ensuring a seamless integration process. The following are the key steps and checks to undertake:

• Choosing the right payment gateway: Select a gateway that meets the functional needs, such as supporting specific payment methods and currencies, supporting the target regions, and complying with the region-specific regulations.
• Setting up the Banking infrastructure: Ensure that your business has a compatible merchant account that supports the required currencies and transactions and meets the gateway requirements.
• Understand the gateway requirements: Familiarize yourself with the gateway’s prerequisites, such as API Keys, webhooks, and other integration-specific details.

Payment Gateway Configuration

After we have selected the payment gateway, the next step is to configure it. This step typically includes:

• Credential Setup
• Generate and configure the API Keys, webhook tokens, and other secrets for live and test mode.
• Webhook configuration
• Subscribe to payment-specific events by setting up webhooks to receive real-time transaction updates.
• Product Configuration
• Define and configure products with region-specific pricing and currencies, such as subscriptions or one-time purchases. Generally, the products need to be set up separately for live and test modes.

While exact configuration details vary across gateways, these are the foundational steps required for most integrations.

Order Creation

Order creation at the gateway involves generating a client-specific secret or token for each payment request. The client requests the server with necessary parameters such as productID, currency, quantity, and user details. The server uses this information to create an order in the payment gateway and returns a secret, along with other necessary information, to the client. The payment gateway credentials, securely stored on the server, generate the secret mentioned above. This ensures that a layer of abstraction is created and sensitive information, such as API keys, remains protected and is never exposed to the client.

The client uses the information returned from the server to make a payment request to the gateway. The gateway validates the request body and verifies the transaction details against the server's order. Once validated, the payment gateway handles the payment processing according to the configuration.

Handling Events and Managing the Subscription Lifecycle

Once the gateway verifies the payment, an event is generated and transmitted to the server through the webhook endpoint configured during the earlier steps (see the Prerequisites section). Upon receiving the event, signature verification is first performed to verify that the message is generated from a trusted source.

A response is promptly sent back to the gateway based on the signature verification and message parsing. This fail-fast approach ensures that discrepancies result in immediate failure response, maintaining a secure and reliable setup.

The parsed response is modified to a standard template and published to a messaging queue, which acts as a buffer for asynchronous processing. Various listeners deployed across multiple data centers consume messages from the queue using a retry mechanism to ensure reliability. Depending on the event type, the consumer service updates the user's subscription state accordingly. This ensures a robust, scalable, and fail-safe approach to handling webhooks.

Testing Strategy

With the integration of a third-party payment gateway, rigorous testing becomes necessary to ensure that the user subscription lifecycle is handled seamlessly. Most gateways provide separate test and live modes, each with distinct credentials. To imitate dummy payments, the test mode generally requires a configuration similar to that of the live mode.

To simplify testing, especially for live clients, the server uses a unified order creation and webhook endpoint for both the test and live users. The server maintains a whitelist of phone numbers designated for testing purposes. When the client requests an order creation, the server checks the user's user identity against the whitelist. Based on the result, the server creates the order using either the test or live credentials and sends a request to the payment gateway.

We keep the webhook processing logic the same for both test and live users. This strategy ensures consistency, while the whitelisting mechanism allows seamless testing without the disruption of the production environment. This approach ensures that the integration remains robust and error-free.

Challenges

Handling payments at scale introduces various complexities. Below, we outline some critical challenges encountered and how we handled them.

Handling Payments in EU and Non-EU Regions

Processing payments across multiple regions, especially EU and non-EU regions, presents its own set of challenges, primarily related to legal compliance. Different geographical regions enforce distinct regulations on how data should be processed and stored, requiring a region-specific, tailored approach to ensure compliance.

In our architecture, once the data is published to the messaging queue, multiple consumer services deployed in different regions process it. The user's region is determined based on the user-specific data present in the event. This ensures that the data is processed only by the consumer service that complies with that region's legal requirements.

Segregating the data processing tasks regionally helps us provide a seamless payment experience to users across regions while maintaining data compliance.

Designing a Reusable Framework for Multiple Payment Gateways

As mentioned earlier, most payment gateways have the same flow for creating orders and processing payments: order creation → payment processing → transaction verification → webhook events. Although the flow remains consistent, each gateway typically uses its message format for webhook events.

We designed a reusable framework for subscription processing to avoid duplication of development efforts and streamline the handling of the subscription lifecycle across gateways. The webhook message from all payment gateways is transformed into a standard message format before being published to the messaging queue.

By normalizing the message format, the subscription processing logic remains consistent, regardless of the payment gateway. This approach reduces complexity making it easier to integrate different payment gateways seamlessly.

Securing Public Endpoints for Webhooks

Since the webhook endpoints are publicly accessible, they require robust security measures to ensure that subscriptions are only granted to users who have legitimately completed their payments. Most payment gateways have out-of-the-box support for signing the event payload using a secret key. Upon receiving a webhook request, our server verifies the signature to confirm its authenticity.

In addition to the signature verification, we validate that the request originates from an authorized payment gateway IP address, adding an extra layer of security by ensuring that unauthorized sources cannot send malicious content.

Many payment gateways include a timestamp in the signature and/or the encrypted payload to prevent replay attacks. By checking this timestamp, we ensure that an attacker does not use an old or repeated payload to simulate a Denial of Service(DoS) attack.

Only after passing all these checks, the webhook request is processed further. If any of these validation fails, the server promptly rejects the request, maintaining the system's integrity.

Retry Mechanism for Webhook Processing

As shown in the architecture diagram above, webhook processing failures can occur primarily at two points:

• During transmission from the gateway to the public endpoint, this can happen due to a corrupted message or other issues with the payload.
• During consumer service message consumption, errors might occur while reading and processing messages from the messaging queue.

In the first case, when the server detects the message to be corrupted or invalid, it returns an error to the payment gateway. The gateway then retries sending the message, following its retry mechanism.

We follow a fail-fast principle in our approach. Once the webhook message is successfully decrypted and mapped to the gateway-specific message model, the server promptly responds successfully to the gateway. In most scenarios, replaying a successfully processed message from the gateway is not straightforward. Hence, once a successful response is sent, we are responsible for ensuring proper event processing. Once the standardized message is published to the messaging queue and the consumer service tries to process the message, unforeseen issues may arise. In such cases, the consumer service does not acknowledge the message. After multiple retries, the message is moved to a secondary queue, commonly referred to as a dead-letter queue (DLQ). Alerts are triggered in case a message is published to the DLQ, prompting manual intervention by developers to address and process such cases.

Although failures leading to DLQ publishing are rare, they are not entirely avoidable. By implementing this retry mechanism and fail-safe approach, we ensure robust webhook processing with minimal disruption.

What’s Next

Integrating various third-party payment gateways has been a valuable endeavor for Truecaller, enabling us to offer a seamless payment experience globally.

With this guide, you now have a high-level blueprint and architecture for integrating third-party payment gateways into your global app, along with insights into the challenges you need to prepare for. Start by exploring gateways that align with your business needs, implementing robust architecture, and adapting to regional compliance requirements. With this foundation, you are ready to enhance your app's payment capabilities and scale seamlessly.