Integrating Payment Gateway SDKs and Payment Workflows in React Native

Course: React Native Training

Topic: Integrating Payment Gateway SDKs and Payment Workflows

Course Link: React Native Training at JustAcademy

Demo Link: Register for a Course Demo

JustAcademy Website: Visit JustAcademy

1. Introduction to Payment Gateway Integration

Payment gateway integration is the process of connecting a mobile application to a payment service that securely processes transactions between customers, merchants, banks, and payment networks. In React Native, developers integrate payment gateway SDKs or hosted payment interfaces to allow users to purchase products, subscribe to services, book appointments, or pay for digital services.

A payment gateway typically provides tools for collecting payment details, initiating transactions, authenticating customers, processing payments, and reporting transaction results. The exact workflow depends on the provider, payment method, country, and type of transaction.

For example, an e-commerce application may allow a customer to add products to a cart, proceed to checkout, select a payment method, complete authentication, and receive an order confirmation after the payment has been verified.

1.1 What Is a Payment Gateway?

A payment gateway is a service that securely facilitates payment transactions between a merchant application and the payment processing ecosystem. It may provide SDKs, APIs, hosted checkout pages, transaction status notifications, refunds, and reporting tools.

1.2 What Is a Payment SDK?

A Software Development Kit (SDK) is a collection of libraries, methods, configuration options, and tools provided by a payment provider. A mobile SDK can simplify payment collection, display supported payment interfaces, handle redirects, and return client-side transaction results.

1.3 Why Integrate a Payment Gateway?

• Accept online payments from customers.
• Support payment methods offered by the selected provider.
• Reduce the need to build payment processing infrastructure from scratch.
• Improve checkout usability with supported payment interfaces.
• Track transaction statuses and handle payment failures.
• Support refunds and reconciliation through the provider's APIs.
• Integrate payment confirmation with order management.

2. Understanding the Payment Ecosystem

A payment transaction can involve multiple parties. Understanding their responsibilities helps developers design secure and reliable workflows.

2.1 Basic Payment Flow

Customer
   |
   v
React Native Checkout Screen
   |
   v
Merchant Backend
   |
   v
Payment Provider
   |
   v
Payment Processing and Authentication
   |
   v
Transaction Result
   |
   v
Backend Verification
   |
   v
Order Confirmation in the App

The app may display a preliminary result returned by the SDK, but the backend should establish the final order status using trusted provider data. A successful-looking screen or a client-side callback alone is not sufficient proof that money has been received.

3. Types of Payment Gateway Integration

3.1 Native Payment SDK Integration

A native payment SDK provides platform-specific or React Native-compatible tools to integrate payment functionality into an application. It can offer native checkout screens, payment methods, authentication handling, and transaction callbacks.

Advantages:

• Provides a mobile-oriented checkout experience.
• Can support native payment methods and authentication flows.
• Reduces the amount of payment interface code developers must write.
• May offer provider-specific payment status and error information.

3.2 Hosted Checkout Integration

Hosted checkout redirects or opens a provider-controlled payment page where customers enter payment details. After the payment attempt, the customer may return to the application through a configured redirect or deep link.

This approach can reduce the amount of sensitive payment information handled directly by the application, but the merchant must still follow applicable security and compliance requirements.

3.3 Payment API Integration

Payment APIs allow the merchant backend to create orders, initiate supported payment operations, check transaction status, and process refunds. The React Native app typically communicates with the merchant backend rather than directly using privileged provider credentials.

3.4 Choosing an Integration Method

4. Popular Payment Providers for React Native

Payment providers differ in supported countries, currencies, payment methods, transaction fees, SDK capabilities, and business requirements. Always consult the provider's current documentation before selecting an integration.

4.1 Razorpay

is commonly used for online payments in India. Its React Native integration supports a checkout workflow that involves creating an order on the merchant server, opening checkout in the app, and verifying payment details on the server.

Documentation: Razorpay React Native Integration Guide.

4.2 Stripe

provides a React Native SDK with native payment interfaces and PaymentSheet. The SDK can send sensitive payment details directly to Stripe rather than passing them through the merchant's own server.

Documentation: Stripe React Native SDK and Documentation.

4.3 How to Select a Provider

• Check whether the provider supports the countries where your customers live.
• Confirm support for your required currency and payment methods.
• Review SDK compatibility with your React Native version and build setup.
• Understand transaction fees, settlement periods, and refund policies.
• Review documentation for webhooks, signature verification, and error handling.
• Confirm compliance with app-store rules for the type of product being sold.

5. Planning the Payment Workflow

A payment workflow describes the steps between a customer selecting a purchase and the merchant confirming the resulting transaction. Designing the workflow before writing code reduces errors and helps the application handle unsuccessful or interrupted payments.

5.1 Step-by-Step Payment Workflow

1. Product selection: The customer chooses a product or service.
2. Checkout review: The application displays the order summary, quantity, applicable taxes, discounts, and total amount.
3. Backend validation: The server validates product availability, pricing, discounts, and the customer's authorization to place the order.
4. Order creation: The server creates an internal order and, where required, a corresponding order with the payment provider.
5. Checkout initialization: The app receives the necessary non-secret checkout information from its backend.
6. Payment initiation: The customer selects a supported payment method and completes the checkout flow.
7. Authentication: The provider may request additional verification, depending on the payment method and applicable rules.
8. Payment verification: The backend verifies the provider's response or signature and checks the authoritative transaction status.
9. Order update: The backend changes the order to the appropriate state only after the required payment conditions are satisfied.
10. Confirmation: The application displays a confirmation or a clear next step.

5.2 Payment Workflow Diagram

Customer selects a product
          |
          v
Review checkout and total
          |
          v
Backend validates the order
          |
          v
Create internal/provider order
          |
          v
Open payment SDK or hosted checkout
          |
          v
Customer completes payment attempt
          |
          v
Backend verifies payment status
          |
          +-----------------------+
          |                       |
          v                       v
Payment confirmed           Payment not confirmed
          |                       |
          v                       v
Mark order paid             Keep order pending/failed
          |                       |
          v                       v
Show confirmation           Offer safe next steps

6. Preparing a React Native Project

Before installing a payment SDK, review the provider's installation guide and check the required React Native version, supported operating systems, native dependencies, and development environment.

6.1 Check Project Compatibility

• Confirm that the project uses a supported React Native version.
• Check whether the SDK supports Android and iOS.
• Review native build requirements and any required permissions.
• Determine whether the project uses Expo or React Native CLI.
• Check whether a development build is required instead of Expo Go.
• Verify that the provider supports the intended payment methods and business location.

6.2 Installing an SDK

For example, the Razorpay React Native SDK is distributed through npm. Install the version recommended by its current integration documentation.

npm install react-native-razorpay

Note: The installation command is provider-specific. Installing a package does not complete the payment integration. Native dependencies, platform configuration, backend endpoints, and provider dashboard settings may also be required. Follow the SDK's official installation instructions for your project.

7. Creating a Secure Backend Payment Endpoint

A secure payment architecture uses a merchant backend to validate order information and communicate with the provider. The app should not determine the final price solely from values supplied by the customer or expose private payment credentials.

7.1 Responsibilities of the Backend

• Authenticate the customer where required.
• Retrieve authoritative product prices from the database.
• Calculate the payable amount and currency.
• Create an internal order with a unique identifier.
• Create a payment order with the provider when required.
• Return only the information needed to initialize checkout.
• Verify transaction details and process signed webhook events.
• Update order status and support safe retries.

7.2 Example Backend Endpoint Using Node.js

The following is a simplified Express example. It demonstrates the general structure of an order-creation endpoint; the provider-specific API call and database functions must be implemented using the selected provider's official server SDK and your application's data model.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/api/checkout/create-order', async (req, res) => {
  try {
    // Authenticate the customer using your middleware.
    const userId = req.user?.id;

    if (!userId) {
      return res.status(401).json({
        error: 'Authentication required',
      });
    }

    const { productId, quantity } = req.body;

    if (
      typeof productId !== 'string' ||
      !Number.isInteger(quantity) ||
      quantity < 1 ||
      quantity > 20
    ) {
      return res.status(400).json({
        error: 'Invalid order details',
      });
    }

    // Load the product and price from your database.
    const product = await findProduct(productId);

    if (!product || !product.isAvailable) {
      return res.status(400).json({
        error: 'Product is unavailable',
      });
    }

    const amount = calculateOrderAmount(product, quantity);

    // Persist the internal order and create the provider order
    // using the provider's official server-side SDK.
    const order = await createPendingOrder({
      userId,
      productId,
      quantity,
      amount,
      currency: 'INR',
    });

    const checkout = await createProviderOrder({
      internalOrderId: order.id,
      amount,
      currency: 'INR',
    });

    return res.status(201).json({
      orderId: order.id,
      checkoutOrderId: checkout.id,
      amount,
      currency: 'INR',
      publicKey: process.env.PAYMENT_PUBLIC_KEY,
    });
  } catch (error) {
    return res.status(500).json({
      error: 'Unable to initialize checkout',
    });
  }
});

This is a teaching example, not a complete deployable backend. Functions such as findProduct, calculateOrderAmount, createPendingOrder, and createProviderOrder are placeholders. The example also assumes authentication middleware that attaches a verified user to req. Add database transactions, input validation, idempotency, rate limiting, and appropriate error handling before production use.

7.3 Why the Backend Calculates the Amount

Imagine a product costs ₹1,500. A malicious user might modify the amount sent from the mobile app to ₹1. If the backend blindly trusts that value, the customer may be charged an incorrect amount.

The server should retrieve the product price, validate quantities and discounts, calculate the total, and create the payment order using the verified amount. The app may display the total, but the server must remain authoritative.

8. Integrating a Payment SDK into a React Native Screen

The mobile screen should initiate the checkout workflow, handle the SDK's result, and request payment-status confirmation from the backend. The exact SDK calls depend on the selected payment provider.

8.1 Example: Razorpay Checkout

The following example illustrates the client-side structure of a Razorpay checkout flow. It assumes that a backend endpoint creates a provider order and returns the required checkout fields. The endpoint must be implemented securely before this code can work.

import React, { useState } from 'react';
import {
  View,
  Text,
  Alert,
  ActivityIndicator,
} from 'react-native';
import RazorpayCheckout from 'react-native-razorpay';

export default function CheckoutScreen() {
  const [loading, setLoading] = useState(false);

  const handlePayment = async () => {
    if (loading) return;

    setLoading(true);

    try {
      const response = await fetch(
        'https://your-api.example.com/api/checkout/create-order',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            // Add your application's access token securely.
          },
          body: JSON.stringify({
            productId: 'product_123',
            quantity: 1,
          }),
        }
      );

      if (!response.ok) {
        throw new Error('Unable to create payment order');
      }

      const order = await response.json();

      const result = await RazorpayCheckout.open({
        key: order.publicKey,
        amount: order.amount,
        currency: order.currency,
        name: 'Example Store',
        description: 'Product purchase',
        order_id: order.checkoutOrderId,
        notes: {
          internalOrderId: order.orderId,
        },
        theme: {
          color: '#2563EB',
        },
      });

      // Send the provider response to your backend for verification.
      const verifyResponse = await fetch(
        'https://your-api.example.com/api/checkout/verify',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            internalOrderId: order.orderId,
            razorpay_order_id: result.razorpay_order_id,
            razorpay_payment_id: result.razorpay_payment_id,
            razorpay_signature: result.razorpay_signature,
          }),
        }
      );

      if (!verifyResponse.ok) {
        Alert.alert(
          'Payment submitted',
          'We are verifying your payment. Check your order status shortly.'
        );
        return;
      }

      const verification = await verifyResponse.json();

      if (verification.status === 'paid') {
        Alert.alert(
          'Payment successful',
          'Your order has been confirmed.'
        );
      } else {
        Alert.alert(
          'Payment pending',
          'Your payment status is still being checked.'
        );
      }
    } catch (error) {
      // A checkout rejection is not always proof that no payment occurred.
      Alert.alert(
        'Payment status unavailable',
        'Check your order status before trying again.'
      );
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text style={{ fontSize: 22, marginBottom: 16 }}>
        Checkout
      </Text>

      {loading ? (
        <ActivityIndicator size="large" />
      ) : (
        <Text onPress={handlePayment}>
          Pay Now
        </Text>
      )}
    </View>
  );
}

Important implementation notes:

• Replace the example backend URL with your real HTTPS endpoint.
• Implement the verification endpoint on the server; do not trust a client-supplied signature check.
• Verify the signature using the provider's documented algorithm and the original server-side order ID.
• Check the authoritative payment status and required capture state before marking the order as paid.
• Use the backend's authenticated user context to authorize access to the internal order.
• Ensure the response field names and amount units match the installed SDK and provider documentation.
• Use a proper accessible button component rather than relying on a plain text press handler in production.
• Use an idempotent backend verification process and handle delayed webhook events.

The SDK callback is a useful signal to begin verification, not a replacement for server-side verification. A network timeout or a closed checkout screen does not always mean the payment failed.

9. Server-Side Payment Verification

Payment verification confirms that the transaction details returned by checkout are authentic and correspond to the expected order. It helps prevent forged success messages and unauthorized order updates.

9.1 Why Verification Is Necessary

• Client-side values can be modified by an attacker.
• A payment screen may return before the final transaction status is known.
• Network interruptions may prevent the app from receiving a result.
• The provider may authorize a payment without completing capture or settlement.
• Orders must not be fulfilled based solely on a user-controlled success screen.

9.2 Example Verification Logic

For Razorpay, signature verification uses the provider's documented server-side procedure. Conceptually, the server should retrieve the original order from its database, validate the relationship between that order and the payment response, and compare the generated signature with the received signature.

// Illustrative pseudocode for backend verification.
// Use the official provider SDK in your actual backend.

async function verifyPayment({
  internalOrderId,
  paymentId,
  providerOrderId,
  signature,
}) {
  const order = await findOrderById(internalOrderId);

  if (!order) {
    throw new Error('Order not found');
  }

  // Confirm that the order belongs to the authenticated user.
  // Confirm that the provider order ID matches the stored ID.
  // Verify the signature using the provider's server-side SDK.
  // Fetch/check payment status when required.
  // Validate amount, currency, capture status, and order state.
  // Update the order atomically and idempotently.

  return await completeVerifiedPayment({
    order,
    paymentId,
    providerOrderId,
    signature,
  });
}

This pseudocode intentionally leaves the cryptographic implementation to the provider's official SDK. Never implement a payment verification process by merely comparing two untrusted client values or accepting a client-provided status string.

Reference: Razorpay's official React Native integration documentation.

10. Webhooks and Asynchronous Payment Updates

A webhook is a server-to-server notification sent by a payment provider when an event occurs. For example, a provider may notify the merchant backend when a payment succeeds, fails, is captured, or is refunded.

10.1 Why Webhooks Matter

• The customer may close the application before checkout finishes.
• The mobile network may disconnect during payment processing.
• The provider may update a transaction after the initial checkout response.
• Refunds and other transaction events may happen later.
• Webhooks allow backend workflows to continue even when the app is offline.

10.2 Typical Webhook Workflow

1. The merchant registers a webhook endpoint with the payment provider.
2. The provider sends an event to the endpoint.
3. The backend validates the webhook signature using the raw request body and configured webhook secret as required by the provider.
4. The backend checks the event type and related transaction or order.
5. The event is recorded and processed safely.
6. The order or refund status is updated according to the verified event.
7. Duplicate events are handled without repeating the business operation.

10.3 Webhook Security Checklist

• Use HTTPS for public webhook endpoints.
• Validate provider signatures before trusting the payload.
• Store webhook secrets only on the server.
• Use event IDs or other suitable identifiers to prevent duplicate processing.
• Handle retries and out-of-order event delivery.
• Keep an audit trail of relevant payment state changes.
• Do not expose webhook endpoints as trusted merely because they receive JSON.

11. Managing Payment States

Payments can pass through several states. A well-designed application should distinguish a checkout attempt from a confirmed, captured, or refunded transaction.

Exact state names and transitions differ by provider. Define a documented internal state model and map provider-specific events to that model instead of assuming every gateway uses identical statuses.

12. Handling Payment Errors and Retries

Payment errors can result from invalid payment details, authentication failure, insufficient funds, unsupported payment methods, provider outages, network issues, or user cancellation.

12.1 Common Payment Problems

12.2 Safe Retry Strategy

1. Prevent repeated taps while the checkout request is being initialized.
2. Store an internal order ID for the current checkout attempt.
3. When a timeout occurs, check the existing order and payment status.
4. Do not create a second charge simply because the app did not receive a callback.
5. Use idempotency keys where supported by the provider and endpoint.
6. Offer a new payment attempt only when the previous transaction's state allows it.
7. Show a pending or support message if the result cannot yet be confirmed.

13. Security Best Practices for Payment Integration

Payment workflows require special care because errors can lead to financial loss, fraudulent orders, or exposure of sensitive information.

13.1 Protect Payment Credentials

• Never include private API secrets in React Native source code.
• Use public client keys only where the provider explicitly permits them.
• Store private credentials in secure server-side configuration or a secrets manager.
• Rotate compromised credentials promptly.
• Avoid logging payment secrets, access tokens, or sensitive customer information.

13.2 Protect Transaction Integrity

• Calculate prices and totals on the backend.
• Validate the internal order and customer ownership.
• Verify signatures using the provider's official procedure.
• Check the expected amount, currency, payment ID, and order ID.
• Confirm capture or other required completion status before fulfillment.
• Use atomic database updates and idempotent processing.

13.3 Protect Customer Data

• Prefer provider-managed payment interfaces and tokenization where suitable.
• Avoid storing raw card numbers or security codes in application databases.
• Collect only the customer information required for the transaction.
• Use HTTPS for communication between the application and backend.
• Apply appropriate authentication, authorization, logging, and access controls.
• Review applicable PCI DSS requirements and local payment regulations.

13.4 App Store Payment Policies

Payment gateway integration is not appropriate for every type of in-app purchase. Digital subscriptions, virtual currency, premium app features, and other digital content may be subject to Apple App Store or Google Play billing rules. Physical goods and certain real-world services may follow different rules.

Before choosing a gateway, review the current platform policies for the specific product, region, and distribution model. Do not assume that a third-party payment SDK is permitted for every digital purchase.

14. Testing Payment Workflows

Payment integration must be tested thoroughly before release. Use the provider's test environment and documented test credentials rather than real customer payment details during development.

14.1 Important Test Scenarios

• Successful payment.
• Declined payment.
• Customer cancellation.
• Authentication challenge failure.
• Network disconnection during checkout.
• Backend timeout after payment submission.
• Duplicate payment button taps.
• Duplicate webhook delivery.
• Delayed payment confirmation.
• Invalid or mismatched signature.
• Incorrect amount or currency.
• Refund initiation and completion.
• Application restart while an order is pending.

14.2 Test Environment and Live Environment

14.3 Production Readiness Checklist

• All payment flows have been tested in the provider's test environment.
• Backend signature verification is implemented and tested.
• Webhook signature validation is enabled.
• Duplicate events and requests are handled safely.
• Order status is updated only after verified payment conditions are met.
• Refund and reconciliation procedures are documented.
• Secrets are stored securely and are not bundled into the app.
• Error messages do not expose sensitive internal details.
• Monitoring and support procedures are ready.
• Platform billing policies and provider requirements have been reviewed.

15. Practical Project: Build a Checkout Workflow

Project objective: Develop a React Native checkout feature that connects a product screen to a secure backend and a payment gateway.

15.1 Required Features

• Product selection and order summary.
• Server-calculated checkout total.
• Backend order creation.
• Payment SDK or hosted checkout integration.
• Server-side payment verification.
• Loading, success, failure, and pending states.
• Webhook-based order reconciliation.
• Payment history or order status screen.

15.2 Suggested Folder Structure

src/
  components/
    CheckoutButton.js
    PaymentStatusCard.js
    OrderSummary.js
  screens/
    CheckoutScreen.js
    PaymentStatusScreen.js
    OrderHistoryScreen.js
  hooks/
    useCheckout.js
    usePaymentStatus.js
  services/
    checkoutService.js
    paymentService.js
    orderService.js
  navigation/
    AppNavigator.js
  constants/
    paymentConfig.js

15.3 Implementation Tasks

1. Create the checkout screen and order summary components.
2. Build backend endpoints to create and retrieve orders.
3. Calculate the payable amount using trusted server-side data.
4. Integrate the selected provider's SDK.
5. Send payment results to the backend for verification.
6. Implement webhook signature validation and duplicate-event handling.
7. Display transaction status based on verified backend information.
8. Test failure, cancellation, timeout, retry, and refund scenarios.

15.4 Expected Learning Outcome

After completing this project, you should understand how to connect React Native checkout screens to payment SDKs, coordinate backend operations, verify transactions, handle asynchronous updates, and build a safer end-to-end payment workflow.

16. Common Interview Questions and Answers

Q1. What is a payment gateway?

Answer: A payment gateway is a service that facilitates electronic payment transactions between a merchant application and the payment processing ecosystem.

Q2. What is a payment SDK?

Answer: A payment SDK provides libraries and tools that help developers integrate a provider's checkout experience and payment-related functionality into an application.

Q3. Why is backend integration necessary?

Answer: The backend validates orders, calculates authoritative prices, creates provider orders, protects credentials, verifies payment results, and updates order records.

Q4. Why should payment signatures be verified on the server?

Answer: The client can be modified or manipulated. Server-side signature verification helps establish that the payment response corresponds to an authentic provider transaction.

Q5. What is a webhook?

Answer: A webhook is a server-to-server event notification that allows a payment provider to inform the merchant backend about transaction changes asynchronously.

Q6. What is idempotency in payment processing?

Answer: Idempotency allows repeated requests with the same idempotency key to be handled without unintentionally repeating the same operation, subject to the provider's documented behavior.

Q7. What should happen if the app closes during payment?

Answer: The backend should continue processing provider events. When the customer returns, the app should retrieve the order's verified status rather than assuming the transaction failed.

Q8. Should the app store card details?

Answer: Generally, use a provider's secure payment interface or tokenization features rather than storing raw card information. Follow the provider's instructions and applicable compliance requirements.

Q9. What is the difference between authorization and capture?

Answer: Authorization approves a payment amount according to the payment method and issuer. Capture completes the collection step where the payment method uses separate authorization and capture stages.

Q10. How can duplicate charges be prevented?

Answer: Disable repeated submissions, use server-side idempotency, persist order identifiers, and check the existing payment status before creating another payment attempt.

Q11. What should the app display when verification is delayed?

Answer: It should display a pending or processing message, retrieve the latest order status, and avoid telling the customer that payment definitively failed or succeeded without sufficient evidence.

Q12. How should refunds be handled?

Answer: The backend should authorize the refund request, submit it through the provider's API, track the refund status, process webhook updates, and communicate the result to the customer.

17. Quick Revision Notes

• Payment gateway: Facilitates electronic transactions.
• SDK: Provides integration tools and checkout functionality.
• Backend: Validates orders, calculates totals, and protects secrets.
• Payment workflow: Covers order creation, checkout, verification, and confirmation.
• Signature verification: Helps authenticate provider payment responses.
• Webhook: Communicates asynchronous transaction events.
• Idempotency: Helps prevent duplicate operations.
• Payment states: Represent pending, authorized, captured, failed, and refunded transactions.
• Security: Requires trusted server-side validation and secure credential management.
• Testing: Must include successful, failed, cancelled, delayed, and duplicate-event scenarios.

18. Conclusion

Integrating payment gateway SDKs and payment workflows is an important skill for building React Native applications that support purchases, bookings, and other eligible transactions. A successful integration requires more than opening a checkout screen: it involves backend order creation, secure SDK configuration, server-side payment verification, webhook handling, error management, and reliable order-status updates.

By separating payment UI, hooks, services, and backend responsibilities, developers can build a checkout experience that is easier to maintain, test, and secure. Always use the selected provider's official documentation for SDK setup, transaction verification, and production configuration.

Further learning: Explore the React Native Training course at JustAcademy and register for a course demo.